Skip to content

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 ​

#QuestionProposed answer / statusRef
—No open questions.
Closed Questions (0) — click to expand
#QuestionResolutionRef

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 under docs/site/ (config docs/site/.vitepress/config.ts, landing docs/site/index.md) publishes all 33 feature specs from docs/features/*.md; docs/site/.vitepress/cache/features-counts.json is a build-time cache of open issue counts per feature label, regenerated by sync-features.mjs on every build; each spec carries machine-readable front-matter acs: with per-AC status, an ## Acceptance Criteria section with ⏳/✅ markers traceable to transcript sources, and a ## Current Status table; the AC index generator (docs/site/scripts/build-ac-index.mjs → _ac-index.json, pnpm build:ac-index) cross-indexes every AC for the tools/mcp-ac-search server; docs/site/scripts/sync-features.mjs renders 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 at docs/features/_personas.md for AC tagging via the personas: 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. The docs/site/scripts/copy-journeys.mjs script copies docs-github/user-journeys/ into docs/site/journeys/ at build time so the VitePress portal resolves /journeys/* locally and on the published site. The index.md in 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 by docs/site/scripts/build-ac-index.mjs (regex [a-zA-Z][\w-]*(?:\.[\w-]+){1,}) and resolved by tools/mcp-ac-search/server.mjs tools (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 into docs/features/ — Matt's source of truth — and because a gate that cries wolf trains reviewers to reach for the spec-unchanged bypass reflexively, which is how a real drift eventually slips through. Three ownership rules are enforced by checkDrift in docs/site/scripts/features-data.mjs: (a) fragment and generated artefacts under docs/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) — so sgd.md's broad docs/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 from exportable-reports.md's services/reports-and-export/** to logbook.md); and (c) shared-infrastructure code — an exact-path, individually justified list (SHARED_INFRASTRUCTURE_PATHS in docs/site/scripts/features-config.mjs, consumed via isSharedInfrastructureFile) exempts multi-feature registration points that no single spec can own — currently the single path api/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 and find_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.md claims monitorGeofencePreferences.ts by 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/, via isTestArtefact) 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 a spec-unchanged round-trip; after the carve-out, 0 do, while 1374 source files still trip — detection is unchanged. .feature files are deliberately NOT excluded: they are the living, executable acceptance criteria, so they behave as spec content (they are currently claimed under the separate bdd-features: front-matter key rather than code-paths:, so the gate does not match them today either way — the exclusion is withheld so a spec globbing one into code-paths: keeps working). One explicit exception guards rule (c): the test sibling of a shared-infrastructure path stays matchable (isSharedInfrastructureTestSibling). scheduler-lambda.test.ts is 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 a code-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.mjs runs BEFORE the drift check in spec-drift.yml (and pre-commit via lint-staged) and hard-fails on three conditions: (a) dead-glob — a code-paths: glob matching zero tracked files at HEAD; (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 — a code-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 under code-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 into code-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's ok is violations.length === 0, vacuously true over an empty set, so a BOM on a spec file, a CRLF change, or a parseFrontMatter/list-item regression zeroes a spec's code-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 — checked increments per declared glob, so any spec declaring paths forces checked >= 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, so code-paths: [] and a bare code-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 every src: 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 — and build-ac-index.mjs read 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 and mcp__ppp-ac-search knew about only one. The failure was silent by construction — a displaced citation is not a broken one, so the Validate AC index gate 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 the uat baseline, 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 into acs[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 --validate rather 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 the key: regex is anchored and an indented line never matches it — so the miss fell through a bare continue. This is the worst failure mode a governance record can have, because the row is still present: docs/site/features/ppp-passport.md published | 2026-05-13 | >- | #6198, #5948 | >- | where the audit content should have been, and nothing looked missing. Re-deriving the blast radius against HEAD (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.md published 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 — assertNoBareScalarMarkerCells re-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 breaks Build 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_CODES carried X_MISSING_END_TAG (24) but not its exact mirror X_INVALID_END_TAG (23) — a closing tag with no matching open tag. That gap shipped a broken cpd.md in #12033 and took the docs site down on every uat push 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 own createMarkdownRenderer into 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 in gate-integrity.md; its negative control is the &quot;-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.mjs in 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 as All internal links resolved with 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 in gate-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 below MIN_PAGES_RATIO of 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 built 404.html is 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/*.md is the authoritative English-language source of truth for every feature — CLAUDE.md mandates "Before modifying any named feature, read its spec file in docs/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 via docs/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 /pipeline orchestrators (.claude/commands/*.md) all read the spec file first and require an AC reference in every issue. The sgd-gap-analysis.mjs script emits sgd:gap issues 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/*.md spec carries two frontmatter fields that together encode the must-have / nice-to-have classification: wave (Now | Next | Later) and priority (integer ranking from Matt's Notion). wave: Now means must-have for the current demo scope; wave: Next or wave: Later means nice-to-have. Defaults are inherited from the feature's capability grouping via docs/site/scripts/capabilities-config.mjs (each capability declares a default wave), and individual specs may override by setting wave directly in their frontmatter. The docs/site/scripts/features-data.mjs loader 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 in docs/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-pipeline orchestrator 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 enforces fixes #N linkage 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 to pr-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 skills pr-issue and pr-review carry "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-pipeline and /batch-pipeline orchestrators (.claude/commands/team-pipeline.md, .claude/commands/batch-pipeline.md) operationalise this AC by grouping related GitHub issues — typically a feature's outstanding sgd:gap cluster, or a slice of acceptance criteria from a single docs/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 in docs/features/, (b) the matching .feature BDD scenarios in instances/ppp/e2e/bdd/features/, and (c) the /pr-issue + /pr-review hard stops (see .claude/commands/pr-issue.md, .claude/commands/pr-review.md) that gate every PR before merge. The sgd-gap-analysis.mjs script (pnpm sgd:gap) emits the cluster of sgd: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/*.md with 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-featureStatusNotes
Docs portal — single SOT✅ BuiltVitePress portal + spec front-matter + AC index + drift gate (#6440)
User journey / story map✅ Verifieddocs-github/user-journeys/ — personas, user-flow-diagram, user-story-map (#6441)
Anchor hashes📋 SpecifiedACs extracted from transcripts
Spec-driven AI process📋 SpecifiedFormally adopted 2026-04-21
Must-have classification✅ Verifiedwave + 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✅ VerifiedNotion pages own narrative framing; repo specs own AC (#6447)
AC traceability gate✅ BuiltCI 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 ​
#TitleStatusPriority
—No open issues yet
Change Log ​
DateChangePR/IssueReason
2026-10-04AC 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, ##12885Rob, 4 Oct 2026: be 100% sure every spec AC is either proven in code or tracked as work
2026-08-30The 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, #12057VitePress 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-30The 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, #12041Code 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 &lt;abbr&gt; 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-29Spec-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, #11997Broad 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-27Code-paths liveness gate now compares the front-matter parser against an independent raw byte scan, failing when the parser has silently lost specs.#11093, #11085A 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-27Changelog 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, #11031Silent 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-26The 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 &lt;abbr&gt; 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, #10983Silent 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-26Spec-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, #10975Two 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-10Narrowed code-paths: docs/site/** → docs/site/scripts/** (SGD-owned tooling only)#8483, #8481Explainer 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-27Hardened 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/&lt;slug&gt;.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, #7384sgd.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-20Marked 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, #6443Foundational 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-20Verified 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, #6441Closes 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-20Verified sgd.process.must-have-classification — wave + priority frontmatter on every spec encode must-have / nice-to-have per demo scope.#6608, #6444Closes 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-20Verified sgd.process.critical-classification — decisions are classified as critical or non-critical to enable safe AI autonomy on low-risk items.#6606, #6445The /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-20Verified sgd.process.issue-clustering — issues are resolved in functional clusters, not individually; human-readable checks run before each cluster.#6605, #6446Closes 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-20Flipped sgd.docs.anchor-hashes ⏳ → ✅#6442Verified 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-20Verified 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.#6440Closes #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-19Verified sgd.notion.feature-page-framing — Notion feature pages document purpose, global implications, and business framing for dual internal/investor use.#6447Closes 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-19Initial spec — 8 ACs from Apr 2026 transcripts—SGD formally adopted; spec retroactively authored from transcript audit

Internal documentation — org members only