context-generate

ult-context-generate

Status: piloting. The What-L3/What-L2 dual-layer model, D10 blast-radius analysis, D11 constraints layer, and the D12 handoff to a downstream generation skill were validated end-to-end on a real ~40 KSLOC FastAPI codebase (an RBAC guest-role feature, run through a full context-package generation and approval cycle) before this migration. Now rolling out to a small set of pilot users on substantially larger codebases (500 KSLOC+, often multi-repo), where the What-L1 (external-spec) layer remains disabled and token-cost behavior at this scale is still an open question. Report findings (works well / doesn't / surprises — especially around graphify query budgets and token costs at scale) as an issue in this repo so this can graduate out of pilot status or be reworked.

What-L1 fallback (Step 7.1, D13/D14) is also now piloting — a small specs/external/ corpus is indexed by scripts/md_index.py, a Python-stdlib-only CLI that builds a deterministic structural index (headings, clause ids, section bounds, resolved cross-references — "the graphify for markdown"; see scripts/README.md). Step 7.1 builds this index once per run (--stale-check, the same build-once contract graphify update uses), then queries it per both-layers-gap aspect with synonym-expanded keyword matching to bridge terminology gaps between an aspect's wording and the external spec's own terms. Validated end-to-end against a real downloaded 3GPP TS 33.401 spec plus a NIST SP 800-63B excerpt — see scripts/IMPLEMENTATION-NOTES.md for the full validation write-up. The 500 KSLOC+ volunteer pilots above should still leave what_l1.enabled: false until indexing strategy for large multi-file external-spec corpora (Open Question 1) is resolved — this pilot covers only the small-corpus case.

The index also carries heading-tree bounds and resolved single-hop cross-references (D14) — its markdown-AST (ATX + Setext headings) gives deterministic section boundaries, and a per-profile cross-reference pass (clause X, Annex Y, (see Z), etc.) resolves in-document references at index-build time, so Step 7.1 can follow a matched section's citations to directly-cited sections as additional candidates with no further parsing. Validated against the same two files: recovered a genuinely relevant section (NIST §7.2 "Session Termination", cross-referenced from both originally-matched sections) that the keyword/synonym pass alone had missed, and confirmed Setext-only Annex headings (TS 33.401's Annexes A-K) are correctly bounded. Zero-LLM extraction — a stdlib subprocess builds the index; the agent only reads the matched section_bounds line-ranges. See D13/D14.

How-L1 fallback (Step 2.1, D13/D14) is newly added, not yet field-validated against a real corpus. It reuses the same scripts/md_index.py mechanism as What-L1's Step 7.1, gap-triggered off the existing How-L2 org-convention check (Step 2) instead of per-aspect, and with no web-search/training-knowledge fallback chain of its own — see references/how-l1-fallback-query.md. Leave how_l1.enabled: false until you've run it once against your own org's process-standard .md files and confirmed the results look right.

This file and others in this repo cite D<N>/§<N> labels (e.g. D11, D20 §15.5) — see ../../../references/design-scratchpad-glossary.md for what each one means.