# Quality and Architecture Remediation Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Make coverage, scenario, CI, and architecture gates measure executable production behavior and fail when their measured universe is empty or incomplete. **Architecture:** One typed gate schema drives both the local runner and generated workflow. Coverage separates repository inventory from instrumented totals. The Babel/resolver graph is the sole architecture authority while TypeScript 7 is unsupported by dependency-cruiser. **Tech Stack:** TypeScript 7, Node.js 24, Babel parser, Vitest 4, Playwright, Gitea Actions. ## Global Constraints - A zero-file or zero-module result is failure, never success. - High-risk changed modules need explicit coverage ownership or an owned, expiring waiver. - Scenario declarations count only when a table-driven test executes all required assertions. - Checked-in workflow content is generated deterministically from the same gate model used locally. - Every enforcement change begins with a failing fixture. --- ### Task 1: Repository-aware risk coverage **Files:** - Modify: `vitest.config.ts` - Modify: `config/testing/risk-coverage.json` - Modify: `scripts/check-risk-coverage.ts` - Modify: `tests/fixtures/coverage/below-threshold.json` - Create: `tests/fixtures/coverage/repository-omission.json` - Create: `tests/unit/risk-coverage.test.ts` - [ ] Add tests asserting `selectedTotal`, `repositoryTotal`, uncovered repository modules, and changed high-risk ownership. A summary covering 14 files while production inventory is larger must fail. - [ ] Run `corepack pnpm exec vitest run tests/unit/risk-coverage.test.ts` and confirm RED because only selected totals exist. - [ ] Enumerate every production `.ts`/`.tsx` module under `src`, exclude declarations/stories/generated files explicitly, and emit both totals. Expand coverage instrumentation to `src/**/*.{ts,tsx}` with documented exclusions. - [ ] Seed the critical registry with HTTP V3, bounded request/response readers, boot bounds, Service Worker lifecycle, scope generation, and release loading. Validate waiver owner, reason, and future expiry. - [ ] Run focused tests and `corepack pnpm test:coverage`; commit with `git commit -m "fix: measure repository-wide risk coverage"`. ### Task 2: Executable HTTP scenario catalog **Files:** - Modify: `tests/mocks/scenarios/catalog.ts` - Create: `tests/integration/http-scenario-catalog.test.ts` - Modify: `tests/mocks/handlers/reference-resources.ts` - Modify: `scripts/check-test-evidence.ts` - Modify: `config/testing/test-evidence.json` - [ ] Define typed expectations for status/outcome/effect/retry/fetch count/media type/body bound/scope fence for every declared scenario. - [ ] Add a table-driven test that executes each operation/scenario pair through `ContractHttpExecutor` and asserts every expectation field. Add a deliberately declared-but-unexecuted fixture and make the evidence checker reject it. - [ ] Run `corepack pnpm exec vitest run tests/integration/http-scenario-catalog.test.ts && node scripts/check-test-evidence.ts` and confirm RED because the current gate counts source tokens. - [ ] Export execution receipts from the test artifact and make the checker compare exact catalog IDs to exact executed IDs; source-token counts become diagnostics only. - [ ] Re-run tests/checker and commit with `git commit -m "test: execute the HTTP scenario catalog"`. ### Task 3: Shared CI gate schema and deterministic workflow generation **Files:** - Create: `scripts/contracts/ci-gates.ts` - Create: `scripts/generate-ci-workflow.ts` - Modify: `scripts/run-ci-gate.ts` - Modify: `config/ci/gates.json` - Modify: `.gitea/workflows/quality-gates.yml` - Create: `tests/unit/ci-workflow-generation.test.ts` - [ ] Add invalid gate fixtures for unknown fields, duplicate IDs, missing artifact schemas, unknown dependencies, and cycles. Add a snapshot test for the full generated workflow plus `--check` drift. - [ ] Run `corepack pnpm exec vitest run tests/unit/ci-workflow-generation.test.ts` and confirm RED because no shared parser/generator exists. - [ ] Parse gates once with strict Zod schemas. Generate every job, dependency, command, environment mapping, timeout, artifact upload/download, and schema validation deterministically. - [ ] Replace regex/token workflow checks with `node scripts/generate-ci-workflow.ts --check`; generated YAML must match byte-for-byte. - [ ] Re-run tests and check mode; commit with `git commit -m "refactor: generate CI workflow from gate contracts"`. ### Task 3b: Semantic validation for every CI evidence format **Files:** - Modify: `scripts/contracts/release-artifacts.ts` - Modify: producer scripts for the remaining generic JSON evidence - Modify: `scripts/lib/ci-artifact-validator.ts` - Modify: `config/ci/gates.json` - Modify: `tests/unit/ci-artifact-contract.test.ts` - [x] Inventory every artifact still mapped to `generic-json-object` and export/reuse the producer's strict schema, including cross-field status/failure/count invariants. Do not treat a non-empty JSON object as semantic evidence. - [x] Replace substring-only JUnit/HTML acceptance with bounded well-formed document validation. Reject DTD/entities, malformed nesting, duplicate/invalid roots, and trailing non-whitespace content. - [x] Add invalid-but-pattern-matching fixtures for all structured kinds and a table proving every configured artifact resolves to a semantic validator. - [ ] Run focused artifact tests, `corepack pnpm check:ci`, types, lint, and diff checks; commit separately so this evidence-quality closeout is independently reviewable. ### Task 4: One authoritative architecture graph **Files:** - Modify: `scripts/check-architecture.ts` - Modify: `config/architecture/layers.json` - Modify: `.dependency-cruiser.json` - Create: `tests/fixtures/architecture/forbidden/contracts-import-application.ts` - Create: `tests/fixtures/architecture/forbidden/feature-adapter-imports-global-adapter.ts` - Create: `tests/unit/architecture-policy.test.ts` - [ ] Add fixtures proving contracts cannot import application/runtime layers, feature adapters cannot import concrete global adapters, unresolved imports fail, cycles fail, and a zero-module root fails. - [ ] Run `corepack pnpm exec vitest run tests/unit/architecture-policy.test.ts` and confirm missing rules/zero-module behavior fail. - [ ] Make the Babel parser plus Node/TS resolver graph authoritative. Keep dependency-cruiser output informational while it sees zero TS7 modules, and explicitly fail authoritative counts of zero modules or zero dependencies in a non-empty source tree. - [ ] Add the two dependency-direction rules to the typed layer policy and ensure aliases/extensions resolve identically to TypeScript. - [ ] Run focused tests and `corepack pnpm check:architecture`; commit with `git commit -m "fix: enforce architecture with the TS7 graph"`. ### Task 5: Test hygiene and production read/write E2E **Files:** - Modify: `vitest.config.ts` - Modify: `tests/setup.ts` - Modify: `playwright.config.ts` - Modify: `playwright.dev.config.ts` - Modify: `playwright.storybook.config.ts` - Modify: `playwright.visual.config.ts` - Create: `tests/e2e/reference-resource-write.spec.ts` - Modify: `scripts/check-test-evidence.ts` - [ ] Add a fixture containing `.only` and a leaking fake timer; assert the gate rejects/isolation restores them. Assert every Playwright config resolves `forbidOnly: true`. - [ ] Add E2E that loads a real mocked GET response, submits POST, verifies request body/header contract, verifies response-rendered resource, then reloads and verifies read-after-write. - [ ] Run focused Vitest and Playwright tests and confirm RED for inherited configs/current shallow E2E. - [ ] Enable Vitest sequence hook that rejects `.only`, restore real timers in common `afterEach`, and centralize a Playwright base config with `forbidOnly: true` inherited by all configs. - [ ] Make E2E evidence require both observed response and observed mutation receipt. - [ ] Re-run supported tests; commit with `git commit -m "test: harden test isolation and read-write E2E"`. ### Task 6: Quality verification - [ ] Run `corepack pnpm check:architecture`. - [ ] Run `corepack pnpm test:coverage`. - [ ] Run `node scripts/check-test-evidence.ts`. - [ ] Run `node scripts/generate-ci-workflow.ts --check`. - [ ] Run `corepack pnpm test:all`, `corepack pnpm check:types`, `corepack pnpm lint`, and `git diff --check`. - [ ] Run browser/E2E gates only when the environment supports them and report exact commands separately.