Add interviews/staffml/README.md covering the local development
workflow that the prior commit's predev hook relies on:
- TL;DR install + run-dev steps
- explanation of the production-worker vs local-static data flow
- what the predev hook does (sync-periodic-table + vault build --local)
- env vars (NEXT_PUBLIC_VAULT_FALLBACK, NEXT_PUBLIC_VAULT_API,
STAFFML_SKIP_LOCAL_CORPUS) and their effects
- troubleshooting the three failure modes that bit us during the YAML
audit work (could-not-load, stale content, infinite loading)
Update interviews/vault-cli/README.md to surface `vault build --local`
in the Local-dev section with a pointer to the StaffML README.
The intent: a contributor who edits a YAML and doesn't see the change
in the dev server should now find the answer in the README before
they're forced to read the loader source.
Establishes one ignored subdirectory for ALL intermediate outputs of
LLM-driven tooling (chain proposals, gap detection, draft scorecards,
audit traces). Single gitignore rule: /_pipeline/.
Convention is documented in interviews/vault/README.md under "Pipeline
artifacts" — it's a real project layout convention, not AI-specific
config.
Path migration:
interviews/vault/chains.proposed*.json
→ _pipeline/chains.proposed*.json
interviews/vault/gaps.proposed*.json
→ _pipeline/gaps.proposed*.json
interviews/vault/draft-validation-scorecard.json
→ _pipeline/draft-validation-scorecard.json
interviews/vault/audit-runs/
→ _pipeline/runs/
8 scripts updated to define a PIPELINE_DIR constant and route default
outputs through it: build_chains_with_gemini.py,
apply_proposed_chains.py, merge_chain_passes.py, validate_drafts.py,
audit_chains_with_gemini.py, generate_question_for_gap.py,
summarize_proposed_chains.py, promote_drafts.py.
Forward-looking docs (README.md chain-pipeline section + CHAIN_ROADMAP.md
resume instructions + state snapshot) updated to reference the new
paths. Historical Progress Log entries left as-is — they accurately
describe what was committed at the time.
Drive-by .gitignore fixes (both used full repo-relative paths under
package-local .gitignore files, which never matched):
interviews/vault-cli/.gitignore: scripts/.calibration_cache/
interviews/vault/.gitignore: /embeddings.npz
Validation:
- vault check --strict: 10,705 loaded, 0 invariant failures
- pytest interviews/vault-cli/tests/: 74/74
- audit --dry-run: paths resolve correctly to _pipeline/runs/<ts>/
No durable corpus content moves. chains.json (live registry),
id-registry.yaml, questions/, etc. all stay where they were.
dev renamed the vault-cli flag in 2b381bb949 (the flag is the staffml
frontend's local-dev fallback for reading corpus.json from disk, not
deprecated path — "local-json" reads correctly in scripts and docs).
Merge of origin/dev (5c5af75ed) brought the new name in but the
roadmap + README still referenced the old one.
- README.md: 1 replacement in the chain-pipeline runbook footer
- CHAIN_ROADMAP.md: 8 replacements across resume instructions,
phase runbooks, and progress-log validator lines
Historical text inside log entries is otherwise unchanged — those
record what was true at commit time. Forward-looking instructions
now use the current flag name.
Phase 4.8 of CHAIN_ROADMAP.md.
ARCHITECTURE.md gains a new §3.6 capturing the three deltas that landed
during the chain workstream — additive to v1, not replacements:
- hierarchical question layout (`<track>/<area>/<id>.yaml`)
- sidecar chain architecture (chains.json authoritative; YAML chains:
field retired)
- chain tier model (primary/secondary, default-primary on read)
README.md updates:
- status line: v1.1, points at CHAIN_ROADMAP.md and ARCHITECTURE.md §3.6
- new "Chain build pipeline" section with the diagnose / build /
apply / merge invocations
- layout listing reflects scripts/ and the actual src/ contents
(was stuck on Phase 0 scaffolding shape)
No code changes. The v1 release-pipeline invariants absorb the v1.1
deltas without modification (chains.json is a Merkle leaf; tier flows
into that leaf transparently).
R11 (David, fresh-eyes stability check): 0 Critical + 0 High + 1 Medium
(doc cleanup from R10-F-2 closure itself).
R11-M-1 (MEDIUM): CUTOVER_QA.md + vault-cli/README.md still referenced
--canary-percent flag after R10-F-2 removed it from code + ARCHITECTURE.md.
Operator following CUTOVER_QA.md step 1 of cutover day would hit
'Error: no such option --canary-percent' \u2014 the one document whose
entire purpose is cutover correctness.
Fix: CUTOVER_QA.md \u00a71 replaces canary-staged rollout with all-or-nothing
ship language + Phase-7-deferred note pointing at \u00a74.3. README.md:57
drops [--canary-percent N] from the ship example.
STABILITY DECLARED after R11. Three consecutive rounds (R7, R8, R11) with
zero new Criticals. R11 explicit: 'convergence confirmed.'
Finding-density trajectory across 11 rounds (new Criticals per round):
R1: 3, R2: 1, R3: 2, R4: 3, R5: 3, R6: skipped,
R7: 0, R8: 0, R9: 1* (regression-detect, not new), R10: 0, R11: 0
Total findings closed across all rounds: ~120.
No further rounds scheduled.
ARCHITECTURE.md header bumped v2.5 \u2192 v2.6.
REVIEWS.md adds 'Rounds 7\u201311' section with per-round finding counts,
notable findings, meta-observation on R9 (tooling/persistence issue
Gemini caught that individual-file reviewers couldn't), and the
convergence signal.
interviews/vault/README.md (NEW)
Top-level tour of the vault directory tree, common commands, data-
flow diagram (YAML \u2192 paper / YAML \u2192 site), invariant summary,
review-round summary. Points at CC-BY-NC-4.0 license.
interviews/vault-cli/README.md — updated Quickstart
Full 22-subcommand reference replacing the Phase-0 placeholder,
organized by authoring / build-check / release-pipeline / local-dev.
release.py::_sql_quote
Docstring explains why SQLite single-quote escape is sufficient and
injection-safe for our callers (corpus content authored via
maintainer-approved flow, not external untrusted input). Warns
against reuse for other dialects.
