spec: validate numbering, edges, and links before writing artifacts - #217
Merged
Conversation
Skill Eval ResultsMode:
|
joestump
added a commit
that referenced
this pull request
Aug 19, 2026
…path Two defects in the Related Artifacts section: The heading collided with the one /sdd:docs already appends. Both transform-openspecs.js and the vendored Docusaurus plugin emit a generated '## Related Artifacts' mini-DAG at the foot of every spec and design page, so an authored section under the same name gave every rendered page two identical H2s -- duplicate anchors and a doubled TOC entry. Renamed to '## Graph Edges', matching the repo's own edge vocabulary. The Implements example pointed at ../../../adr/, singular. The ADR directory is docs/adrs/, so every spec seeded from this template shipped a dead link -- and PR #217 adds a validation rule requiring exactly the links this template breaks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Skill Eval ResultsMode:
|
joestump
force-pushed
the
feat/spec-authoring-validation
branch
from
August 19, 2026 10:03
453d6d8 to
e56db3f
Compare
joestump
added a commit
that referenced
this pull request
Aug 19, 2026
…path Two defects in the Related Artifacts section: The heading collided with the one /sdd:docs already appends. Both transform-openspecs.js and the vendored Docusaurus plugin emit a generated '## Related Artifacts' mini-DAG at the foot of every spec and design page, so an authored section under the same name gave every rendered page two identical H2s -- duplicate anchors and a doubled TOC entry. Renamed to '## Graph Edges', matching the repo's own edge vocabulary. The Implements example pointed at ../../../adr/, singular. The ADR directory is docs/adrs/, so every spec seeded from this template shipped a dead link -- and PR #217 adds a validation rule requiring exactly the links this template breaks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Skill Eval ResultsMode:
|
Add a consistency-validation step between drafting and writing: the SPEC number in the H1 must match the sequential number chosen in Step 3, every frontmatter edge target must resolve to an existing artifact, and every relative markdown link in both files must point at a real file. Found by auditing downstream projects — a renumbered spec kept its stale requirement-ID prefix and cross-links rotted silently. Also extends the self-review checklist with these checks and requires design.md to keep its Open Questions section. 💘 Generated with Crush Assisted-by: Crush:glm-5.3
…tion Step 4c's SPEC-number check asserted the H1 equals the *next* sequential number from Step 3. Step 3 runs unconditionally, including on the Step 2 update path, so validating an update to an existing spec would have demanded the file be renumbered — orphaning every tracker issue, graph edge, and cross-spec reference that already cites the old number. Scope the check to the number the run is actually authoring under. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
joestump
force-pushed
the
feat/spec-authoring-validation
branch
from
August 19, 2026 10:26
e56db3f to
530f94d
Compare
joestump
added a commit
that referenced
this pull request
Aug 19, 2026
…path Two defects in the Related Artifacts section: The heading collided with the one /sdd:docs already appends. Both transform-openspecs.js and the vendored Docusaurus plugin emit a generated '## Related Artifacts' mini-DAG at the foot of every spec and design page, so an authored section under the same name gave every rendered page two identical H2s -- duplicate anchors and a doubled TOC entry. Renamed to '## Graph Edges', matching the repo's own edge vocabulary. The Implements example pointed at ../../../adr/, singular. The ADR directory is docs/adrs/, so every spec seeded from this template shipped a dead link -- and PR #217 adds a validation rule requiring exactly the links this template breaks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Owner
Code review —
|
Skill Eval ResultsMode:
|
joestump
added a commit
that referenced
this pull request
Aug 19, 2026
…path Two defects in the Related Artifacts section: The heading collided with the one /sdd:docs already appends. Both transform-openspecs.js and the vendored Docusaurus plugin emit a generated '## Related Artifacts' mini-DAG at the foot of every spec and design page, so an authored section under the same name gave every rendered page two identical H2s -- duplicate anchors and a doubled TOC entry. Renamed to '## Graph Edges', matching the repo's own edge vocabulary. The Implements example pointed at ../../../adr/, singular. The ADR directory is docs/adrs/, so every spec seeded from this template shipped a dead link -- and PR #217 adds a validation rule requiring exactly the links this template breaks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
joestump
added a commit
that referenced
this pull request
Aug 19, 2026
) * spec: render frontmatter edges as a Related Artifacts body section Frontmatter edges are machine-readable only -- a reader of the raw markdown or the rendered docs page never sees which ADRs a spec implements or which capabilities it requires, so downstream projects hand-write ad-hoc "Related ADRs" header lines in inconsistent shapes (found in every audited downstream repo). Give the template a canonical home for that information: a Related Artifacts section that mirrors the frontmatter edges, one bullet per target, regenerated whenever edges change. 💘 Generated with Crush Assisted-by: Crush:glm-5.3 * fix(spec): avoid the generated mini-DAG heading and fix the ADR link path Two defects in the Related Artifacts section: The heading collided with the one /sdd:docs already appends. Both transform-openspecs.js and the vendored Docusaurus plugin emit a generated '## Related Artifacts' mini-DAG at the foot of every spec and design page, so an authored section under the same name gave every rendered page two identical H2s -- duplicate anchors and a doubled TOC entry. Renamed to '## Graph Edges', matching the repo's own edge vocabulary. The Implements example pointed at ../../../adr/, singular. The ADR directory is docs/adrs/, so every spec seeded from this template shipped a dead link -- and PR #217 adds a validation rule requiring exactly the links this template breaks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: joestump <joe@joestump.net> Co-authored-by: Claude Opus 5 <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
2 participants
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.
First of five PRs hardening the authoring skills, based on a downstream audit: I reviewed every ADR and OpenSpec in a plugin-generated project (msgbrowse) and traced which defects came from the skills vs. the project. Three skill-side gaps showed up as real bugs downstream.
What changed (this PR)
Adds Step 4c — Consistency validation before writing to
/sdd:spec, run after drafting and before the files hit disk:SPEC-XXXXmust equal the sequential number chosen in Step 3. Downstream evidence: msgbrowse's contact-merge spec was renumbered mid-draft to SPEC-0018 but its ten requirement headings kept the staleREQ-0015-prefix, and seven Go source comments inherited the wrong ID before anyone noticed.implements/requires/extends/supersedesID must resolve to an artifact on disk; otherwise/sdd:graph validatefails the first time it runs.](...)relative targets from both spec.md and design.md and stat each. Hand-finished specs accumulate silently-broken relative links.Also extends the self-review/architect checklist with the same three checks plus: design.md must retain its
## Open Questionssection (an explicit "None currently" is fine) — today nothing stops the section from being dropped, which loses the designated home for unresolved questions.Verification
scripts/check-structure.shpassesCompanion PRs: ADR template hardening, Related Artifacts body section, security-baseline references, and a
/sdd:status backfillmode.🤖 This was posted autonomously by
glm-5.3using Crush.