Delivery Methodology
The documentation discipline every build and engagement follows, promoted from the vsi-feed-1 delivery (reference/vsi-feed-1).
The quartet
| Artifact | Purpose | Required when |
|---|---|---|
| CONTEXT.md | Controlled-vocabulary glossary with explicit anti-terms (“Avoid” entries) | any project with domain language |
| docs/adr/NNNN-slug.md | Architecture Decision Records: Status/Context/Decision/Consequences, including rejected alternatives | every architectural call |
| BUILD_LOG.md | Append-only dated journal with verification evidence per step | every build |
| HANDOFF.md | Session-to-session continuity: what is live, secrets inventory, guardrails, likely next tasks | every pause in multi-session work |
Gated builds
Substantial builds start from a PROMPT.md-class spec with explicit gates: numbered steps, each with entry criteria, verification evidence, and operator sign-off before the next gate opens. The vsi-feed-1 build (10 gates, 16-finding hardening pass, 42 tests) is the exemplar.
Cell promotion gate (drafted → approved)
Promotion is verification plus validation; both must pass and they are not the same check (15288: verification = built right, validation = right thing built). The reviewer and the validator may be the same person only when that person did not author the cell.
| Step | Check | Who | Evidence |
|---|---|---|---|
| V1 Verification | uv run mbse verify exits 0; style sweep (placeholders, no em dashes, verbatim blocks intact); traceability and seam closure re-checked against the manifest | Independent reviewer (never the authoring agent in the same change) | Review dispatch or commit message listing checks run |
| V2 Validation | Cold-start operator test actually performed: a named operator (BR, RF, MR, JM, or CS acting in an operator role) walks the cell plus its cited artifacts and confirms they could execute or brief from it alone, without asking the author anything | Named operator, recorded by initials | Validator initials and date in the review dispatch or commit message |
| V3 Sign-off | Accountable owner accepts residual gaps and promotes status to approved, bumping version | Owner | Status/version change in the same commit |
A cell that fails V2 goes to needs-revision with the operator’s blocking questions listed verbatim; those questions are the defect list. Batch promotions (review burn-downs) still require V2 per cell, but one validator may cover a coherent set (e.g. the EP-020..026 planning family) in a single recorded session.
Reliability doctrine (for alerting/operational systems)
- Deterministic hot path: no LLM, ML, or external decision API may gate an alert. External data sources are acceptable; external judgment is not.
- LLM enrichment runs strictly off the hot path and reads the hot path’s logs.
- Delivery-integrity invariants: mark-seen only after confirmed delivery; high-water marks advance only after full batch delivery; first-run priming learns backlog without alerting.
- Chat-exposed LLM analysts run sandboxed: web-only tools, no shell or filesystem, throwaway working directory, grounding injected into the prompt.