BOHICA-LABS / BOHICA-LABS/vsdd-factory
bug(spec-steward+consistency-validator): inputDocuments: frontmatter is one-directional, unvalidated, and silently rots when input files move or are renamed
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Defect class
`inputDocuments:` frontmatter is authored by hand at spec creation, is one-directional, and is never revalidated. `/vsdd-factory:check-input-drift` compares hashes but doesn't check existence, doesn't warn on files-that-should-be-listed-but-aren't, and doesn't enforce a return-link from the input file to the owning spec.
Three subclasses of failure:
1. **Dangling path.** A file in `inputDocuments:` is deleted or renamed by an unrelated PR → the spec's citation dangles silently. `check-input-drift` computes a hash of the current file (or fails to find it) but doesn't scream about the delta.
2. **Missing-authority file.** A file that OUGHT to be in `inputDocuments:` — a newly-added workflow, a new script, a new Formula — is created and no spec claims authority for it. No scan flags "these CI files aren't referenced by any spec."
3. **Version disagreement.** Multiple specs each list the same input but disagree on the version they were validated against. Consistency-validator has no cross-spec version-of-shared-inputs check.
## Observed failures (switchboard-blue, 2026-07-04)
**Instance 1 (subclass 2, missing-authority).** During ARCH-06 v1.1 amendment, verified that the spec's `inputDocuments:` listed `.github/workflows/ci.yml` but the ci.yml header comment ("Never touches Formula/switchboard.rb — that slot is reserved") had no corresponding stamp saying "authoritative spec: ARCH-06-deployment-and-ops.md §Distribution & Packaging". If ci.yml were renamed or moved, ARCH-06's `inputDocuments:` would silently become invalid (dangling path) and no factory step would surface it.
**Instance 2 (subclass 2, missing-authority).** `cicd-setup.md` v1.0 listed six workflow files but did NOT list `Formula/switchboard-a.rb` — an omission that let PR #75 (Formula rename) land without any spec touch, despite the Formula being a first-class distribution artifact.
**Instance 3 (subclass 1, dangling-path risk).** No systematic scan of "does every file listed in every spec's `inputDocuments:` still exist?" — a rename PR by an unrelated story would leave stale entries.
## Root cause
- `inputDocuments:` is authored once at spec creation, never derived, never revalidated on unrelated PRs.
- No return-link from the input file back to its authoritative spec.
- `/vsdd-factory:check-input-drift` is hash-diff only; doesn't check existence or coverage.
- `/vsdd-factory:register-artifact` doesn't prompt for `inputDocuments:` at spec-creation time or validate that each listed path is a real file.
## Proposed fix (three-part)
### 1. Make `inputDocuments:` bidirectional
Every entry gains a mirror. Either:
**Option A (return-link in the input file):** the input file must carry a comment header:
```yaml
# spec-authority: ARCH-06-deployment-and-ops.md §Distribution & Packaging
```
**Option B (authored_by in the spec):** the spec's `inputDocuments:` list gains an `authored_by:` field per entry — but this is what we already have, so this option is degenerate. Prefer Option A.
For file types that don't support comments (JSON, non-config binary), fall back to a manifest file at the same directory alongside the input (e.g. `Formula/.spec-authorities.yaml`).
### 2. New skill `/vsdd-factory:validate-input-anchors`
- **Existence check.** Confirms every path in every spec's `inputDocuments:` still exists. Fails on dangling paths.
- **Coverage warning.** For every file touched by CI (workflows, Formula files, scripts, config files) that has NO spec authority, prints a warning listing the file and suggesting which spec should adopt it. Operator can suppress with an explicit `not-a-spec-input:` marker.
- **Version cross-check.** For every file referenced by multiple specs, warns if the specs disagree on the version they last validated against (they should all be current, or one is stale).
Runs as part of `check-input-drift` (phase gates) and `steady-state-spec-drift` (post-SHIPPED — see C1).
### 3. Update `/vsdd-factory:register-artifact`
Prompt for `inputDocuments:` at spec-creation time. Validate that each path is a real file (not a placeholder). Register the return-link comment in the input file(s) automatically where the file type supports it.
## Acceptance criteria
- [ ] `/vsdd-factory:validate-input-anchors` skill registered and covers all three subclasses
- [ ] `check-input-drift` calls into `validate-input-anchors` for existence + coverage checks
- [ ] `register-artifact` prompts for `inputDocuments:` and validates paths
- [ ] Spec-steward's template includes guidance on when to add an entry to `inputDocuments:`
- [ ] Some `.github/workflows/**` file gets a `# spec-authority:` example in the plugin's blueprint materials
## Duplicate check
Not a duplicate.
- Not #396 (citation-corpus sweep) — different granularity (spec-body vs frontmatter list).
- Related to `/vsdd-factory:check-input-drift` — but that's hash-diff only, not existence-check.
- Adjacent to C1 (steady-state spec-drift) and C2 (docs projection) — same "inputs and outputs of specs should be first-class, bidirectional, machine-checkable" pattern, different edges of the graph.
## Priority
**MEDIUM** — audit-chain integrity. Not HIGH because dangling paths tend to surface eventually (someone runs the workflow, it breaks, someone investigates). But the failure mode is exactly the kind of silent-decay that steals hours later; catching it at drift-time is orders of magnitude cheaper.
Contributor guide
Assessment
This issue has not been assessed yet.