BOHICA-LABS / BOHICA-LABS/vsdd-factory
enhancement(spec-steward+story-writer): treat docs/ tree as a projection of specs — every user-facing doc needs a BC or PRD-supplement anchor and bidirectional projects_to/projects_from links
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Defect class
VSDD methodology treats `docs/` as a downstream projection of specs, but the factory has no scaffolding that makes the projection **bidirectional**. User-facing tutorials, CLI references, error catalogs, and architecture overviews contain BEHAVIORAL claims — statements that set operator expectations the code must satisfy — but they have no BC anchor, no PRD-supplement anchor, and no frontmatter tying them back to their spec authorities.
Detected class: BC amendment → doc silently diverges → operator hits inconsistency → factory never fires a red light.
## Observed failure (switchboard-blue, 2026-07-04)
`docs/getting-started.md` and `docs/sbctl.md` (both shipped in PR #74) contain BEHAVIORAL facts:
- Alpha-channel install command `brew install ArcavenAE/tap/switchboard-a`
- `switchboard-a` binary name substitution rule (`switchboard-a` binary invoked as `switchboard`)
- sbctl-not-yet-on-Homebrew caveat
- Exit-code conventions (BC-2.07.002 EC-003 Ruling A: `--help` → stdout, exit 0)
- `--yes` vs `--confirm` semantics (BC-2.07.005)
- `sbctl --help` short-circuit contract (INV-7)
All of these set operator expectations that specific BCs and interface-definitions.md sections govern. **None** of them carry an anchor. If BC-2.07.002 EC-003 Ruling A were amended (say, adding EC-011 that redirects `--help` to a pager when TTY is present), `docs/sbctl.md §"Common pitfalls"` would silently diverge — and no adversary would catch it, because `docs/*.md` is not in any spec's `inputDocuments:`.
## Root cause
Story S-USER-DOCS (FOLLOWUP-S-USER-DOCS, delivered as PR #74) authored the tutorial without anchoring each behavioral claim in the text to a BC ID. The story template offered no scaffolding for `docFrontmatter:`. The `technical-writer` agent generates docs but doesn't stamp anchors. Consistency-validator has no doc-tier check because there's no anchor to validate against.
## Failure scenario
1. BC-2.07.002 gains EC-011 (say, "if stdout is a TTY, page the output via `$PAGER`; otherwise emit raw").
2. Spec-steward bumps BC-2.07.002 to v1.20.
3. `docs/sbctl.md §"Common pitfalls and how to avoid them"` still says "`--help` exits 0 to stdout" — accurate for legacy behavior, silently incomplete for the new TTY-paged path.
4. Consistency-validator sees no drift (docs aren't in any `inputDocuments:` list).
5. Adversary sees no drift (docs are outside the review perimeter).
6. Operator following the tutorial in a non-TTY pipeline (e.g. CI, or piped through `grep`) hits paging behavior the tutorial never mentioned — files a confused issue.
Detected only by operator complaint months later, or by a fresh phase-1 adversary in the next release cycle picking up the whole docs tree with fresh eyes.
## Proposed fix (three-part)
### 1. Require `docFrontmatter:` on every story that produces `docs/*.md`
`story-writer` prompt update: any story whose deliverables include `docs/*.md` must produce a doc frontmatter block:
```yaml
---
doc_type: user-facing-tutorial | cli-reference | error-catalog | architecture-overview
version: "1.0"
projects_from:
- BC-2.07.002 # every behavioral claim in the doc gets a BC anchor
- interface-definitions.md#L125
- error-taxonomy.md#E-CFG-013
---
```
Each behavioral claim in the doc body should be traceable to one of the entries in `projects_from:` — either via inline anchor markup (e.g. `` above the claim) or via section-level frontmatter on major headings.
### 2. Bidirectional links via `projects_to:`
Register each `projects_from:` entry as a `projects_to:` in the target spec's frontmatter (bidirectional link):
```yaml
# in BC-2.07.002.md frontmatter
projects_to:
- docs/sbctl.md
- docs/getting-started.md
```
Consistency-validator can then catch drift in either direction: a spec amendment that doesn't touch its `projects_to:` docs, OR a doc that references a spec version that no longer contains the anchored clause.
### 3. New skill `/vsdd-factory:validate-docs-projection`
Verifies every claim in `docs/` matches its anchor at the pinned version. Runs as part of `check-input-drift` (phase gates) and `steady-state-spec-drift` (post-SHIPPED gate — see the sibling issue C1).
## Acceptance criteria
- [ ] `story-writer` template requires `docFrontmatter:` for `docs/*.md` outputs
- [ ] `technical-writer` agent stamps anchors when generating docs
- [ ] `projects_to:` field defined in spec-steward's spec frontmatter template
- [ ] `/vsdd-factory:validate-docs-projection` skill registered
- [ ] Consistency-validator gains a doc-tier check
- [ ] `docs/FACTORY.md` picks up "docs are projections of specs" as first-class
## Duplicate check
Not a duplicate.
- Related but distinct from #396 (citation-corpus sweep) — that operates on spec-side citations of other specs; this is spec→doc projection, a different graph edge.
- Related to `technical-writer` agent (currently generates docs but doesn't stamp anchors) — but this is a policy + template issue, not a technical-writer bug.
## Priority
**MEDIUM** — auditability + tutorial trust. Silent drift here erodes operator confidence in the tutorial without any factory signal. Every VSDD project shipping user-facing docs is exposed. Not HIGH because a corrupted tutorial is user-visible pain, not a production correctness defect.
Contributor guide
Assessment
This issue has not been assessed yet.