docs(architecture): refresh explainers and spec to the shipped system
Some checks failed
CI / typecheck + lint + boundaries + test + build (push) Has been cancelled
CI / Playwright e2e (push) Has been cancelled
CI / Storybook smoke tests + visual regression (push) Has been cancelled
CodeQL / Analyze (javascript-typescript) (push) Has been cancelled
Coverage snapshot / snapshot (push) Has been cancelled
Release Please / release-please (push) Has been cancelled
Sentry PII guard (R31) / pii-guard (push) Has been cancelled
Mutation testing (nightly) / mutate (push) Has been cancelled
Library trace revalidation (weekly) / revalidate (push) Has been cancelled

Bring docs/architecture/ in line with the current repo:

- feature-conformance-explainer.html: drop the "proposed / not yet
  implemented" framing — the system is shipped. Four enforcement points
  become five (adds `pnpm fallow` as the whole-codebase audit). Manifest
  playground shows `coverage`, `analyticsEvents`, `rateLimit`,
  `requiresConsent`. Milestone / anchor / open-question sections kept
  but marked historical.
- agent-first-workflow-and-conformance.md: four → five enforcement
  layers; layer table gains the Fallow row.
- di-explainer.html: bind-production sample rewritten to show
  wireUseCase() + assertFeatureConformance() + the full wrapper stack
  (span → capture → audit? → analytics? → consent? → rateLimit?).
- data-flow-explainer.html: same bind-production refresh for the
  data-flow narrative.
- audit-and-compliance-explainer.html: AuditAction enum 6 → 10 values
  (CONSENT_GRANT / WITHDRAW / RESTRICT / UNRESTRICT);
  BindProductionContext example gains analytics, consentFactory,
  rateLimit.
- vertical-feature-spec.md: §5 layout lists the 8 optional cores plus
  core-testing; §9.5 hedges the turbo.json snippet against the live
  file; §10.4 drops the dated "360 tests" metric for the ADR-020
  coverage architecture; §11 gains a historical lead-in pointing at
  docs/decisions/ as the canonical 25-ADR set.
This commit is contained in:
2026-05-23 14:06:03 +02:00
parent b455ae8018
commit 0748f9e5ed
6 changed files with 251 additions and 51 deletions

View File

@@ -400,7 +400,7 @@ The reviewer agent **explicitly checks the task's `Out of scope` section against
## Conformance system integration
The four enforcement layers (detailed in [`feature-conformance-explainer.html`](./feature-conformance-explainer.html)):
The five enforcement layers (detailed in [`feature-conformance-explainer.html`](./feature-conformance-explainer.html)):
| Layer | Latency | Catches |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
@@ -408,6 +408,7 @@ The four enforcement layers (detailed in [`feature-conformance-explainer.html`](
| AST-aware ESLint | <1s | manifest code drift; undeclared `bus.publish` / `auditLogger.log`; required cores not installed |
| Boot assertion (`assertConformance`) | ~3s | binding type-casts that hid unwrapped factories; manifests edited without rebinding |
| CI drift gate (`pnpm conformance`) | ~120s | orphan event consumers; scaffold drift from generator; required-cores workspace mismatch |
| Fallow audit (`pnpm fallow`) | ~3060s | whole-codebase dead exports, duplicate code, circular deps, complexity hotspots |
### How conformance interacts with tasks
@@ -417,7 +418,7 @@ When a task adds an audit emission (e.g. `audits: ["user.created"]`):
2. The binding's branded slot type _now_ demands `Audited<F>` TS2322 if the wrapper is missing
3. Agent adds `withAudit(...)` in `bind-production.ts` TS goes quiet
4. Agent adds `auditLogger.log(...)` in the use-case factory ESLint goes quiet
5. Pre-commit `pnpm conformance` confirms all four layers pass
5. Pre-commit `pnpm conformance` confirms all five layers pass
6. PR submitted
Each step gives sub-second feedback. The agent's iteration loop is dominated by think + write, not by waiting for feedback.
@@ -653,7 +654,7 @@ These are explicitly deferred until the tier that needs them:
This design is "done" when:
- [ ] `docs/work/` exists with templates, `_state.json` schema, README
- [ ] Conformance system v1 is implemented through all four enforcement layers
- [ ] Conformance system v1 is implemented through all five enforcement layers
- [ ] All five feature packages have manifests
- [ ] All three apps run `assertConformance` at boot
- [ ] `pnpm conformance` is a CI gate