tech-log-frontend/docs/superpowers/plans/2026-08-01-quality-architecture-remediation.md

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

• 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.

• 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.

• 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.