feat: buildable + convergent reconstruction PRDs (v0.5.0)#3
Merged
Conversation
Both fronts (reverse-engineer-from-code and from-scratch) now capture the *contracts* a fresh agent needs to rebuild a unit correctly — not just a faithful-looking sketch — and a deterministic gate enforces it. Closes the gaps a multi-agent audit found: contracts named but unspecified (enum members, function signatures, external-service shapes, rate limits, i18n copy) and internally contradictory plans (an anonymous write to an owner-FK table). Engine: - --check buildability gate (src/check.ts): exits non-zero on unresolved 🧠 callouts / "fill this in" placeholders, a feature referencing an undocumented entity/operation, a feature PRD missing its spine, or an uncovered locale. - validatePlanConsistency (src/scratch.ts), wired into --scratch: fails fast on dangling feature->entity/interface refs, empty enums, or a field enumRef to an undefined enum; warns on a public/anonymous write to a caller-owned FK (owner/author/sender) so the scratch path is buildable by construction. - Extended plan schema (all optional, backward-compatible): enums, services, policies, i18n.messages catalog, interface input/output/sideEffects, dataModel field enumRef + entity indexes/uniques, feature.writes. - Templates render Enums & domain types, External services, Cross-cutting policies, the i18n message catalog, per-operation contracts, a Writes line, and a hardened Definition of Done (write satisfiability, enum enumeration, source-string i18n coverage, --check). Docs & fixtures: - New references/buildability-checklist.md (eight contract categories + the consistency self-review + the gate); analysis/scratch playbooks, plan-schema doc, PRD templates, SKILL.md (v0.5.0), README, DOCUMENTATION updated. - Realigned tests/fixtures/scratch-plan/medic.plan.json to mirror the real repo (real notifications/profileViewsLog shapes, anonymous-capable contactRequests, NextAuth adapter tables, 21 entities, 101 interfaces, 20 enums, 6 services, 10 policies) so the from-code and from-scratch paths converge. - parity-medic asserts buildability-by-construction (0 consistency errors/warnings) + scaffold richness + locale parity. 184 tests pass; tsc --noEmit clean; parity:medic PASS. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The multi-agent re-verification reproduced a defect: on the code path, --check passed a contract-empty tree. Its reference-integrity gate reads inv.dataModel/inv.interfaces/feature.entities — all empty in code mode — so it iterated empty sets and passed vacuously. Stripping every callout and gutting the architecture docs to bare headings still returned "PASS — buildable". - Add contract-substance gates to --check: DATA-MODEL.md must declare >=1 entity, INTERFACES.md must declare >=1 operation, and every feature PRD must carry real content (not just spine headings). Detection is shape-agnostic (### blocks, filled tables, or path bullets), so it works on both the code and scratch paths. A gutted code-mode tree now fails with explicit "declares no entities/operations". - Add a 9th buildability contract category — shared & owned UI components (props, states, validation, primitives) — covering the residual open finding that component contracts like BookingCard/AvailabilityCalendar were never demanded. Updated "eight"->"nine" across SKILL.md and the playbooks. 188 tests pass (4 new substance tests); tsc clean; parity:medic PASS. Re-verified: the reproduced gut-to-empty exploit now exits non-zero. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Tagline now states the buildable bar + greenfield mode. - "What it produces" notes the new architecture-doc sections (enums, external services, cross-cutting policies, i18n message catalog, per-operation contracts). - Validation section explains --check fully: structural failures incl. the gutted data-model/interface/feature gates, the nine contract categories, and greenfield plan-consistency validation. - Greenfield section notes the plan pre-fills enums/services/policies/catalog. - Fixed: the --merge/--summary standalone paragraph was orphaned under Validation; moved it back under Bundling. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Both fronts — reverse-engineer-from-code and from-scratch — now capture the contracts a fresh agent needs to rebuild a unit correctly, and a deterministic gate enforces it. Closes the gaps a multi-agent audit found: contracts named but unspecified (enum members, function signatures, external-service shapes, rate limits, i18n copy) and internally contradictory plans (an anonymous write to an owner-FK table). The from-scratch plan and the from-code path now converge on the same product.
Changes
Engine
--checkbuildability gate (src/check.ts): fails on unresolved🧠callouts / placeholders, dangling entity/operation references, a feature PRD missing its spine, uncovered locales, and a gutted (empty) data model / interface surface / feature PRD.validatePlanConsistencywired into--scratch: fails fast on dangling refs / empty enums; warns on a public/anonymous write to a caller-owned FK (owner/author/sender) — buildable by construction.enums,services,policies,i18n.messagescatalog, interfaceinput/output/sideEffects, entityindexes/uniques+ fieldenumRef,feature.writes.Docs & fixtures
references/buildability-checklist.md(nine contract categories incl. shared/owned UI components) + the consistency self-review + the gate.tests/fixtures/scratch-plan/medic.plan.jsonrealigned to mirror the real repo (21 entities, 101 interfaces, 20 enums, 6 services, 10 policies; correctnotifications/profileViewsLogshapes, anonymouscontactRequests, NextAuth tables) so the two paths converge.scripts/parity-medic.mjsasserts buildability-by-construction + scaffold richness + locale parity.Verification
tsc --noEmitclean · 188 tests (40 new) ·parity:medicPASS ·check:buildreproducible.--checkpassed a contract-empty tree) was then fixed by the substance gates in this PR and confirmed closed.