Bootstrap reference domain and spec examples

Traceability

• Spec ID: bootstrap-reference-domain
• Status: Implemented

Intent

The Bootstrap support track is the only Better Harness route for a project that has no coding-agent harness yet, but its whole depth lives in a single 55-line skill-local file, skills/better-harness/references/support-bootstrap.md. That file must stay inside the skill prompt budget, so it can only say "propose the smallest useful owner" and cannot teach what a complete, agent-executable specification actually contains. Teams doing 0 -> 1 work therefore get owner advice with no artifact shape, and the repository has no calibration example for what a finished requirement spec looks like across delivery surfaces.

Split the depth out into a new references/bootstrap/ domain that owns the specification structure contract and stack-specific calibration examples, keep the skill file as a thin track selector, and register the new domain in the references/README.md switchboard so both agents and humans can route to it.

Acceptance Scenarios

• BRD-AC-1 (domain exists and routes): references/bootstrap/README.md follows the established domain-index shape used by references/loop-engineering/README.md and references/session-evidence/README.md, with Purpose, Load When, Owns, Does Not Own, and Read Next sections.
• BRD-AC-2 (spec structure contract): references/bootstrap/spec-structure.md defines the required specification sections, stable id schemes for business rules, exception scenarios, and acceptance criteria, plus the completeness gates that decide whether a spec is ready for implementation.
• BRD-AC-3 (surface honesty): The contract states that the surface specification section repeats once per delivery surface, so the eight-part count of a two-surface project is an instantiation of the contract rather than a fixed section list every project must match.
• BRD-AC-4 (three stack examples): references/bootstrap/examples/ contains a backend-service, a frontend-web, and a mobile-app spec example, each instantiating every required section with numbered BR-*, E-*, and AC-* ids, and each example is indexed from examples/README.md.
• BRD-AC-5 (thin skill track): support-bootstrap.md keeps Select This Track and Preserve Boundaries, routes its recommendation depth to the new domain, stays under 120 lines and 7,000 bytes, and preserves every phrase asserted by test/better-harness-skill.test.mjs: the explicit initial-guidance trigger, the zero-count exclusion, smallest useful owner, Good AGENTS.md Example Fragments, and the separate task-local request boundary.
• BRD-AC-6 (read-only boundary preserved): Neither the new domain nor the revised track authorizes asset creation, installation, activation, or mutation, and neither turns an initialization request into evidence that the target project is defective.
• BRD-AC-7 (English-first chain): Every file reachable from skills/better-harness/SKILL.md stays free of Han-script characters, which the new domain must satisfy because support-bootstrap.md links into it.
• BRD-AC-8 (link integrity): All relative links resolve, the new domain is registered in the references/README.md switchboard, and docs/better-harness-doc-links.mmd is regenerated.

Non-goals

• Add a fourth support track, change track selection thresholds, or let Bootstrap add findings, change severity, or rescore a dimension.
• Own instruction-file taxonomy or quality; that stays with references/agent-customize/routing.md and agents-md-review.md.
• Own verification harness design, acceptance controls, or recovery evidence; those stay with references/project-harness/.
• Own durable owner selection for repeated work; that stays with references/loop-engineering/.
• Introduce a spec validator, generator, template renderer, or any executable tooling. This domain ships prose and examples only.
• Prescribe a vendor stack. The examples name a technology only where the contract shape depends on it.
• Change docs/specs/ conventions for this repository's own specs; the new contract describes product requirement specs written for target projects.

Plan and Tasks

1. Add references/bootstrap/README.md as the domain index, declaring what the domain owns, what it explicitly does not own, and the read order.
2. Add references/bootstrap/spec-structure.md with the required sections, the BR-* / E-* / AC-* id and traceability rules, the per-surface repetition rule, completeness gates, and anti-patterns.
3. Add references/bootstrap/examples/README.md plus three examples: backend-service-spec.md (service contract, data model, admin and mini-program surfaces), frontend-web-spec.md (page skeleton, component granularity, state machine, interaction constraints), and mobile-app-spec.md (offline and sync, permissions, background work, release gating). Each example calibrates the contract; none is a template to copy wholesale.
4. Rewrite the Shape the Recommendation section of support-bootstrap.md to route into the new domain while keeping the test-asserted phrases and the compact budget.
5. Register bootstrap/ in the references/README.md switchboard next to the other support domains.
6. Regenerate the routing graph with node scripts/doc-link-graph/cli.mjs skills/better-harness.

Test and Review Evidence

• node --test test/doc-link-graph.test.mjs — relative link resolution, Han-script-free English chain (BRD-AC-7), and routing-graph freshness (BRD-AC-8).
• node --test test/better-harness-skill.test.mjs — support-track phrase, line-count, and byte-budget assertions (BRD-AC-5). support-bootstrap.md measures 60 lines and 2,983 bytes after the split.
• npm test — 1,148 of 1,149 tests pass. The single failure is Better Harness skill's English-first Markdown chain stays Han-script-free, caused by the link from references/project-harness/agent-verify-loop.md to friendly-cli.md, which is already on main. That opens the chain SKILL.md -> models/agent-work-loop.md -> agent-verify-loop.md -> friendly-cli.md -> docs/ARCHITECTURE.md into the Docusaurus and README.zh-CN.md docs. Every edge in that chain exists without this spec's changes, so the failure is not attributable here and is not fixed here.
• Blast-radius check (BRD-AC-7): the transitive closure of the depth this track newly routes into, seeded from spec-structure.md and examples/README.md, contains exactly the five new in-chain files and nothing else. All eight touched or added files are verified Han-script-free.
• Design fix applied during implementation: an earlier draft linked references/bootstrap/README.md from the references/README.md switchboard and deep-linked references/project-harness/agent-verify-loop.md from spec-structure.md. Both pulled cross-domain subtrees into the English-first skill chain. The domain README now stays outside that chain, matching how references/loop-engineering/README.md behaves, and no switchboard entry names a README.
• Risk: the examples are prose fixtures with no executable verifier, so they can drift from the contract in spec-structure.md. Mitigation is that every example lists the same required sections in the same order, making a divergence visible in review.
• Risk: references/bootstrap/README.md is reachable only by directory browsing, not by a Markdown link from the switchboard. This is deliberate containment of the English-first chain and matches the existing loop-engineering/ entry.