Specification-Governed Design (SGD)
Feature Overview
SGD is the PPP development methodology: every product decision is expressed as an English-language spec before any code is written. Specs govern what the AI tooling builds, provide a stable anchor for cross-referencing, and act as the single source of truth for features, acceptance criteria, and current implementation status. The process was formally adopted in April 2026 as the team scaled AI-assisted development.
Open Questions
| # | Question | Proposed answer / status | Ref |
|---|---|---|---|
| — | No open questions. |
Closed Questions (0) — click to expand
| # | Question | Resolution | Ref |
|---|
Acceptance Criteria
Docs portal
✅
sgd.docs.single-source-of-truth— PPP Docs portal is the single source of truth for features, ACs, and implementation status. Verified #6440: the VitePress portal underdocs/site/(configdocs/site/.vitepress/config.ts, landingdocs/site/index.md) publishes all 33 feature specs fromdocs/features/*.md;docs/site/.vitepress/cache/features-counts.jsonis a build-time cache of open issue counts per feature label, regenerated bysync-features.mjson every build; each spec carries machine-readable front-matteracs:with per-ACstatus, an## Acceptance Criteriasection with ⏳/✅ markers traceable to transcript sources, and a## Current Statustable; the AC index generator (docs/site/scripts/build-ac-index.mjs→_ac-index.json,pnpm build:ac-index) cross-indexes every AC for thetools/mcp-ac-searchserver;docs/site/scripts/sync-features.mjsrenders the Spec Index + per-spec pages and Change Log fragments; and the spec-drift Tier-1 CI gate (docs/site/scripts/check-spec-drift.mjs, #6515) enforces that code cannot diverge from the specs — making the Docs portal the authoritative, enforced source of truth.†✅
sgd.docs.user-journey-persona-map— PPP Docs includes user journeys, personas, and a screen-level user story map for demo use.†Implementation: The PPP Docs portal ships three companion documents under
docs-github/user-journeys/that satisfy this AC: (a)personas.md— the persona catalogue (also surfaced in repo atdocs/features/_personas.mdfor AC tagging via thepersonas:frontmatter field), (b)user-flow-diagram.md— end-to-end user journeys, and (c)user-story-map.md— the screen-level user story map for demo use. Thedocs/site/scripts/copy-journeys.mjsscript copiesdocs-github/user-journeys/intodocs/site/journeys/at build time so the VitePress portal resolves/journeys/*locally and on the published site. Theindex.mdin that folder acts as the entry point for demo walk-throughs.✅
sgd.docs.anchor-hashes— every spec section has a stable unique anchor hash for AI and human cross-referencing.† (#6442) — implemented as kebab-case dot-delimited AC codes (e.g.sgd.docs.anchor-hashes) parsed bydocs/site/scripts/build-ac-index.mjs(regex[a-zA-Z][\w-]*(?:\.[\w-]+){1,}) and resolved bytools/mcp-ac-search/server.mjstools (get_ac,find_by_code_path,search_acs).✅
sgd.docs.drift-gate-ownership-attribution— the BLOCKING spec-drift gate faults only the spec that genuinely owns a changed file. A mis-attribution is treated as a defect in the gate, not as work for the author, because the "fix" it demands writes cross-domain noise intodocs/features/— Matt's source of truth — and because a gate that cries wolf trains reviewers to reach for thespec-unchangedbypass reflexively, which is how a real drift eventually slips through. Three ownership rules are enforced bycheckDriftindocs/site/scripts/features-data.mjs: (a) fragment and generated artefacts underdocs/features/are owned by no spec —.changelog/**and.sources/**(FRAGMENT_DIR_PREFIXES, #5273/#8084) and any_-prefixed file such as_sources.json/_ac-index.json(isCrossCuttingFeatureFile, #8036) — sosgd.md's broaddocs/features/**glob never claims them; (b) precise ownership — when several specs match one file, only the spec whose glob pins the most literal path segments is faulted (bestGlobSpecificity, #8036), so a narrow claim beats a broad directory glob (this is what re-attributes the surgical-logbook import wizard services fromexportable-reports.md'sservices/reports-and-export/**tologbook.md); and (c) shared-infrastructure code — an exact-path, individually justified list (SHARED_INFRASTRUCTURE_PATHSindocs/site/scripts/features-config.mjs, consumed viaisSharedInfrastructureFile) exempts multi-feature registration points that no single spec can own — currently the single pathapi/backend-ppp/entrypoints/scheduler-lambda.ts, the cron-registration entrypoint every scheduled job in the product registers into. A spec may still cite an exempted path (the citation stays useful for navigation andfind_by_code_path); the gate simply refuses to attribute the file to it. Rules (a) and (b) do not weaken detection at all. Rule (c) carries one bounded, documented residual gap: changes to what a scheduled job does still block (that behaviour lives in a spec-owned file —timesheets.mdclaimsmonitorGeofencePreferences.tsby exact path), but changes to whether or when a job is registered are visible only in the exempt entrypoint and are not caught here. The compensating control is that entrypoint's own test sibling,api/backend-ppp/entrypoints/scheduler-lambda.test.ts, which asserts every registered processor is invoked — it is deliberately not exempted, so a PR removing a registration and its assertion together still fails CI. Rule (d) test artefacts (#11997) — files that VERIFY behaviour rather than DEFINE it (*.test.*,*.spec.*,*.steps.ts,*.stories.*,__tests__/,__mocks__/,test-utils/, viaisTestArtefact) are owned by no spec. A spec glob is broad by design (modules/wellness/**) so it sweeps in the tests beside the source it owns; changing only a test then demanded a product-spec update, which alters no acceptance criterion and writes test-mechanics prose into Matt's source of truth. Measured against the real shipped specs: 880 of 1925 test artefacts (45.7%) tripped the gate standalone, each costing aspec-unchangedround-trip; after the carve-out, 0 do, while 1374 source files still trip — detection is unchanged..featurefiles are deliberately NOT excluded: they are the living, executable acceptance criteria, so they behave as spec content (they are currently claimed under the separatebdd-features:front-matter key rather thancode-paths:, so the gate does not match them today either way — the exclusion is withheld so a spec globbing one intocode-paths:keeps working). One explicit exception guards rule (c): the test sibling of a shared-infrastructure path stays matchable (isSharedInfrastructureTestSibling).scheduler-lambda.test.tsis the ONLY compensating control for cron REMOVAL on an entrypoint rule (c) deliberately exempts, so carving it out as "just a test" would have turned that documented bounded gap into an unbounded one — a must-stay-red test pins it. The residual gap for rule (d), stated plainly: a PR changing ONLY a test file no longer demands a spec update, so a behaviour change smuggled entirely into a test helper is not caught here; it cannot alter product behaviour without also touching a non-test file, which still trips.
Each rule carries must-stay-red regression tests in docs/site/scripts/features-data.test.mjs, alongside a suite asserting the rules against the real shipped docs/features/*.md configuration rather than fixtures, and tripwires that pin the exemption set and fail if a listed path stops existing — so growing the list is always a conscious, reviewed edit.†‡ (#10975)
✅
sgd.docs.drift-gate-code-paths-live— the BLOCKING spec-drift gate can only guard code its globs can actually see, so acode-paths:glob that resolves to nothing is a silent hole: the gate reports SUCCESS having inspected NOTHING for that spec, and the green tick everyone reads as "the spec is in sync" in fact means "we could not see anything". That is strictly worse than having no gate.node docs/site/scripts/check-code-paths-live.mjsruns BEFORE the drift check inspec-drift.yml(and pre-commit via lint-staged) and hard-fails on three conditions: (a) dead-glob — acode-paths:glob matching zero tracked files atHEAD; (b) accidental-match — a.../**/<Name>/**glob where no tracked directory is actually named<Name>, so it "matched" only because**collapsed into a neighbouring segment's suffix (instances/ppp/src/**/Admin/**survived the reorganisation solely by hitting.../hospital-admin/HospitalApproverAdmin/, guarding one incidental directory instead of the Admin module it names); and (c) planned-now-live — acode-paths-planned:glob that has started matching. Each is a hard failure, never a warning, because the whole lesson being applied is that an advisory signal inside a green run is invisible. A spec that legitimately describes unbuilt code declares those globs undercode-paths-planned:rather than deleting them — excluded from drift matching (phantom code cannot drift), required to match zero files, and failed by (c) the day the code lands so the glob is promoted back intocode-paths:instead of forgotten; without (c) the hatch would simply become the new silent hole. Deleting a dead glob to go green is explicitly the wrong fix and the gate's failure text says so. Backfill in the same change re-pointed 103 dead globs across 25 specs at their real post-ADR-0003 homes.†‡ (#11030)✅
sgd.docs.drift-gate-parser-blindness— the code-paths liveness gate refuses to pass when the front-matter parser has silently lost specs.checkCodePathsLive'sokisviolations.length === 0, vacuously true over an empty set, so a BOM on a spec file, a CRLF change, or aparseFrontMatter/list-item regression zeroes a spec'scode-paths:and the gate reports success — the exact silent hole it exists to close, one level up. Crucially this is invisible to the dead-glob rule: that rule classifies globs which were DECLARED, and a spec whose front matter failed to parse declares nothing, so blindness by omission is structurally undetectable by any rule inspecting declarations. The gate therefore compares the parser's view against an independent raw byte scan of the same files (rawSpecsDeclaringCodePaths), failing when disk shows more specs declaring paths than the parser produced. The independence is the mechanism, not a detail: the first attempt compared two projections of the SAME parsed array and was unsatisfiable —checkedincrements per declared glob, so any spec declaring paths forceschecked >= 1— and a real BOM regression still exited 0 green. It catches total blindness (all 45 specs BOM'd) and partial (5 of 45), which the unsatisfiable form could never see. The oracle measures the same property as the parser — at least one entry, socode-paths: []and a barecode-paths:are correctly not counted — and a tripwire test pins the two readers to agree on the shipped specs, since a disagreement on a healthy tree would fail the build on correct input.†‡ (#11085)✅
sgd.docs.ac-index-all-citations— the AC index records everysrc:citation on an AC line, not just the first, so citation order never decides what is traceable. An AC accumulates citations as it evolves — the originating issue, then the decision that reshaped it — andbuild-ac-index.mjsread them with.match(), so adding a second citation to an AC silently displaced the one already there: the spec markdown still showed both to a human reading it, while the index behind/sgd:*tooling andmcp__ppp-ac-searchknew about only one. The failure was silent by construction — a displaced citation is not a broken one, so theValidate AC indexgate stayed green, and the only reason it was ever noticed (during PR #10983) was an author diffing the validator's "sources not cited by any AC" list against theuatbaseline, a check nobody is required to run. The extractor now collects every†<abbr>on the line (‡code:implementation pointers are still deliberately excluded), dedupes repeat ids, and resolves each independently intoacs[code].sources; a broken citation outranks a resolved one when scoring AC integrity, so an AC citing one good and one typo'd source still fails--validaterather than passing on the strength of its first citation. Un-masking this on the shipped specs recovered 54 previously-displaced citations across 43 multi-citation ACs and reclaimed 35 sources that had been reported as cited by no AC — including 4 citations pointing at source ids that had no.sources/fragment at all, genuinely broken citations the displacement had been hiding from the CI gate (fragments added in the same PR). The positional workaround the bug forced on authors ("put the new<abbr>second") is retired.†‡ (#10985)✅
sgd.docs.changelog-fragment-parse-integrity— a Change Log fragment is either parsed in full or the build fails naming the file; frontmatter is never silently discarded into a blank row. The fragment loader's own comment called it a tiny YAML subset parser, and it recognised no block scalar header at all:change: >-stored the marker>-as the value, then dropped every continuation line, because thekey:regex is anchored and an indented line never matches it — so the miss fell through a barecontinue. This is the worst failure mode a governance record can have, because the row is still present:docs/site/features/ppp-passport.mdpublished| 2026-05-13 | >- | #6198, #5948 | >- |where the audit content should have been, and nothing looked missing. Re-deriving the blast radius againstHEAD(rather than trusting the issue, per the Verify-Epic-Scope rule) showed it was 143 blanked rows across 17 rendered specs — every block-scalar fragment in the tree — not the single>-row the issue reported; the folded>form used by the other 142 fragments was broken identically, e.g.timesheets.mdpublished a>cell for #8114. The parser now understands|,|-,|+,>,>-and>+with real folding, paragraph breaks and chomping, plus a flow sequence wrapped onto the following line (issues:then the bracketed list) — a valid-YAML form already in the tree whose silent loss the fail-loud rule exposed on its first run, and which had been publishing an onboarding row with no issue references at all. Two rules make the class unrepeatable rather than just fixing today's row: (a) refuse what you cannot read — any uninterpretable frontmatter line, including a block scalar header outside the supported set such as an explicit indentation indicator, throws with the fragment path and line number, because>-support alone would leave the next unsupported form to fail just as quietly; and (b) assert on the rendered output —assertNoBareScalarMarkerCellsre-scans every generated spec before it is written and fails the docs build if any table cell is a bare marker, catching the paths the parser cannot guard (a hand-written inline row, a future loader, a regressed parser) rather than leaving them to be spotted by eye.†‡ (#11031)✅
sgd.docs.spec-vue-guard-fatal-code-coverage— the spec Vue-compile guard (docs/site/scripts/check-spec-vue.mjs) fails on every Vue compiler error class that actually breaksBuild VitePress. The guard renders each generated spec and collects the compiler's errors, then filters them against an allow-list of fatal codes — so a fatal error the compiler does report is silently discarded if its code is missing from that list, and the guard prints a green pass. This is the same failure shape as [[sgd.docs.drift-gate-parser-blindness]] and #11004 one level down: not a check that failed to run, but a check that ran, saw the defect, and threw the evidence away.FATAL_CODEScarriedX_MISSING_END_TAG(24) but not its exact mirrorX_INVALID_END_TAG(23) — a closing tag with no matching open tag. That gap shipped a brokencpd.mdin #12033 and took the docs site down on everyuatpush until #12041: an<abbr title="…">whose title backslash-escaped its inner quotes, which is not an HTML escape, so the attribute ended at the first inner quote, the stray">closed the tag, and the real</abbr>was orphaned. The regression test feeds real spec markdown through VitePress's owncreateMarkdownRendererinto the guard rather than asserting on hand-written HTML, because a test that constructs the HTML it asserts on proves nothing about an escaping bug — the self-constructed-tautology anti-pattern named ingate-integrity.md; its negative control is the"-escaped form, so it cannot pass by flagging everything.†‡ (#12041)✅
sgd.docs.link-check-covers-every-built-page— the docs-site 404 check inspects every built page, and proves it did.pages.yml's "Verify no internal 404s" step asserted in its own comment that it would "Crawl every built page";crawl-docs.mjsin fact seeded its queue with/and grew it only by regexing server-rendered<a href>out of each page. VitePress renders nav and sidebar client-side, so any page not linked from another page's in-content prose was unreachable: measured against a real build, 133 of 253 built pages (52.6%) were never visited, and a broken in-content link on any of them was reported asAll internal links resolvedwith exit 0. Same family as [[sgd.docs.drift-gate-parser-blindness]] and [[sgd.docs.spec-vue-guard-fatal-code-coverage]] — the always-satisfied predicate named ingate-integrity.md— and it sat green throughout the #12041 docs outage, in the very workflow that was failing. Two rules make the class unrepeatable rather than just fixing today's blind spot: (a) enumerate, don't discover — the crawl frontier is the built artefact list (<dist>/**/*.html), exactly the set the deploy publishes, which cannot collapse the way link discovery did; in-content link extraction still runs per page on top of that, so a broken hand-written link to a never-built page is still caught (enumeration replaces the frontier, not the link checking, and the two halves are asserted separately); and (b) assert a floor — the run fails when pages visited drops belowMIN_PAGES_RATIOof the built file count, derived from the count rather than a magic number, so a regression to a near-empty frontier fails loudly instead of passing silently. The built404.htmlis exempted from the 404-title check it would otherwise trip on every run, asserted in both directions so the exemption cannot swallow a real break.†‡ (#12057)
Process
✅
sgd.process.spec-driven-ai— all product development is driven by English-language specs that govern AI tooling and prevent code drift.†Implementation: This AC is the foundational SGD principle and is enforced across the entire engineering workflow.
docs/features/*.mdis the authoritative English-language source of truth for every feature —CLAUDE.mdmandates "Before modifying any named feature, read its spec file indocs/features/" and codifies the BDD-First Rule (the scenario IS the acceptance criteria; order is always scenario first, implementation second). The spec-drift gate (docs/site/scripts/check-spec-drift.mjs, wired into CI viadocs/site/scripts/check-spec-drift.test.mjs) detects implementation that has drifted from the spec and blocks merges. The/team-pipeline,/batch-pipeline,/implement-issue, and/pipelineorchestrators (.claude/commands/*.md) all read the spec file first and require an AC reference in every issue. Thesgd-gap-analysis.mjsscript emitssgd:gapissues directly from English AC paragraphs, so the AI tooling is governed by the spec rather than the other way around. The transcript audit protocol (docs/features/_sgd-audit-protocol.md) ensures every new AC is traceable to a specific paragraph in a raw Dev Session transcript — preventing inferred or hallucinated requirements from entering the spec.✅
sgd.process.must-have-classification— each feature carries a formal must-have / nice-to-have classification per demo scope.†Implementation: Every
docs/features/*.mdspec carries two frontmatter fields that together encode the must-have / nice-to-have classification:wave(Now|Next|Later) andpriority(integer ranking from Matt's Notion).wave: Nowmeans must-have for the current demo scope;wave: Nextorwave: Latermeans nice-to-have. Defaults are inherited from the feature'scapabilitygrouping viadocs/site/scripts/capabilities-config.mjs(each capability declares a defaultwave), and individual specs may override by settingwavedirectly in their frontmatter. Thedocs/site/scripts/features-data.mjsloader resolves the effective wave/priority for every spec and surfaces both on the rendered docs portal — so the demo-scope classification is visible per feature and machine-readable for the AC index. The field convention is documented indocs/features/_spec-template.md.✅
sgd.process.critical-classification— decisions are classified as critical or non-critical to enable safe AI autonomy on low-risk items.†Implementation: The
/team-pipelineorchestrator encodes the critical / non-critical split as hard stops in every implementation agent's prompt. Two decision points are flagged as critical and pause for explicit pass criteria: (1)pr-issue— verifies and enforcesfixes #Nlinkage between PR and issue before any review work proceeds; (2)pr-review— runs a full code review and requires every finding to be fixed in code, then a label swap topr-reviewed, before merge is permitted. Everything else is delegated to autonomous AI action: choosing changelog fragment filenames, applying labels (enhancement,size:s,spec-unchanged,pr-reviewing), formatting commit messages, picking which fragment file to drop a CPD or wellness scenario into, resolving inline merge conflicts on adjacent ⏳→✅ flips, and squash-merging once both hard stops pass. The critical / non-critical labels are explicit in the agent prompt copy (see.claude/skills/team-pipeline-agent-template/SKILL.md— "Hard stops"), and the gating skillspr-issueandpr-reviewcarry "HARD STOP 1" and "HARD STOP 2" in their own descriptions. This split is what makes the pipeline safe to run unsupervised across N parallel agents without Matt or Rob reviewing every PR mid-flight.✅
sgd.process.issue-clustering— issues are resolved in functional clusters, not individually; human-readable checks run before each cluster.†Implementation: The
/team-pipelineand/batch-pipelineorchestrators (.claude/commands/team-pipeline.md,.claude/commands/batch-pipeline.md) operationalise this AC by grouping related GitHub issues — typically a feature's outstandingsgd:gapcluster, or a slice of acceptance criteria from a singledocs/features/<slug>.md— and flowing them through N parallel implementation agents under one feature branch. Before each cluster runs, the human-readable checks are: (a) the spec file's English acceptance criteria indocs/features/, (b) the matching.featureBDD scenarios ininstances/ppp/e2e/bdd/features/, and (c) the/pr-issue+/pr-reviewhard stops (see.claude/commands/pr-issue.md,.claude/commands/pr-review.md) that gate every PR before merge. Thesgd-gap-analysis.mjsscript (pnpm sgd:gap) emits the cluster ofsgd:gap-labelled issues that feed each batch, making the clustering itself spec-driven rather than ad-hoc bug-fix triage.
Notion workflow
✅
sgd.notion.feature-page-framing— Notion feature pages document purpose, global implications, and business framing for dual internal/investor use.†Implementation: Matt authors every named feature as a page under the Notion Features parent. Each Notion feature page carries (a) the feature's purpose, (b) its global implications across personas and adjacent features, and (c) business framing suitable for both internal engineering use and external investor communication. Engineering treats those pages as read-only context (see CLAUDE.md — "Matt's Notion Feature pages are READ-ONLY for engineering") and translates them into the spec files under
docs/features/*.mdwith acceptance criteria, BDD scenarios, and a change log. This dual-surface arrangement — narrative framing in Notion, machine-checkable AC in the repo — is the contract that satisfies this AC.
Current Status
| Sub-feature | Status | Notes |
|---|---|---|
| Docs portal — single SOT | ✅ Built | VitePress portal + spec front-matter + AC index + drift gate (#6440) |
| User journey / story map | ✅ Verified | docs-github/user-journeys/ — personas, user-flow-diagram, user-story-map (#6441) |
| Anchor hashes | 📋 Specified | ACs extracted from transcripts |
| Spec-driven AI process | 📋 Specified | Formally adopted 2026-04-21 |
| Must-have classification | ✅ Verified | wave + priority frontmatter on every spec (#6444) |
| Critical classification | ✅ Verified | /team-pipeline hard stops (pr-issue, pr-review) gate critical decisions; others run autonomously (#6445) |
| Issue clustering | ✅ Verified | /team-pipeline + /batch-pipeline orchestrators (#6446) |
| Notion feature-page framing | ✅ Verified | Notion pages own narrative framing; repo specs own AC (#6447) |
| AC traceability gate | ✅ Built | CI fails a built AC with no scenario or an unbuilt AC with no issue; baseline ratchet (#12885) |
Open issues on label:feature:sgd — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Open GitHub Issues
| # | Title | Status | Priority |
|---|---|---|---|
| — | No open issues yet |
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-04 | AC traceability gate: check-ac-traceability.mjs fails CI when a built AC has no non-WIP scenario or an unbuilt AC has no tracking issue; existing gaps frozen in _ac-traceability-baseline.json | #12883, ##12885 | Rob, 4 Oct 2026: be 100% sure every spec AC is either proven in code or tracked as work |
| 2026-08-30 | The docs-site 404 check takes its crawl frontier from the built artefacts (dist/**/*.html) instead of following server-rendered anchors, still extracts in-content links per page, and fails when pages visited drops below 90% of the built file count. | #12060, #12057 | VitePress renders nav and sidebar client-side, so the anchor-following crawler reached 120 of 253 built pages — 133 (52.6%) were never visited, and a broken in-content link on any of them reported "All internal links resolved" and exited 0. The step's own comment claimed it crawled every built page. It sat green throughout the #12041 docs outage, in the very workflow that was failing. Enumeration replaces the frontier only, not the link checking, so a broken link to a never-built page is still caught; the page floor is the specific guard against a future regression back to a near-empty frontier. |
| 2026-08-30 | The spec Vue-compile guard (check-spec-vue.mjs) now treats X_INVALID_END_TAG (Vue compiler code 23) as fatal, alongside the structural codes 24/25/27 and the interpolation code 46 it already covered. | #12052, #12041 | Code 23 is the exact mirror of the X_MISSING_END_TAG (24) the guard was built for, and its absence from FATAL_CODES was a silent hole: a spec whose <abbr> title backslash-escaped its inner quotes rendered to an orphaned closing tag, the guard rendered the page and the compiler DID report the fatal error, and the filter discarded it. The guard printed a green pass and the break merged, taking down Build VitePress on every uat push from #12033 until #12041. No acceptance criterion changes — this widens an existing guard to the class it already claimed to cover. |
| 2026-08-29 | Spec-drift ownership gains rule (d): test artefacts (.test., .spec., *.steps.ts, .stories., tests/, mocks/, test-utils/) are owned by no spec. .feature files stay matchable as executable ACs, and the test sibling of a shared-infrastructure path stays matchable as #10975's compensating control. | #12000, #11997 | Broad code-paths globs swept in the tests beside the source they own, so 880 of 1925 test artefacts (45.7%) tripped the gate standalone, each costing a spec-unchanged round-trip for a change that alters no acceptance criterion. After the carve-out 0 do, while 1374 source files still trip. A first blanket version broke #10975's must-stay-red test by swallowing scheduler-lambda.test.ts, the only signal for cron removal on a deliberately-exempt entrypoint; that file is now explicitly re-included. |
| 2026-07-27 | Code-paths liveness gate now compares the front-matter parser against an independent raw byte scan, failing when the parser has silently lost specs. | #11093, #11085 | A BOM or parser regression zeroed a spec's code-paths and the gate reported success. The first attempt compared two projections of the same parsed array and was unsatisfiable, so a real regression still exited 0 green. |
| 2026-07-27 | Changelog fragment frontmatter is now parsed in full, or the docs build fails naming the file and line. The loader recognised no YAML block scalar header at all — it stored the marker as the value and dropped every continuation line, because the anchored key regex never matches an indented line and the miss fell through a bare continue. Re-derived against HEAD, that had blanked 143 Change Log rows across 17 rendered specs (every block-scalar fragment in the tree), not the single strip-chomped row the issue reported; the plain folded form used by the other 142 fragments was broken identically. The parser now supports literal and folded blocks with all three chomping indicators, with real folding and paragraph breaks, plus a flow sequence wrapped onto the following line. Anything it cannot interpret — including a block scalar header outside the supported set — now throws with the fragment path and line number, and a new assertNoBareScalarMarkerCells scan re-checks every generated spec before it is written. Adds acceptance criterion sgd.docs.changelog-fragment-parse-integrity and 9 node --test cases, both fail-loud paths included. | #11068, #11031 | Silent corruption of the audit trail the Change Log exists to be. The failure left the row present, so nothing looked missing to a human reading the published governance record while the content sat intact in the fragment file. Supporting the one reported marker form alone would have fixed today's row and left the next unsupported form to fail just as quietly, so the fix is fail-loud first and marker support second. Turning the bare continue into a throw immediately surfaced a second silent drop the same class had been hiding — a valid wrapped flow sequence in an onboarding fragment that had been publishing its row with no issue references at all. |
| 2026-07-26 | The AC index now records EVERY src: citation on an AC line instead of only the first. build-ac-index.mjs extracted citations with .match(), so adding a citation to an AC that already had one silently displaced the existing one — the spec markdown still showed both to a human while the index behind /sgd:* tooling and mcp__ppp-ac-search knew about only one, with no error and a green Validate AC index job (a displaced citation is not a broken one). extractACs now collects every †-marked <abbr> via matchAll, dedupes repeat ids, and returns citations[] + transcripts[] arrays in place of the single sourceId/transcript scalars; ‡ code: implementation pointers stay excluded as before. Each citation resolves independently into acs[code].sources, and a broken ref outranks a resolved one when scoring integrity — at BOTH the per-AC verdict and the per-feature cited_count/integrity_score, so the two records can never disagree — and an AC citing one good source and one mistyped source still fails --validate. Adds acceptance criterion sgd.docs.ac-index-all-citations and 8 node --test cases (6 unit, 2 end-to-end through --validate), all proven red against the unmodified origin/uat script. | #10992, #10985, #10983 | Silent traceability loss on the measure the AC index exists to produce (SM-1). Un-masking recovered 54 previously-displaced citations across 43 multi-citation ACs (665 -> 719 resolved citation entries) and dropped "sources not cited by any AC" from 85 to 50. It also exposed 4 citations naming source ids with no .sources/ fragment at all (issue-7750, issue-8490, issue-9140, issue-10623) — genuinely broken citations the displacement had been hiding from the CI gate; fragments added in the same PR. The bug was found during PR #10983 only because that author diffed the validator orphaned-source list against the uat baseline, a check nobody is required to run, and the positional workaround it forced ("place the new abbr second") broke again on a third citation or any reorder — that workaround note is removed here. |
| 2026-07-26 | Spec-drift gate now faults only the spec that truly owns a changed file — added a shared-infrastructure carve-out for multi-feature registration points, documented as AC sgd.docs.drift-gate-ownership-attribution. | #10980, #10975 | Two PRs in one session were blocked for path mis-attribution rather than real drift and both used the spec-unchanged bypass. The updates the gate demanded would have written cross-domain noise into docs/features/, and a gate that cries wolf trains reviewers to bypass reflexively — which is how a real drift eventually slips through. |
| 2026-06-10 | Narrowed code-paths: docs/site/** → docs/site/scripts/** (SGD-owned tooling only) | #8483, #8481 | Explainer pages, theme components and ADRs are presentation of other features; the broad glob caused endemic drift-gate false positives (6 manual bypasses on 2026-06-10 alone) |
| 2026-05-27 | Hardened the BLOCKING spec-drift gate (docs/site/scripts/features-data.mjs) so editing one feature spec no longer false-blocks the PR via another spec's catch-all code-paths glob — a docs/features/<slug>.md file is the canonical document for its OWN slug and is excluded from the cross-spec code-path match (mirrors the existing changelog-fragment exclusion). Added a regression test. | #7658, #7384 | sgd.md owns the catch-all docs/features/** glob, so any sibling spec edit (e.g. timesheets.md) was matched as "code belonging to sgd" and the gate demanded an sgd.md update on every spec-editing PR. The fix removes that false positive while leaving each spec's own self-skip intact. |
| 2026-05-20 | Marked sgd.process.spec-driven-ai AC complete — English-language specs in docs/features/ are the source of truth, enforced by the spec-drift gate, BDD-First Rule, and pipeline orchestrators. | #TBD, #6443 | Foundational SGD principle is already operationalised across CLAUDE.md, the spec-drift check (docs/site/scripts/check-spec-drift.mjs), the /team-pipeline and /implement-issue orchestrators, and the sgd-gap-analysis.mjs AC-to-issue generator. |
| 2026-05-20 | Verified sgd.docs.user-journey-persona-map — PPP Docs portal includes personas, end-to-end user journeys, and a screen-level user story map under docs-github/user-journeys/. | #6614, #6441 | Closes the SGD gap-analysis AC. The three companion documents (personas.md, user-flow-diagram.md, user-story-map.md) already exist and are copied into the VitePress portal at build time by docs/site/scripts/copy-journeys.mjs; flipping the AC verified and recording the implementation note closes the gap. |
| 2026-05-20 | Verified sgd.process.must-have-classification — wave + priority frontmatter on every spec encode must-have / nice-to-have per demo scope. | #6608, #6444 | Closes the SGD gap-analysis AC. The convention already exists across docs/features/*.md (defaults from capabilities-config.mjs, resolved by features-data.mjs); flipping the AC verified and documenting it explicitly in _spec-template.md closes the gap. |
| 2026-05-20 | Verified sgd.process.critical-classification — decisions are classified as critical or non-critical to enable safe AI autonomy on low-risk items. | #6606, #6445 | The /team-pipeline orchestrator encodes the split as explicit hard stops in every implementation agent's prompt. pr-issue (HARD STOP 1) and pr-review (HARD STOP 2) gate critical decisions; non-critical decisions (label application, changelog fragment naming, commit message formatting, BDD fragment file selection, inline merge-conflict resolution on adjacent ⏳→✅ flips, squash-merge) run autonomously. This split is what makes the pipeline safe to run unsupervised across N parallel agents. |
| 2026-05-20 | Verified sgd.process.issue-clustering — issues are resolved in functional clusters, not individually; human-readable checks run before each cluster. | #6605, #6446 | Closes the SGD gap-analysis AC. The /team-pipeline and /batch-pipeline orchestrators cluster related sgd:gap issues into one feature branch and route them through N parallel implementation agents. Human-readable checks (spec ACs, BDD scenarios, /pr-issue + /pr-review hard stops) gate every PR before merge — the implementation IS this pipeline. |
| 2026-05-20 | Flipped sgd.docs.anchor-hashes ⏳ → ✅ | #6442 | Verified existing implementation. Stable unique anchor hashes are realised as kebab-case dot-delimited AC codes (e.g. sgd.docs.anchor-hashes), parsed by docs/site/scripts/build-ac-index.mjs (regex [a-zA-Z][\w-]*(?:\.[\w-]+){1,}) and resolved across the AC index and tools/mcp-ac-search/server.mjs (get_ac, find_by_code_path, search_acs) for AI and human cross-referencing. |
| 2026-05-20 | Verified sgd.docs.single-source-of-truth ✅ — VitePress portal under docs/site/ (config + landing) publishes 35 feature specs from docs/features/*.md with machine-readable acs: front-matter, AC index (build-ac-index.mjs), spec sync (sync-features.mjs), and spec-drift CI gate (#6515) making the Docs portal the authoritative, enforced source of truth. | #6440 | Closes #6440. Confirms the SGD docs-portal-as-SoT AC is built (not just contracted) so the spec status table and AC index reflect reality. |
| 2026-05-19 | Verified sgd.notion.feature-page-framing — Notion feature pages document purpose, global implications, and business framing for dual internal/investor use. | #6447 | Closes the SGD gap-analysis AC. Matt-authored Notion Feature pages already carry purpose, global implications, and investor-grade framing; engineering translates those pages into machine-checkable specs under docs/features/. The dual-surface contract (narrative framing in Notion, AC + BDD in repo) is the implementation. |
| 2026-05-19 | Initial spec — 8 ACs from Apr 2026 transcripts | — | SGD formally adopted; spec retroactively authored from transcript audit |