@spec-engine/spec-engine 0.6.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/architecture/index.html +1 -1
- package/dist/docs/checks/index.html +25 -5
- package/dist/docs/commands/index.html +3 -3
- package/dist/docs/pagefind/fragment/en_6ce6fae.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_775cc8c.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_a3cd8bf.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_b44542a.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_d652b3c.pf_fragment +0 -0
- package/dist/docs/pagefind/index/en_6b9dc89.pf_index +0 -0
- package/dist/docs/pagefind/index/en_c5bf3e1.pf_index +0 -0
- package/dist/docs/pagefind/pagefind-entry.json +1 -1
- package/dist/docs/pagefind/pagefind.en_c6c8e941d5.pf_meta +0 -0
- package/dist/docs/platform-mapping/index.html +1 -1
- package/dist/docs/tags/index.html +1 -1
- package/dist/impl.js +832 -517
- package/package.json +1 -1
- package/dist/docs/pagefind/fragment/en_01934b1.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_4560516.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_aa3ebfe.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_dfaa776.pf_fragment +0 -0
- package/dist/docs/pagefind/fragment/en_edd950c.pf_fragment +0 -0
- package/dist/docs/pagefind/index/en_a63e8e2.pf_index +0 -0
- package/dist/docs/pagefind/pagefind.en_2ed26d23fb.pf_meta +0 -0
|
@@ -386,7 +386,7 @@
|
|
|
386
386
|
|
|
387
387
|
|
|
388
388
|
|
|
389
|
-
<table><thead><tr><th>Operation</th><th>Input</th><th>Result</th><th>CLI</th><th>HTTP</th><th>MCP</th></tr></thead><tbody><tr><td><code dir="auto">query</code></td><td>storage, text, limit</td><td>ranked hits, or <code dir="auto">usage</code> on an FTS5 grammar error</td><td><code dir="auto">spec query</code></td><td><code dir="auto">GET /api/query</code></td><td><code dir="auto">spec_query</code></td></tr><tr><td><code dir="auto">resolveFiles</code></td><td>storage, platform-relative files</td><td>the requirements tagged in them</td><td><code dir="auto">spec resolve</code></td><td><code dir="auto">GET /api/resolve?files=</code></td><td><code dir="auto">spec_resolve</code></td></tr><tr><td><code dir="auto">reqTags</code></td><td>storage, requirement id</td><td>every tag site, and whether the id is known</td><td><code dir="auto">spec resolve --req</code></td><td><code dir="auto">GET /api/resolve?req=</code></td><td><code dir="auto">spec_req_tags</code></td></tr><tr><td><code dir="auto">propagation</code></td><td>storage, requirement id</td><td>per-member migration state</td><td><code dir="auto">spec propagation</code></td><td><code dir="auto">GET /api/propagation/:id</code></td><td><code dir="auto">spec_propagation</code></td></tr><tr><td><code dir="auto">coverageReport</code></td><td>storage</td><td>per-domain rollup</td><td></td><td><code dir="auto">GET /api/report</code></td><td><code dir="auto">spec_coverage_report</code></td></tr><tr><td><code dir="auto">check</code></td><td>storage, platform dir, results file, base ref, flags</td><td>diagnostics, <code dir="auto">build_id</code>, red or green</td><td><code dir="auto">spec check</code></td><td></td><td><code dir="auto">spec_check</code></td></tr><tr><td><code dir="auto">nextId</code></td><td>platform dir, domain key or prefix</td><td>the resolved key and next unused id, or <code dir="auto">usage</code></td><td><code dir="auto">spec req</code></td><td></td><td><code dir="auto">spec_next_id</code></td></tr><tr><td><code dir="auto">mint</code></td><td>platform dir, key, statement, why, lives-in, issue, status</td><td>the new id and file, or <code dir="auto">not_found</code> / <code dir="auto">usage</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec req --text</code></td><td><code dir="auto">POST /api/requirements</code></td><td></td></tr><tr><td><code dir="auto">amend</code></td><td>platform dir, id, fields
|
|
389
|
+
<table><thead><tr><th>Operation</th><th>Input</th><th>Result</th><th>CLI</th><th>HTTP</th><th>MCP</th></tr></thead><tbody><tr><td><code dir="auto">query</code></td><td>storage, text, limit</td><td>ranked hits, or <code dir="auto">usage</code> on an FTS5 grammar error</td><td><code dir="auto">spec query</code></td><td><code dir="auto">GET /api/query</code></td><td><code dir="auto">spec_query</code></td></tr><tr><td><code dir="auto">resolveFiles</code></td><td>storage, platform-relative files</td><td>the requirements tagged in them</td><td><code dir="auto">spec resolve</code></td><td><code dir="auto">GET /api/resolve?files=</code></td><td><code dir="auto">spec_resolve</code></td></tr><tr><td><code dir="auto">reqTags</code></td><td>storage, requirement id</td><td>every tag site, and whether the id is known</td><td><code dir="auto">spec resolve --req</code></td><td><code dir="auto">GET /api/resolve?req=</code></td><td><code dir="auto">spec_req_tags</code></td></tr><tr><td><code dir="auto">propagation</code></td><td>storage, requirement id</td><td>per-member migration state</td><td><code dir="auto">spec propagation</code></td><td><code dir="auto">GET /api/propagation/:id</code></td><td><code dir="auto">spec_propagation</code></td></tr><tr><td><code dir="auto">coverageReport</code></td><td>storage</td><td>per-domain rollup</td><td></td><td><code dir="auto">GET /api/report</code></td><td><code dir="auto">spec_coverage_report</code></td></tr><tr><td><code dir="auto">check</code></td><td>storage, platform dir, results file, base ref, flags</td><td>diagnostics, <code dir="auto">build_id</code>, red or green</td><td><code dir="auto">spec check</code></td><td></td><td><code dir="auto">spec_check</code></td></tr><tr><td><code dir="auto">nextId</code></td><td>platform dir, domain key or prefix</td><td>the resolved key and next unused id, or <code dir="auto">usage</code></td><td><code dir="auto">spec req</code></td><td></td><td><code dir="auto">spec_next_id</code></td></tr><tr><td><code dir="auto">mint</code></td><td>platform dir, key, statement, why, lives-in, relates, issue, status</td><td>the new id and file, or <code dir="auto">not_found</code> / <code dir="auto">usage</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec req --text</code></td><td><code dir="auto">POST /api/requirements</code></td><td></td></tr><tr><td><code dir="auto">amend</code></td><td>platform dir, id, fields</td><td>the changed fields, or <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec amend</code></td><td><code dir="auto">PUT /api/requirements/:id</code></td><td></td></tr><tr><td><code dir="auto">supersede</code></td><td>platform dir, id, successor statement and fields, a fresh-tags callback</td><td>the successor id, the domain version, the retag worklist, or <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">usage</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec supersede</code></td><td><code dir="auto">POST /api/requirements/:id/supersede</code></td><td><code dir="auto">spec_supersede</code></td></tr><tr><td><code dir="auto">move</code></td><td>platform dir, id, target domain key, optional successor fields, a fresh-tags callback</td><td>both files, both versions, the retag worklist, or <code dir="auto">usage</code> / <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec move</code></td><td></td><td></td></tr><tr><td><code dir="auto">deprecate</code></td><td>platform dir, id, reason, a fresh-tags callback</td><td>the file and the tags still bound, or <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec deprecate</code></td><td><code dir="auto">POST /api/requirements/:id/deprecate</code></td><td><code dir="auto">spec_deprecate</code></td></tr><tr><td><code dir="auto">accept</code></td><td>platform dir, id</td><td>the file, or <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec accept</code></td><td><code dir="auto">POST /api/requirements/:id/accept</code></td><td><code dir="auto">spec_accept</code></td></tr><tr><td><code dir="auto">mintTerm</code>, <code dir="auto">listTerms</code>, <code dir="auto">reviseTerm</code>, <code dir="auto">confirmTerm</code></td><td>platform dir, term fields or ids</td><td>the term id, the store rows, the bumped version, or the re-pinned citation; <code dir="auto">not_found</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code></td><td><code dir="auto">spec term</code></td><td></td><td></td></tr><tr><td><code dir="auto">coverageMatrix</code></td><td>storage</td><td>requirement × repo rows</td><td><code dir="auto">spec map</code></td><td><code dir="auto">GET /api/coverage</code></td><td></td></tr><tr><td><code dir="auto">getRecord</code></td><td>storage, requirement id</td><td>one full <code dir="auto">Requirement</code> row, or null</td><td><code dir="auto">spec get</code></td><td><code dir="auto">GET /api/requirements/:id</code></td><td><code dir="auto">spec_get</code></td></tr><tr><td><code dir="auto">listRecords</code></td><td>storage, optional key and status</td><td>every <code dir="auto">Requirement</code> row in (key, seq) order</td><td><code dir="auto">spec list</code></td><td><code dir="auto">GET /api/requirements</code></td><td><code dir="auto">spec_list</code></td></tr><tr><td><code dir="auto">relations</code></td><td>storage</td><td><code dir="auto">relates</code> links</td><td><code dir="auto">spec relations</code></td><td><code dir="auto">GET /api/relations</code></td><td></td></tr><tr><td><code dir="auto">provenance</code></td><td>storage, optional issue id</td><td>provenance matrix rows</td><td><code dir="auto">spec provenance</code></td><td><code dir="auto">GET /api/provenance</code></td><td></td></tr><tr><td><code dir="auto">guard</code></td><td>storage, platform dir, git ref</td><td>the losses a change is about to cause</td><td><code dir="auto">spec guard</code></td><td></td><td></td></tr><tr><td><code dir="auto">gate</code></td><td>storage, platform dir, repo, requirement id</td><td>the gate outcome and <code dir="auto">build_id</code>, or <code dir="auto">usage</code> for an unknown repo</td><td><code dir="auto">spec gate</code></td><td></td><td></td></tr><tr><td><code dir="auto">resolveMemberPin</code>, <code dir="auto">writeMemberConfig</code></td><td>repo dir, pin override, force</td><td>the pin and its source; wrote or already configured, or <code dir="auto">usage</code> / <code dir="auto">conflict</code></td><td><code dir="auto">spec init</code></td><td></td><td></td></tr><tr><td><code dir="auto">newDomain</code>, <code dir="auto">listDomains</code></td><td>platform dir, key</td><td>the scaffolded file, or <code dir="auto">usage</code> / <code dir="auto">conflict</code> / <code dir="auto">invalid_domain_file</code>; the <code dir="auto">{ key, scope }</code> rows</td><td><code dir="auto">spec domain</code></td><td></td><td></td></tr><tr><td><code dir="auto">writeGlossary</code>, <code dir="auto">migrateGlossary</code>, <code dir="auto">checkGlossary</code></td><td>platform dir</td><td>the generated count, the migrated count or a skip, clean or drift</td><td><code dir="auto">spec glossary</code></td><td></td><td></td></tr></tbody></table>
|
|
390
390
|
<p>Reads take an open <code dir="auto">Storage</code> handle because the surface owns the handle’s lifetime: the CLI and MCP open one per call through <code dir="auto">withIndex</code>, the API keeps one for the life of the server. Writes take the platform directory because they edit <code dir="auto">SPEC.json</code> files. A lifecycle write takes a fresh-tags callback for its worklist, so a one-shot surface cold-rebuilds a throwaway index while the API re-indexes into the handle it keeps. Every guard runs before the first byte is written (REQ-038 <!-- @spec REQ-038 -->), and <code dir="auto">operations-parity.test.ts</code> proves each surface writes the same envelope.</p>
|
|
391
391
|
<div class="sl-heading-wrapper level-h2"><h2 id="the-single-seams">The single seams</h2><a class="sl-anchor-link" href="#the-single-seams"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “The single seams”</span></a></div>
|
|
392
392
|
<p>Each of these exists exactly once, and a grep fence in <code dir="auto">scripts/arch-fences.sh</code> fails CI if a second copy appears. Every fence label starts with the id of the requirement the fence enforces, and the fence function carries that id as its <code dir="auto">@spec</code> tag.</p>
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
})();
|
|
71
71
|
</script> </sl-sidebar-state-persist> <div class="md:sl-hidden"> <div class="mobile-preferences sl-flex astro-2lx56rho"> <div class="social-icons astro-2lx56rho"> <a href="https://github.com/spec-engine/spec-engine" rel="me" class="sl-flex astro-opyhioab"><span class="sr-only astro-opyhioab">GitHub</span><svg aria-hidden="true" class="astro-opyhioab astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M12 .3a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57L9 21.07c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .3Z"/></svg></a> </div> <starlight-theme-select> <label style="--sl-select-width: 6.25em" class="astro-oxpvutiw"> <span class="sr-only astro-oxpvutiw">Select theme</span> <svg aria-hidden="true" class="icon label-icon astro-oxpvutiw astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M21 14h-1V7a3 3 0 0 0-3-3H7a3 3 0 0 0-3 3v7H3a1 1 0 0 0-1 1v2a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3v-2a1 1 0 0 0-1-1ZM6 7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v7H6V7Zm14 10a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-1h16v1Z"/></svg> <select autocomplete="off" class="astro-oxpvutiw"> <option value="dark" class="astro-oxpvutiw">Dark</option><option value="light" class="astro-oxpvutiw">Light</option><option value="auto" selected class="astro-oxpvutiw">Auto</option> </select> <svg aria-hidden="true" class="icon caret astro-oxpvutiw astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M17 9.17a1 1 0 0 0-1.41 0L12 12.71 8.46 9.17a1 1 0 1 0-1.41 1.42l4.24 4.24a1.002 1.002 0 0 0 1.42 0L17 10.59a1.002 1.002 0 0 0 0-1.42Z"/></svg> </label> </starlight-theme-select> <script>
|
|
72
72
|
StarlightThemeProvider.updatePickers();
|
|
73
|
-
</script> </div> </div> </div> </div> </nav> <div class="main-frame astro-to3xypmc"> <script type="module">const a=document.getElementById("starlight__sidebar"),n=a?.querySelector("sl-sidebar-state-persist"),o="sl-sidebar-state",i=()=>{let t=[];const e=n?.dataset.hash||"";try{const s=sessionStorage.getItem(o),r=JSON.parse(s||"{}");Array.isArray(r.open)&&r.hash===e&&(t=r.open)}catch{}return{hash:e,open:t,scroll:a?.scrollTop||0}},c=t=>{try{sessionStorage.setItem(o,JSON.stringify(t))}catch{}},d=()=>c(i()),l=(t,e)=>{const s=i();s.open[e]=t,c(s)};n?.addEventListener("click",t=>{if(!(t.target instanceof Element))return;const e=t.target.closest("summary")?.closest("details");if(!e)return;const s=e.querySelector("sl-sidebar-restore"),r=parseInt(s?.dataset.index||"");isNaN(r)||l(!e.open,r)});addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"&&d()});addEventListener("pageHide",d);</script> <div class="lg:sl-flex astro-blhl7r6q"> <aside class="right-sidebar-container print:hidden astro-blhl7r6q"> <div class="right-sidebar astro-blhl7r6q"> <div class="lg:sl-hidden astro-l5m3cfel"><mobile-starlight-toc data-min-h="2" data-max-h="3" class="astro-goxitxj7"><nav aria-labelledby="starlight__on-this-page--mobile" class="astro-goxitxj7"><details id="starlight__mobile-toc" class="astro-goxitxj7"><summary id="starlight__on-this-page--mobile" class="sl-flex astro-goxitxj7"><span class="toggle sl-flex astro-goxitxj7">On this page<svg aria-hidden="true" class="caret astro-goxitxj7 astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg></span><span class="display-current astro-goxitxj7"></span></summary><div class="dropdown astro-goxitxj7"><ul class="isMobile astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#always-on-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Always-on diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#glossary-term-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Glossary (TERM) diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#trusted-red-proof-gate---results-junitxml" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Trusted-red proof gate (--results <junit.xml>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#governance-diagnostics---base-ref" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Governance diagnostics (--base <ref>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#opt-in-policy-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Opt-in policy diagnostics</span> </a> </li> </ul></div></details></nav></mobile-starlight-toc><script type="module" src="/_astro/MobileTableOfContents.astro_astro_type_script_index_0_lang.hwBsy0Mo.js"></script></div><div class="right-sidebar-panel sl-hidden lg:sl-block astro-l5m3cfel"><div class="sl-container astro-l5m3cfel"><starlight-toc data-min-h="2" data-max-h="3"><nav aria-labelledby="starlight__on-this-page"><h2 id="starlight__on-this-page">On this page</h2><ul class="astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#always-on-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Always-on diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#glossary-term-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Glossary (TERM) diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#trusted-red-proof-gate---results-junitxml" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Trusted-red proof gate (--results <junit.xml>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#governance-diagnostics---base-ref" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Governance diagnostics (--base <ref>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#opt-in-policy-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Opt-in policy diagnostics</span> </a> </li> </ul></nav></starlight-toc><script type="module" src="/_astro/TableOfContents.astro_astro_type_script_index_0_lang.FuRcXuRY.js"></script></div></div> </div> </aside> <div class="main-pane astro-blhl7r6q"> <main data-pagefind-body class="astro-ioexmpvj" lang="en" dir="ltr"> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <h1 id="_top" class="astro-4b4mtvou">Integrity Checks</h1> </div> </div> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <div class="sl-markdown-content"> <p><code dir="auto">spec check</code> runs cross-repo integrity, coverage, and drift diagnostics. Error-severity diagnostics drive exit 1; warnings alone exit 0. <code dir="auto">--ci</code> forces a cold rebuild (deletes the DB first — correctness never trusts a warm index).</p>
|
|
73
|
+
</script> </div> </div> </div> </div> </nav> <div class="main-frame astro-to3xypmc"> <script type="module">const a=document.getElementById("starlight__sidebar"),n=a?.querySelector("sl-sidebar-state-persist"),o="sl-sidebar-state",i=()=>{let t=[];const e=n?.dataset.hash||"";try{const s=sessionStorage.getItem(o),r=JSON.parse(s||"{}");Array.isArray(r.open)&&r.hash===e&&(t=r.open)}catch{}return{hash:e,open:t,scroll:a?.scrollTop||0}},c=t=>{try{sessionStorage.setItem(o,JSON.stringify(t))}catch{}},d=()=>c(i()),l=(t,e)=>{const s=i();s.open[e]=t,c(s)};n?.addEventListener("click",t=>{if(!(t.target instanceof Element))return;const e=t.target.closest("summary")?.closest("details");if(!e)return;const s=e.querySelector("sl-sidebar-restore"),r=parseInt(s?.dataset.index||"");isNaN(r)||l(!e.open,r)});addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"&&d()});addEventListener("pageHide",d);</script> <div class="lg:sl-flex astro-blhl7r6q"> <aside class="right-sidebar-container print:hidden astro-blhl7r6q"> <div class="right-sidebar astro-blhl7r6q"> <div class="lg:sl-hidden astro-l5m3cfel"><mobile-starlight-toc data-min-h="2" data-max-h="3" class="astro-goxitxj7"><nav aria-labelledby="starlight__on-this-page--mobile" class="astro-goxitxj7"><details id="starlight__mobile-toc" class="astro-goxitxj7"><summary id="starlight__on-this-page--mobile" class="sl-flex astro-goxitxj7"><span class="toggle sl-flex astro-goxitxj7">On this page<svg aria-hidden="true" class="caret astro-goxitxj7 astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg></span><span class="display-current astro-goxitxj7"></span></summary><div class="dropdown astro-goxitxj7"><ul class="isMobile astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#always-on-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Always-on diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#glossary-term-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Glossary (TERM) diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#trusted-red-proof-gate---results-junitxml" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Trusted-red proof gate (--results <junit.xml>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#governance-diagnostics---base-ref" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Governance diagnostics (--base <ref>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#opt-in-policy-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Opt-in policy diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#severity-policy-spec-enginecheckjson" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Severity policy (spec-engine/check.json)</span> </a> </li> </ul></div></details></nav></mobile-starlight-toc><script type="module" src="/_astro/MobileTableOfContents.astro_astro_type_script_index_0_lang.hwBsy0Mo.js"></script></div><div class="right-sidebar-panel sl-hidden lg:sl-block astro-l5m3cfel"><div class="sl-container astro-l5m3cfel"><starlight-toc data-min-h="2" data-max-h="3"><nav aria-labelledby="starlight__on-this-page"><h2 id="starlight__on-this-page">On this page</h2><ul class="astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#always-on-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Always-on diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#glossary-term-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Glossary (TERM) diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#trusted-red-proof-gate---results-junitxml" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Trusted-red proof gate (--results <junit.xml>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#governance-diagnostics---base-ref" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Governance diagnostics (--base <ref>)</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#opt-in-policy-diagnostics" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Opt-in policy diagnostics</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#severity-policy-spec-enginecheckjson" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Severity policy (spec-engine/check.json)</span> </a> </li> </ul></nav></starlight-toc><script type="module" src="/_astro/TableOfContents.astro_astro_type_script_index_0_lang.FuRcXuRY.js"></script></div></div> </div> </aside> <div class="main-pane astro-blhl7r6q"> <main data-pagefind-body class="astro-ioexmpvj" lang="en" dir="ltr"> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <h1 id="_top" class="astro-4b4mtvou">Integrity Checks</h1> </div> </div> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <div class="sl-markdown-content"> <p><code dir="auto">spec check</code> runs cross-repo integrity, coverage, and drift diagnostics. Error-severity diagnostics drive exit 1; warnings alone exit 0. <code dir="auto">--ci</code> forces a cold rebuild (deletes the DB first — correctness never trusts a warm index).</p>
|
|
74
74
|
<div class="sl-heading-wrapper level-h2"><h2 id="always-on-diagnostics">Always-on diagnostics</h2><a class="sl-anchor-link" href="#always-on-diagnostics"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Always-on diagnostics”</span></a></div>
|
|
75
75
|
|
|
76
76
|
|
|
@@ -202,7 +202,13 @@
|
|
|
202
202
|
|
|
203
203
|
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
<table><thead><tr><th>Code</th><th>Severity</th><th>Condition</th></tr></thead><tbody><tr><td><code dir="auto">INVALID_DOMAIN_FILE</code></td><td>error</td><td>A <code dir="auto">SPEC.json</code> fails the structural schema (bad JSON, malformed <code dir="auto">key</code>/<code dir="auto">id</code>, missing <code dir="auto">statement</code>, unknown envelope key). The index build refuses, and <code dir="auto">spec check</code> prints only these rows, one per failing field across every invalid file</td></tr><tr><td><code dir="auto">DUP_ID</code></td><td>error</td><td>The same requirement ID appears twice</td></tr><tr><td><code dir="auto">BROKEN_SUPERSEDE</code></td><td>error</td><td><code dir="auto">supersededBy</code> points at a missing ID</td></tr><tr><td><code dir="auto">CYCLIC_SUPERSEDE</code></td><td>error</td><td>A circular supersession chain (<code dir="auto">A → B → A</code>) — the chain is the change history, so a cycle is corrupt history</td></tr><tr><td><code dir="auto">BAD_STATUS</code></td><td>error</td><td>Entry status outside <code dir="auto">active</code> / <code dir="auto">draft</code> / <code dir="auto">superseded</code> / <code dir="auto">deprecated</code></td></tr><tr><td><code dir="auto">DANGLING_TAG</code></td><td>error</td><td>A <code dir="auto">@spec</code> tag references no requirement</td></tr><tr><td><code dir="auto">SUPERSEDED_REFERENCED</code></td><td>error</td><td>Code still tags a superseded requirement (retag to the successor)</td></tr><tr><td><code dir="auto">ORPHAN_REQ</code></td><td>error</td><td>An active requirement has no implementing <code dir="auto">@spec</code> tag</td></tr><tr><td><code dir="auto">UNVERIFIED_REQ</code></td><td>warning</td><td>An active requirement is implemented but has no verifying test tag</td></tr><tr><td><code dir="auto">DRAFT_REFERENCED</code></td><td>error / warning</td><td>A tag references a draft requirement: error on a verifying (test) tag, warning on an implementing or documenting tag</td></tr><tr><td><code dir="auto">DRIFT</code></td><td>error</td><td>A member is pinned behind the version at which a requirement it references changed</td></tr><tr><td><code dir="auto">BROKEN_FILE_REF</code></td><td>error</td><td>An active or draft requirement’s <code dir="auto">livesIn</code> entry does not resolve to a file under the platform root (a terminal-status entry is exempt)</td></tr><tr><td><code dir="auto">NO_SPEC_CONFIG</code></td><td>warning</td><td>A declared member is present on disk with no <code dir="auto">spec-engine.member.json</code></td></tr><tr><td><code dir="auto">MALFORMED_FILE</code></td><td>error (warning for a manifest)</td><td>A <code dir="auto">platform-map.json</code>, a package or workspace manifest, or platform-map’s per-user file failed to parse or validate</td></tr><tr><td><code dir="auto">MARKER_MISMATCH</code></td><td>error</td><td>A member’s <code dir="auto">platform-map.json</code> marker names a different platform</td></tr><tr><td><code dir="auto">MEMBER_MISSING</code></td><td>warning</td><td>A declared member is not on this machine; it is not scanned</td></tr><tr><td><code dir="auto">MARKER_MISSING</code></td><td>warning</td><td>A declared member has no <code dir="auto">platform-map.json</code> marker</td></tr><tr><td><code dir="auto">PLATFORM_NOT_LOCATED</code></td><td>warning</td><td>A marker names a platform this machine cannot find</td></tr><tr><td><code dir="auto">SCAN_TRUNCATED</code></td><td>warning</td><td>A workspace walk hit its depth or entry cap</td></tr><tr><td><code dir="auto">UNLISTED_REPO</code></td><td>warning</td><td>A repository in the platform folder is not a member; its tags are not scanned until <code dir="auto">spec init <name></code> declares it</td></tr><tr><td><code dir="auto">UNDECLARED_PLATFORM</code></td><td>warning</td><td>A folder of repositories with no platform file; nothing in it is a member until <code dir="auto">spec init <name></code> declares the first one</td></tr><tr><td><code dir="auto">BROKEN_RELATES</code></td><td>warning</td><td>A <code dir="auto">relates</code> entry points at a nonexistent requirement ID</td></tr><tr><td><code dir="auto">RELATES_SUPERSEDED</code></td><td>warning</td><td>A <code dir="auto">relates</code> entry points at a superseded requirement</td></tr><tr><td><code dir="auto">SELF_RELATES</code></td><td>warning</td><td>A <code dir="auto">relates</code> entry names its own requirement (dropped, but surfaced)</td></tr><tr><td><code dir="auto">UNKNOWN_ROLE</code></td><td>warning</td><td>An <code dir="auto">issues</code> entry uses a role outside <code dir="auto">created</code> / <code dir="auto">supersedes-via</code> / <code dir="auto">amends-via</code> — surfaced and dropped, never stored</td></tr></tbody></table>
|
|
211
|
+
<p>Coverage counts only active requirements: a draft never raises <code dir="auto">ORPHAN_REQ</code> or <code dir="auto">UNVERIFIED_REQ</code>. <!-- @spec CHCK-032 --></p>
|
|
206
212
|
<div class="sl-heading-wrapper level-h2"><h2 id="glossary-term-diagnostics">Glossary (TERM) diagnostics</h2><a class="sl-anchor-link" href="#glossary-term-diagnostics"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Glossary (TERM) diagnostics”</span></a></div>
|
|
207
213
|
|
|
208
214
|
|
|
@@ -260,7 +266,7 @@
|
|
|
260
266
|
<table><thead><tr><th>Code</th><th>Severity</th><th>Condition</th></tr></thead><tbody><tr><td><code dir="auto">UNPROVEN_REQ</code></td><td>error</td><td>An active requirement has verifying tags but no <em>passing</em> correlated test</td></tr><tr><td><code dir="auto">PROOFS_UNCONFIRMED</code></td><td>warning</td><td>No <code dir="auto">--results</code> supplied — the gate falls back to presence-only mode (this warning is the reminder; routed to stderr under <code dir="auto">--json</code>)</td></tr></tbody></table>
|
|
261
267
|
<div class="expressive-code"><link rel="stylesheet" href="/_astro/ec.v4551.css"><script type="module" src="/_astro/ec.0vx5m.js"></script><figure class="frame is-terminal not-content"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="shell"><code><div class="ec-line"><div class="code"><span style="--0:#82AAFF;--1:#3B61B0">bun</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">test</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#82AAFF;--1:#3B61B0">--reporter=junit</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#82AAFF;--1:#3B61B0">--reporter-outfile=.spec-engine/results.xml</span></div></div><div class="ec-line"><div class="code"><span style="--0:#82AAFF;--1:#3B61B0">spec</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">check</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">.</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#82AAFF;--1:#3B61B0">--ci</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#82AAFF;--1:#3B61B0">--results</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">.spec-engine/results.xml</span></div></div></code></pre><div class="copy"><div aria-live="polite"></div><button title="Copy to clipboard" data-copied="Copied!" data-code="bun test --reporter=junit --reporter-outfile=.spec-engine/results.xmlspec check . --ci --results .spec-engine/results.xml"><div></div></button></div></figure></div>
|
|
262
268
|
<div class="sl-heading-wrapper level-h2"><h2 id="governance-diagnostics---base-ref">Governance diagnostics (<code dir="auto">--base <ref></code>)</h2><a class="sl-anchor-link" href="#governance-diagnostics---base-ref"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Governance diagnostics (--base <ref>)”</span></a></div>
|
|
263
|
-
<p>With a git base ref, <code dir="auto">check</code> also diffs the requirement set against that ref:</p>
|
|
269
|
+
<p>With a git base ref, <code dir="auto">check</code> also diffs the requirement set against that ref. Without <code dir="auto">--base</code>, the removal and loss rows are computed against <code dir="auto">HEAD</code> whenever git resolves:</p>
|
|
264
270
|
|
|
265
271
|
|
|
266
272
|
|
|
@@ -287,7 +293,10 @@
|
|
|
287
293
|
|
|
288
294
|
|
|
289
295
|
<table><thead><tr><th>Code</th><th>Severity</th><th>Condition</th></tr></thead><tbody><tr><td><code dir="auto">REQUIREMENT_REMOVED</code></td><td>error</td><td>A requirement present at the base ref is gone with no approved supersession</td></tr><tr><td><code dir="auto">UNAPPROVED_STATUS_FLIP</code></td><td>warning†</td><td>A flip to superseded/deprecated whose CODEOWNERS domain owner is absent from <code dir="auto">--approved-by</code> — †error under <code dir="auto">--require-owner-approval</code></td></tr><tr><td><code dir="auto">PARTIAL_PROPAGATION</code></td><td>error</td><td>Needs <code dir="auto">--base</code> <strong>and</strong> <code dir="auto">--results</code>: a changed requirement where some bound tests pass and some fail — one site migrated, another still red</td></tr></tbody></table>
|
|
290
|
-
<p
|
|
296
|
+
<p>| <code dir="auto">IMPL_LOST</code> | error | The change removes the last implementing tag of a surviving active requirement |
|
|
297
|
+
| <code dir="auto">VERIFY_LOST</code> | warning | The change removes the last verifying tag of a surviving active requirement |
|
|
298
|
+
| <code dir="auto">SPEC_FILE_DELETED</code> | error | A <code dir="auto">SPEC.json</code> present at the base ref is gone |</p>
|
|
299
|
+
<p>The three loss rows are the ones <code dir="auto">spec guard</code> reports against the same ref; guard’s own <code dir="auto">REQUIREMENT_REMOVED</code> row is not repeated. See <a href="/commands/#spec-guard-platformdir">Commands</a>.</p>
|
|
291
300
|
<div class="sl-heading-wrapper level-h2"><h2 id="opt-in-policy-diagnostics">Opt-in policy diagnostics</h2><a class="sl-anchor-link" href="#opt-in-policy-diagnostics"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Opt-in policy diagnostics”</span></a></div>
|
|
292
301
|
|
|
293
302
|
|
|
@@ -304,4 +313,15 @@
|
|
|
304
313
|
|
|
305
314
|
|
|
306
315
|
|
|
307
|
-
<table><thead><tr><th>Code</th><th>Severity</th><th>Condition</th></tr></thead><tbody><tr><td><code dir="auto">UNSOURCED_CHANGE</code></td><td>warning</td><td>A superseded requirement carries no <code dir="auto">supersedes-via</code> issue. Emitted only under <code dir="auto">spec check --unsourced-change</code></td></tr></tbody></table>
|
|
316
|
+
<table><thead><tr><th>Code</th><th>Severity</th><th>Condition</th></tr></thead><tbody><tr><td><code dir="auto">UNSOURCED_CHANGE</code></td><td>warning</td><td>A superseded requirement carries no <code dir="auto">supersedes-via</code> issue. Emitted only under <code dir="auto">spec check --unsourced-change</code></td></tr></tbody></table>
|
|
317
|
+
<div class="sl-heading-wrapper level-h2"><h2 id="severity-policy-spec-enginecheckjson">Severity policy (<code dir="auto">spec-engine/check.json</code>)</h2><a class="sl-anchor-link" href="#severity-policy-spec-enginecheckjson"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Severity policy (spec-engine/check.json)”</span></a></div>
|
|
318
|
+
<p><code dir="auto">spec-engine/check.json</code> regrades diagnostics. Absent means no rules.</p>
|
|
319
|
+
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="json"><code><div class="ec-line"><div class="code"><span style="--0:#D6DEEB;--1:#403F53">{ </span><span style="--0:#7FDBCA;--1:#096E72">"severity"</span><span style="--0:#D6DEEB;--1:#403F53">: [</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#D6DEEB;--1:#403F53"> </span></span><span style="--0:#D6DEEB;--1:#403F53">{ </span><span style="--0:#7FDBCA;--1:#096E72">"code"</span><span style="--0:#D6DEEB;--1:#403F53">: </span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">UNVERIFIED_REQ</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#7FDBCA;--1:#096E72">"severity"</span><span style="--0:#D6DEEB;--1:#403F53">: </span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">error</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53"> },</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#D6DEEB;--1:#403F53"> </span></span><span style="--0:#D6DEEB;--1:#403F53">{ </span><span style="--0:#7FDBCA;--1:#096E72">"code"</span><span style="--0:#D6DEEB;--1:#403F53">: </span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">UNVERIFIED_REQ</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#7FDBCA;--1:#096E72">"severity"</span><span style="--0:#D6DEEB;--1:#403F53">: </span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">warning</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#7FDBCA;--1:#096E72">"match"</span><span style="--0:#D6DEEB;--1:#403F53">: [</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">LEGACY</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#C789D6;--1:#7C5686">BILLING-004</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">] }</span></div></div><div class="ec-line"><div class="code"><span style="--0:#D6DEEB;--1:#403F53">] }</span></div></div></code></pre><div class="copy"><div aria-live="polite"></div><button title="Copy to clipboard" data-copied="Copied!" data-code="{ "severity": [ { "code": "UNVERIFIED_REQ", "severity": "error" }, { "code": "UNVERIFIED_REQ", "severity": "warning", "match": ["LEGACY", "BILLING-004"] }] }"><div></div></button></div></figure></div>
|
|
320
|
+
<ul>
|
|
321
|
+
<li><code dir="auto">code</code> is any diagnostic code; <code dir="auto">severity</code> is <code dir="auto">error</code>, <code dir="auto">warning</code>, or <code dir="auto">off</code>.</li>
|
|
322
|
+
<li><code dir="auto">match</code> lists domain keys and requirement ids. A scoped rule applies only to rows whose requirement is listed or carries a listed key.</li>
|
|
323
|
+
<li>The most specific rule wins: an id match, then a domain match, then an unscoped rule. Among equals, the later rule wins.</li>
|
|
324
|
+
<li><code dir="auto">off</code> drops the row from every output.</li>
|
|
325
|
+
<li>Exit 1 follows the graded severities, on every surface.</li>
|
|
326
|
+
<li>A file that fails the schema exits 2 with <code dir="auto">spec-engine/check.json: <path>: <reason></code>.</li>
|
|
327
|
+
</ul> </div> <footer class="sl-flex astro-5h22m7ac"> <div class="meta sl-flex astro-5h22m7ac"> <a href="https://github.com/spec-engine/spec-engine/edit/main/packages/site/src/content/docs/checks.md" class="sl-flex print:hidden astro-txs4wy42"><svg aria-hidden="true" class="astro-txs4wy42 astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.2em;"><path d="M22 7.24a1 1 0 0 0-.29-.71l-4.24-4.24a1 1 0 0 0-1.1-.22 1 1 0 0 0-.32.22l-2.83 2.83L2.29 16.05a1 1 0 0 0-.29.71V21a1 1 0 0 0 1 1h4.24a1 1 0 0 0 .76-.29l10.87-10.93L21.71 8c.1-.1.17-.2.22-.33a1 1 0 0 0 0-.24v-.14l.07-.05ZM6.83 20H4v-2.83l9.93-9.93 2.83 2.83L6.83 20ZM18.17 8.66l-2.83-2.83 1.42-1.41 2.82 2.82-1.41 1.42Z"/></svg>Edit page</a> </div> <div class="pagination-links print:hidden astro-7kn6nbmm" dir="ltr"> <a href="/tags/" rel="prev" class="astro-7kn6nbmm"> <svg aria-hidden="true" class="astro-7kn6nbmm astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.5rem;"><path d="M17 11H9.41l3.3-3.29a1.004 1.004 0 1 0-1.42-1.42l-5 5a1 1 0 0 0-.21.33 1 1 0 0 0 0 .76 1 1 0 0 0 .21.33l5 5a1.002 1.002 0 0 0 1.639-.325 1 1 0 0 0-.219-1.095L9.41 13H17a1 1 0 0 0 0-2Z"/></svg> <span class="astro-7kn6nbmm"> Previous <br class="astro-7kn6nbmm"> <span class="link-title astro-7kn6nbmm">Tags</span> </span> </a> <a href="/guides/adoption/" rel="next" class="astro-7kn6nbmm"> <svg aria-hidden="true" class="astro-7kn6nbmm astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.5rem;"><path d="M17.92 11.62a1.001 1.001 0 0 0-.21-.33l-5-5a1.003 1.003 0 1 0-1.42 1.42l3.3 3.29H7a1 1 0 0 0 0 2h7.59l-3.3 3.29a1.002 1.002 0 0 0 .325 1.639 1 1 0 0 0 1.095-.219l5-5a1 1 0 0 0 .21-.33 1 1 0 0 0 0-.76Z"/></svg> <span class="astro-7kn6nbmm"> Next <br class="astro-7kn6nbmm"> <span class="link-title astro-7kn6nbmm">Adoption Guide</span> </span> </a> </div> </footer> </div> </div> </main> </div> </div> </div> </div> </body></html>
|
|
@@ -197,7 +197,7 @@
|
|
|
197
197
|
<p>One-time hard cutover: convert every legacy canonical <code dir="auto">SPEC.md</code> to a schema-validated sibling <code dir="auto">SPEC.json</code>, then delete the <code dir="auto">SPEC.md</code>. Idempotent — skips already-migrated dirs.</p>
|
|
198
198
|
<p><strong>Exit codes:</strong> 0 / 2</p>
|
|
199
199
|
<div class="sl-heading-wrapper level-h3"><h3 id="spec-req-domain-prefix-platformdir"><code dir="auto">spec req <domain-prefix> [platformDir]</code></h3><a class="sl-anchor-link" href="#spec-req-domain-prefix-platformdir"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “spec req <domain-prefix> [platformDir]”</span></a></div>
|
|
200
|
-
<p><strong>Piped:</strong> prints the next unused requirement ID (e.g. <code dir="auto">BILLING-010</code>) — zero prompts, zero writes. <strong>TTY:</strong> interactive authoring. <strong><code dir="auto">--text</code> (+ <code dir="auto">--why</code> / <code dir="auto">--lives</code>):</strong> appends a born-active entry non-interactively through the validated write seam. <strong><code dir="auto">--draft</code>:</strong> the entry is born Draft instead (promote it with <code dir="auto">spec accept</code>). Prefix is case-insensitive (<code dir="auto">bil</code> → <code dir="auto">BILLING</code>; ambiguous → exit 2). <code dir="auto">spec req <domain></code> alone prints the domain’s charter before authoring.</p>
|
|
200
|
+
<p><strong>Piped:</strong> prints the next unused requirement ID (e.g. <code dir="auto">BILLING-010</code>) — zero prompts, zero writes. <strong>TTY:</strong> interactive authoring. <strong><code dir="auto">--text</code> (+ <code dir="auto">--why</code> / <code dir="auto">--lives</code> / <code dir="auto">--relates</code>):</strong> appends a born-active entry non-interactively through the validated write seam. <strong><code dir="auto">--draft</code>:</strong> the entry is born Draft instead (promote it with <code dir="auto">spec accept</code>). Prefix is case-insensitive (<code dir="auto">bil</code> → <code dir="auto">BILLING</code>; ambiguous → exit 2). <code dir="auto">spec req <domain></code> alone prints the domain’s charter before authoring.</p>
|
|
201
201
|
<p><strong>Exit codes:</strong> 0 / 2</p>
|
|
202
202
|
<div class="sl-heading-wrapper level-h3"><h3 id="spec-term-"><code dir="auto">spec term …</code></h3><a class="sl-anchor-link" href="#spec-term-"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “spec term …”</span></a></div>
|
|
203
203
|
<p>The glossary authoring surface — a term is a requirement row in the reserved <code dir="auto">TERM</code> domain (definition in the statement, headword in <code dir="auto">term</code>, synonyms in <code dir="auto">aliases</code>):</p>
|
|
@@ -213,7 +213,7 @@
|
|
|
213
213
|
<p>The GLOSSARY.md round-trip. Default: <strong>generate</strong> GLOSSARY.md from the TERM store, byte-stable and LLM-free. <code dir="auto">--migrate</code>: one-time parse of an existing GLOSSARY.md into <code dir="auto">TERM-001..N</code> (idempotent-skip). <code dir="auto">--check</code>: regenerate into a buffer and fail (exit 1) if the committed file drifts — a CI fence.</p>
|
|
214
214
|
<p><strong>Exit codes:</strong> 0 / 1 / 2</p>
|
|
215
215
|
<div class="sl-heading-wrapper level-h3"><h3 id="spec-supersede-reqid-platformdir"><code dir="auto">spec supersede <reqId> [platformDir]</code></h3><a class="sl-anchor-link" href="#spec-supersede-reqid-platformdir"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “spec supersede <reqId> [platformDir]”</span></a></div>
|
|
216
|
-
<p>The post-ship lifecycle move, mechanized. Flips the entry to superseded, mints the successor (<code dir="auto">--text</code> required non-TTY; <code dir="auto">--why</code
|
|
216
|
+
<p>The post-ship lifecycle move, mechanized. Flips the entry to superseded, mints the successor (<code dir="auto">--text</code> required non-TTY; <code dir="auto">--why</code>, <code dir="auto">--lives</code>, <code dir="auto">--relates</code>, cites, aliases, term, and section default to copies of the predecessor’s; issues do not carry over), reindexes, and prints the <strong>retag worklist</strong> — every code site still on the old ID. The target must be Active.</p>
|
|
217
217
|
<p>On a requirement domain the reported <code dir="auto">spec_version</code> is the <strong>derived</strong> domain version after the supersession — no authored counter is written, and <code dir="auto">--no-bump</code> is a no-op (there is no counter to hold back). On the reserved TERM domain the authored <code dir="auto">specVersion</code> still bumps (it is the term-drift pin) and <code dir="auto">--no-bump</code> opts out.</p>
|
|
218
218
|
<p><code dir="auto">--json</code>: <code dir="auto">{ old_id, new_id, file, spec_version, retag: [...] }</code></p>
|
|
219
219
|
<p><strong>Exit codes:</strong> 0 / 2</p>
|
|
@@ -221,7 +221,7 @@
|
|
|
221
221
|
<p>Cross-domain supersede for taxonomy reorganization: mints the successor as the next id in <code dir="auto"><NEW-DOMAIN></code> (which must exist), carrying the source’s fields (<code dir="auto">--text</code>/<code dir="auto">--why</code>/<code dir="auto">--lives</code> override), flips the source to superseded with a cross-domain <code dir="auto">supersededBy</code>, and emits the retag worklist. Both envelopes validate before either is written — a reject never half-applies. Only Active requirements move; moving into the source’s own domain is a usage error (use <code dir="auto">supersede</code>).</p>
|
|
222
222
|
<p><strong>Exit codes:</strong> 0 / 2</p>
|
|
223
223
|
<div class="sl-heading-wrapper level-h3"><h3 id="spec-amend-reqid-platformdir"><code dir="auto">spec amend <reqId> [platformDir]</code></h3><a class="sl-anchor-link" href="#spec-amend-reqid-platformdir"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “spec amend <reqId> [platformDir]”</span></a></div>
|
|
224
|
-
<p>Revise
|
|
224
|
+
<p>Revise a requirement in place — same ID, no version change (the domain version only derives from supersessions). Field flags name what changes (<code dir="auto">--text</code>/<code dir="auto">--why</code>/<code dir="auto">--lives</code>/<code dir="auto">--relates</code>, at least one); untouched fields stay byte-identical. <code dir="auto">--lives</code> and <code dir="auto">--relates</code> repeat or comma-separate and replace the whole list; an empty value clears it. Only Active and Draft entries amend. A requirement present in its domain file at the newest <code dir="auto">v*</code> tag merged into HEAD is released: its <code dir="auto">--text</code> and <code dir="auto">--why</code> refuse with exit 2 and name <code dir="auto">spec supersede</code>; <code dir="auto">--lives</code> and <code dir="auto">--relates</code> still write in place. With no <code dir="auto">v*</code> tag or no git, nothing is released.</p>
|
|
225
225
|
<p><strong>Exit codes:</strong> 0 / 2</p>
|
|
226
226
|
<div class="sl-heading-wrapper level-h3"><h3 id="spec-accept-reqid-platformdir"><code dir="auto">spec accept <reqId> [platformDir]</code></h3><a class="sl-anchor-link" href="#spec-accept-reqid-platformdir"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “spec accept <reqId> [platformDir]”</span></a></div>
|
|
227
227
|
<p>Promote a Draft requirement to Active — same ID, every other field untouched, no version change. A Draft is never an orphan, never unverified, and never counted in coverage; accepting it makes it an obligation.</p>
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"1.5.2","languages":{"en":{"hash":"
|
|
1
|
+
{"version":"1.5.2","languages":{"en":{"hash":"en_c6c8e941d5","wasm":"en","page_count":12}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","＿"]}
|
|
Binary file
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
<div class="sl-heading-wrapper level-h2"><h2 id="the-platform-root">The platform root</h2><a class="sl-anchor-link" href="#the-platform-root"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “The platform root”</span></a></div>
|
|
84
84
|
<p>The platform root is the directory that holds the canonical <code dir="auto">spec-engine/</code> tree. When the platform is declared, the same directory holds the platform file. Every <code dir="auto">spec</code> command resolves its root through platform-map’s <code dir="auto">locate()</code>: from wherever the command ran, walk upward to the nearest directory holding a <code dir="auto">platform-map.json</code> or a <code dir="auto">.git</code> entry, stopping at the home directory or the filesystem root, then resolve a marker to its platform through the parent directory or the per-user file. A root that <code dir="auto">locate()</code> finds but that holds no <code dir="auto">spec-engine/</code> directory is not a Spec Engine platform, and the command exits 2. <!-- @spec INIT-034 --></p>
|
|
85
85
|
<p>The index-building commands take the platform directory as an argument and ask platform-map to describe that directory. A directory that platform-map does not recognize as a starting point, one with neither a <code dir="auto">.git</code> entry nor a <code dir="auto">platform-map.json</code> inside a larger repository (a spec tree kept in a subfolder, such as a committed fixture), is mapped as a lone single repository: one coverage column named by the directory, and no platform-map diagnostics.</p>
|
|
86
|
-
<p>The platform version is derived, never authored. It is the maximum of the domain versions under <code dir="auto">spec-engine/</code>. A domain file that fails to parse contributes nothing to that number and
|
|
86
|
+
<p>The platform version is derived, never authored. It is the maximum of the domain versions under <code dir="auto">spec-engine/</code>. A domain file that fails to parse contributes nothing to that number, and the index build then refuses: the command prints only that file’s <code dir="auto">INVALID_DOMAIN_FILE</code> rows and exits 1, leaving the index on disk as it was. <!-- @spec INIT-029 --></p>
|
|
87
87
|
<div class="sl-heading-wrapper level-h2"><h2 id="members">Members</h2><a class="sl-anchor-link" href="#members"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Members”</span></a></div>
|
|
88
88
|
<p>A member is a name in the platform file’s <code dir="auto">members</code> list. Nothing else makes a directory a member: not a <code dir="auto">.git</code> entry, not a <code dir="auto">package.json</code>, not a <code dir="auto">spec-engine.member.json</code>. A repository sitting in the platform folder that nobody declared is platform-map’s <code dir="auto">UNLISTED_REPO</code>, and <code dir="auto">spec check</code> reports it so the repository’s <code dir="auto">@spec</code> tags never go unscanned in silence.</p>
|
|
89
89
|
<p><code dir="auto">spec init <name></code> is the one command that makes a repository a member. It declares the repository through platform-map’s <code dir="auto">init</code> (an entry in the platform file and a marker in the repository), then writes the repository’s <code dir="auto">spec-engine.member.json</code>. Run on a repository that is already declared, it only writes the pin, and puts back a missing marker. <!-- @spec INIT-038 --></p>
|
|
@@ -73,7 +73,7 @@
|
|
|
73
73
|
</script> </div> </div> </div> </div> </nav> <div class="main-frame astro-to3xypmc"> <script type="module">const a=document.getElementById("starlight__sidebar"),n=a?.querySelector("sl-sidebar-state-persist"),o="sl-sidebar-state",i=()=>{let t=[];const e=n?.dataset.hash||"";try{const s=sessionStorage.getItem(o),r=JSON.parse(s||"{}");Array.isArray(r.open)&&r.hash===e&&(t=r.open)}catch{}return{hash:e,open:t,scroll:a?.scrollTop||0}},c=t=>{try{sessionStorage.setItem(o,JSON.stringify(t))}catch{}},d=()=>c(i()),l=(t,e)=>{const s=i();s.open[e]=t,c(s)};n?.addEventListener("click",t=>{if(!(t.target instanceof Element))return;const e=t.target.closest("summary")?.closest("details");if(!e)return;const s=e.querySelector("sl-sidebar-restore"),r=parseInt(s?.dataset.index||"");isNaN(r)||l(!e.open,r)});addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"&&d()});addEventListener("pageHide",d);</script> <div class="lg:sl-flex astro-blhl7r6q"> <aside class="right-sidebar-container print:hidden astro-blhl7r6q"> <div class="right-sidebar astro-blhl7r6q"> <div class="lg:sl-hidden astro-l5m3cfel"><mobile-starlight-toc data-min-h="2" data-max-h="3" class="astro-goxitxj7"><nav aria-labelledby="starlight__on-this-page--mobile" class="astro-goxitxj7"><details id="starlight__mobile-toc" class="astro-goxitxj7"><summary id="starlight__on-this-page--mobile" class="sl-flex astro-goxitxj7"><span class="toggle sl-flex astro-goxitxj7">On this page<svg aria-hidden="true" class="caret astro-goxitxj7 astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg></span><span class="display-current astro-goxitxj7"></span></summary><div class="dropdown astro-goxitxj7"><ul class="isMobile astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#scanned-files" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Scanned files</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#tag-kind" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Tag kind</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#verification-levels" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Verification levels</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#coverage" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Coverage</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#tag-scanner-notes" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Tag scanner notes</span> </a> </li> </ul></div></details></nav></mobile-starlight-toc><script type="module" src="/_astro/MobileTableOfContents.astro_astro_type_script_index_0_lang.hwBsy0Mo.js"></script></div><div class="right-sidebar-panel sl-hidden lg:sl-block astro-l5m3cfel"><div class="sl-container astro-l5m3cfel"><starlight-toc data-min-h="2" data-max-h="3"><nav aria-labelledby="starlight__on-this-page"><h2 id="starlight__on-this-page">On this page</h2><ul class="astro-xz67lhkg" style="--depth: 0;"> <li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#_top" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Overview</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#scanned-files" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Scanned files</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#tag-kind" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Tag kind</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#verification-levels" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Verification levels</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#coverage" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Coverage</span> </a> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#tag-scanner-notes" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Tag scanner notes</span> </a> </li> </ul></nav></starlight-toc><script type="module" src="/_astro/TableOfContents.astro_astro_type_script_index_0_lang.FuRcXuRY.js"></script></div></div> </div> </aside> <div class="main-pane astro-blhl7r6q"> <main data-pagefind-body class="astro-ioexmpvj" lang="en" dir="ltr"> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <h1 id="_top" class="astro-4b4mtvou">Tags</h1> </div> </div> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <div class="sl-markdown-content"> <p>A tag in implementation code <strong>implements</strong> a requirement; a tag in a test file <strong>verifies</strong> it, optionally at a level.</p>
|
|
74
74
|
<div class="expressive-code"><link rel="stylesheet" href="/_astro/ec.v4551.css"><script type="module" src="/_astro/ec.0vx5m.js"></script><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="ts"><code><div class="ec-line"><div class="code"><span style="--0:#C792EA;--1:#8844AE">export</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#C792EA;--1:#8844AE">function</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#82AAFF;--1:#3B61B0">renew</span><span style="--0:#D9F5DD;--1:#111111">()</span><span style="--0:#D6DEEB;--1:#403F53"> { </span><span style="--0:#919F9F;--1:#5F636F">/* ... */</span><span style="--0:#D6DEEB;--1:#403F53"> } </span><span style="--0:#919F9F;--1:#5D6376">// @spec BILLING-009</span></div></div><div class="ec-line"><div class="code"><span style="--0:#82AAFF;--1:#3B61B0">it</span><span style="--0:#D6DEEB;--1:#403F53">(</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#ECC48D;--1:#984E4D">charges at current price</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#D9F5DD;--1:#111111">()</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#C792EA;--1:#8844AE">=></span><span style="--0:#D6DEEB;--1:#403F53"> {}) </span><span style="--0:#919F9F;--1:#5D6376">// @spec BILLING-009 unit</span></div></div><div class="ec-line"><div class="code"><span style="--0:#82AAFF;--1:#3B61B0">it</span><span style="--0:#D6DEEB;--1:#403F53">(</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#ECC48D;--1:#984E4D">renews end to end</span><span style="--0:#D9F5DD;--1:#111111">"</span><span style="--0:#D6DEEB;--1:#403F53">, </span><span style="--0:#D9F5DD;--1:#111111">()</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#C792EA;--1:#8844AE">=></span><span style="--0:#D6DEEB;--1:#403F53"> {}) </span><span style="--0:#919F9F;--1:#5D6376">// @spec BILLING-009 e2e</span></div></div></code></pre><div class="copy"><div aria-live="polite"></div><button title="Copy to clipboard" data-copied="Copied!" data-code="export function renew() { /* ... */ } // @spec BILLING-009it("charges at current price", () => {}) // @spec BILLING-009 unitit("renews end to end", () => {}) // @spec BILLING-009 e2e"><div></div></button></div></figure></div>
|
|
75
75
|
<div class="sl-heading-wrapper level-h2"><h2 id="scanned-files">Scanned files</h2><a class="sl-anchor-link" href="#scanned-files"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Scanned files”</span></a></div>
|
|
76
|
-
<p>The scanner reads <code dir="auto">.ts</code>, <code dir="auto">.tsx</code>, <code dir="auto">.js</code>, <code dir="auto">.jsx</code>, <code dir="auto">.mjs</code>, <code dir="auto">.sh</code>, <code dir="auto">.lua</code>, <code dir="auto">.luau</code>, <code dir="auto">.go</code>, and <code dir="auto">.
|
|
76
|
+
<p>The scanner reads <code dir="auto">.ts</code>, <code dir="auto">.tsx</code>, <code dir="auto">.js</code>, <code dir="auto">.jsx</code>, <code dir="auto">.mjs</code>, <code dir="auto">.sh</code>, <code dir="auto">.lua</code>, <code dir="auto">.luau</code>, <code dir="auto">.go</code>, <code dir="auto">.rs</code>, <code dir="auto">.tf</code>, <code dir="auto">.toml</code>, <code dir="auto">.sql</code>, and <code dir="auto">.css</code> files and any file named <code dir="auto">Dockerfile</code> or <code dir="auto">Dockerfile.<suffix></code>. The tag regex ignores the comment leader, so a Lua or SQL <code dir="auto">-- @spec BILLING-009</code>, a Go or Rust <code dir="auto">// @spec BILLING-009</code>, a shell, Terraform, TOML, or Dockerfile <code dir="auto"># @spec BILLING-009</code>, and a CSS <code dir="auto">/* @spec BILLING-009 */</code> all bind. Documentation is scanned from <code dir="auto">.md</code> files.</p>
|
|
77
77
|
<div class="sl-heading-wrapper level-h2"><h2 id="tag-kind">Tag kind</h2><a class="sl-anchor-link" href="#tag-kind"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only" data-pagefind-ignore="">Section titled “Tag kind”</span></a></div>
|
|
78
78
|
<p>Kind is <strong>path-derived</strong>, never authored:</p>
|
|
79
79
|
|