@spec-engine/spec-engine 0.2.0 → 0.4.0

package/README.md

@@ -45,13 +45,18 @@ Run `spec <command> --help` for flags. Many commands support `--json` for machin
 
 ## Source layout
 
-- `cli.ts`: the citty entrypoint. Lazy-imports every subcommand so the compiled binary stays fast to start.
-- `commands/`: one file per subcommand, plus `_shared.ts` (the read-command scaffold that asserts a platform before any DB write).
-- `parser/`, `indexer/`, `storage/`: authored input to derived sqlite index.
-- `check/`, `gate/`, `guard/`, `propagation/`, `relations/`, `resolve/`, `query/`, `map/`: the read and gate projections.
-- `provenance/`: tracker resolution (wires in `@spec-engine/tracker`).
-- `server/`: the Hono API behind `spec serve`.
-- `onboarding/`, `authoring/`: first-run guidance and requirement authoring.
+| Path | Role |
+|------|------|
+| `cli.ts` | citty entrypoint. Lazy-imports every subcommand so the compiled binary starts fast. |
+| `commands/` | One file per subcommand, plus `_args.ts` (shared flag specs) and `_shared.ts` (the CLI adapters over the operations). |
+| `operations/` | One function per verb. The CLI, the HTTP API, and the MCP server all call these. |
+| `indexer/`, `parser/`, `scanner/` | Authored input to derived index: discovery, `SPEC.json` parsing, `@spec` tag scanning. |
+| `storage/` | The one `bun:sqlite` importer. |
+| `check/`, `guard/`, `gate/`, `map/`, `query/`, `resolve/`, `relations/`, `propagation/`, `provenance/`, `results/` | The read and gate projections, each with a `format.ts` for text mode. |
+| `authoring/`, `onboarding/`, `base/` | Requirement authoring, first-run guidance, git base-ref helpers. |
+| `server/` | The Hono API behind `spec serve` and the MCP server behind `spec mcp`. |
+
+Components, seams, and invariants: the [architecture page](https://docs.spec-engine.dev/architecture/).
 
 ## Build
 

package/dist/docs/agent-reference/index.html

@@ -38,7 +38,7 @@
 	})();
 </script> <script type="module" src="/_astro/Search.astro_astro_type_script_index_0_lang.lq3t8uE2.js"></script>  </div> <div class="sl-hidden md:sl-flex print:hidden right-group astro-shhymrmb"> <div class="sl-flex social-icons astro-shhymrmb"> <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>
 	StarlightThemeProvider.updatePickers();
-</script> <script type="module">const r="starlight-theme",o=e=>e==="auto"||e==="dark"||e==="light"?e:"auto",c=()=>o(typeof localStorage<"u"&&localStorage.getItem(r));function n(e){typeof localStorage<"u"&&localStorage.setItem(r,e==="light"||e==="dark"?e:"")}const l=()=>matchMedia("(prefers-color-scheme: light)").matches?"light":"dark";function t(e){StarlightThemeProvider.updatePickers(e),document.documentElement.dataset.theme=e==="auto"?l():e,n(e)}matchMedia("(prefers-color-scheme: light)").addEventListener("change",()=>{c()==="auto"&&t("auto")});class s extends HTMLElement{constructor(){super(),t(c()),this.querySelector("select")?.addEventListener("change",a=>{a.currentTarget instanceof HTMLSelectElement&&t(o(a.currentTarget.value))})}}customElements.define("starlight-theme-select",s);</script> <script type="module">class s extends HTMLElement{constructor(){super();const e=this.querySelector("select");e&&(e.addEventListener("change",t=>{t.currentTarget instanceof HTMLSelectElement&&(window.location.pathname=t.currentTarget.value)}),window.addEventListener("pageshow",t=>{if(!t.persisted)return;const n=e.querySelector("option[selected]")?.index;n!==e.selectedIndex&&(e.selectedIndex=n??0)}))}}customElements.define("starlight-lang-select",s);</script> </div> </div></header> <nav class="sidebar print:hidden astro-to3xypmc" aria-label="Main"> <starlight-menu-button class="print:hidden astro-l43anhaf"> <button aria-expanded="false" aria-label="Menu" aria-controls="starlight__sidebar" class="sl-flex md:sl-hidden astro-l43anhaf"> <svg aria-hidden="true" class="open-menu astro-l43anhaf astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M3 8h18a1 1 0 1 0 0-2H3a1 1 0 0 0 0 2Zm18 8H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Zm0-5H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Z"/></svg> <svg aria-hidden="true" class="close-menu astro-l43anhaf astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="m13.41 12 6.3-6.29a1.004 1.004 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1.004 1.004 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 0 1.42.998.998 0 0 0 1.42 0l6.29-6.3 6.29 6.3a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.42L13.41 12Z"/></svg> </button> </starlight-menu-button> <script type="module">class s extends HTMLElement{constructor(){super(),this.btn=this.querySelector("button"),this.btn.addEventListener("click",()=>this.toggleExpanded());const t=this.closest("nav");t&&t.addEventListener("keyup",e=>this.closeOnEscape(e))}setExpanded(t){this.setAttribute("aria-expanded",String(t)),document.body.toggleAttribute("data-mobile-menu-expanded",t)}toggleExpanded(){this.setExpanded(this.getAttribute("aria-expanded")!=="true")}closeOnEscape(t){t.code==="Escape"&&(this.setExpanded(!1),this.btn.focus())}}customElements.define("starlight-menu-button",s);</script>  <div id="starlight__sidebar" class="sidebar-pane astro-to3xypmc"> <div class="sidebar-content sl-flex astro-to3xypmc"> <sl-sidebar-state-persist data-hash="0fmmri7" class="astro-znqwvy6e"> <script aria-hidden="true">
+</script> <script type="module">const r="starlight-theme",o=e=>e==="auto"||e==="dark"||e==="light"?e:"auto",c=()=>o(typeof localStorage<"u"&&localStorage.getItem(r));function n(e){typeof localStorage<"u"&&localStorage.setItem(r,e==="light"||e==="dark"?e:"")}const l=()=>matchMedia("(prefers-color-scheme: light)").matches?"light":"dark";function t(e){StarlightThemeProvider.updatePickers(e),document.documentElement.dataset.theme=e==="auto"?l():e,n(e)}matchMedia("(prefers-color-scheme: light)").addEventListener("change",()=>{c()==="auto"&&t("auto")});class s extends HTMLElement{constructor(){super(),t(c()),this.querySelector("select")?.addEventListener("change",a=>{a.currentTarget instanceof HTMLSelectElement&&t(o(a.currentTarget.value))})}}customElements.define("starlight-theme-select",s);</script> <script type="module">class s extends HTMLElement{constructor(){super();const e=this.querySelector("select");e&&(e.addEventListener("change",t=>{t.currentTarget instanceof HTMLSelectElement&&(window.location.pathname=t.currentTarget.value)}),window.addEventListener("pageshow",t=>{if(!t.persisted)return;const n=e.querySelector("option[selected]")?.index;n!==e.selectedIndex&&(e.selectedIndex=n??0)}))}}customElements.define("starlight-lang-select",s);</script> </div> </div></header> <nav class="sidebar print:hidden astro-to3xypmc" aria-label="Main"> <starlight-menu-button class="print:hidden astro-l43anhaf"> <button aria-expanded="false" aria-label="Menu" aria-controls="starlight__sidebar" class="sl-flex md:sl-hidden astro-l43anhaf"> <svg aria-hidden="true" class="open-menu astro-l43anhaf astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M3 8h18a1 1 0 1 0 0-2H3a1 1 0 0 0 0 2Zm18 8H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Zm0-5H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Z"/></svg> <svg aria-hidden="true" class="close-menu astro-l43anhaf astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="m13.41 12 6.3-6.29a1.004 1.004 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1.004 1.004 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 0 1.42.998.998 0 0 0 1.42 0l6.29-6.3 6.29 6.3a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.42L13.41 12Z"/></svg> </button> </starlight-menu-button> <script type="module">class s extends HTMLElement{constructor(){super(),this.btn=this.querySelector("button"),this.btn.addEventListener("click",()=>this.toggleExpanded());const t=this.closest("nav");t&&t.addEventListener("keyup",e=>this.closeOnEscape(e))}setExpanded(t){this.setAttribute("aria-expanded",String(t)),document.body.toggleAttribute("data-mobile-menu-expanded",t)}toggleExpanded(){this.setExpanded(this.getAttribute("aria-expanded")!=="true")}closeOnEscape(t){t.code==="Escape"&&(this.setExpanded(!1),this.btn.focus())}}customElements.define("starlight-menu-button",s);</script>  <div id="starlight__sidebar" class="sidebar-pane astro-to3xypmc"> <div class="sidebar-content sl-flex astro-to3xypmc"> <sl-sidebar-state-persist data-hash="1dxffrg" class="astro-znqwvy6e"> <script aria-hidden="true">
 		(() => {
 			try {
 				if (!matchMedia('(min-width: 50em)').matches) return;
@@ -61,7 +61,7 @@
 				);
 			} catch {}
 		})();
-	</script>  <ul class="top-level astro-ux7joveq"> <li class="astro-ux7joveq"> <a href="/overview/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Overview</span>  </a> </li><li class="astro-ux7joveq"> <a href="/getting-started/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Getting Started</span>  </a> </li><li class="astro-ux7joveq"> <a href="/architecture/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Architecture</span>  </a> </li><li class="astro-ux7joveq"> <a href="/commands/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Commands</span>  </a> </li><li class="astro-ux7joveq"> <a href="/format/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">SPEC.json Format</span>  </a> </li><li class="astro-ux7joveq"> <a href="/tags/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Tags</span>  </a> </li><li class="astro-ux7joveq"> <a href="/checks/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Integrity Checks</span>  </a> </li><li class="astro-ux7joveq"> <details open class="astro-ux7joveq"> <summary class="astro-ux7joveq"> <span class="group-label astro-ux7joveq"> <span class="large astro-ux7joveq">Guides</span>  </span> <svg aria-hidden="true" class="caret astro-ux7joveq astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><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> </summary> <sl-sidebar-restore data-index="0"></sl-sidebar-restore> <ul class="astro-ux7joveq"> <li class="astro-ux7joveq"> <a href="/guides/adoption/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Adoption Guide</span>  </a> </li><li class="astro-ux7joveq"> <a href="/guides/platform-setup/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Platform Setup</span>  </a> </li><li class="astro-ux7joveq"> <a href="/guides/single-repo/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Single Repo (Rung 1)</span>  </a> </li> </ul> </details> </li><li class="astro-ux7joveq"> <a href="/agent-reference/" aria-current="page" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Agent Reference</span>  </a> </li> </ul>  <script aria-hidden="true">
+	</script>  <ul class="top-level astro-ux7joveq"> <li class="astro-ux7joveq"> <a href="/overview/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Overview</span>  </a> </li><li class="astro-ux7joveq"> <a href="/getting-started/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Getting Started</span>  </a> </li><li class="astro-ux7joveq"> <a href="/architecture/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Architecture</span>  </a> </li><li class="astro-ux7joveq"> <a href="/platform-mapping/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Platform Mapping</span>  </a> </li><li class="astro-ux7joveq"> <a href="/commands/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Commands</span>  </a> </li><li class="astro-ux7joveq"> <a href="/format/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">SPEC.json Format</span>  </a> </li><li class="astro-ux7joveq"> <a href="/tags/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Tags</span>  </a> </li><li class="astro-ux7joveq"> <a href="/checks/" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Integrity Checks</span>  </a> </li><li class="astro-ux7joveq"> <details open class="astro-ux7joveq"> <summary class="astro-ux7joveq"> <span class="group-label astro-ux7joveq"> <span class="large astro-ux7joveq">Guides</span>  </span> <svg aria-hidden="true" class="caret astro-ux7joveq astro-lm5mbbcm" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><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> </summary> <sl-sidebar-restore data-index="0"></sl-sidebar-restore> <ul class="astro-ux7joveq"> <li class="astro-ux7joveq"> <a href="/guides/adoption/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Adoption Guide</span>  </a> </li><li class="astro-ux7joveq"> <a href="/guides/platform-setup/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Platform Setup</span>  </a> </li><li class="astro-ux7joveq"> <a href="/guides/single-repo/" class="astro-ux7joveq"> <span class="astro-ux7joveq">Single Repo (Rung 1)</span>  </a> </li> </ul> </details> </li><li class="astro-ux7joveq"> <a href="/agent-reference/" aria-current="page" class="large astro-ux7joveq"> <span class="astro-ux7joveq">Agent Reference</span>  </a> </li> </ul>  <script aria-hidden="true">
 		(() => {
 			const scroller = document.getElementById('starlight__sidebar');
 			if (!window._starlightScrollRestore || !scroller) return;
@@ -72,13 +72,14 @@
 	StarlightThemeProvider.updatePickers();
 </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="#mental-model" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Mental model</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#invocation" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Invocation</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#the-agent-loop" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">The agent loop</span> </a> <ul class="isMobile astro-xz67lhkg" style="--depth: 1;"> <li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#route--before-changing-code" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Route — before changing code</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#tag--while-implementing" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Tag — while implementing</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#check--before-finishing" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Check — before finishing</span> </a>  </li> </ul> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#path-rules-for-spec-resolve" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Path rules for spec resolve</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#gotchas" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Gotchas</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="#mental-model" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Mental model</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#invocation" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Invocation</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#the-agent-loop" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">The agent loop</span> </a> <ul class="astro-xz67lhkg" style="--depth: 1;"> <li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#route--before-changing-code" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Route — before changing code</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#tag--while-implementing" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Tag — while implementing</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 1;"> <a href="#check--before-finishing" class="astro-xz67lhkg" style="--depth: 1;"> <span class="astro-xz67lhkg" style="--depth: 1;">Check — before finishing</span> </a>  </li> </ul> </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#path-rules-for-spec-resolve" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Path rules for spec resolve</span> </a>  </li><li class="astro-xz67lhkg" style="--depth: 0;"> <a href="#gotchas" class="astro-xz67lhkg" style="--depth: 0;"> <span class="astro-xz67lhkg" style="--depth: 0;">Gotchas</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">Agent Reference</h1> </div> </div> <div class="content-panel astro-sfndtt72"> <div class="sl-container astro-sfndtt72"> <div class="sl-markdown-content"> <p>Machine-oriented reference for coding agents. For narrative and rationale, see the other docs sections.</p>
 <div class="sl-heading-wrapper level-h2"><h2 id="mental-model">Mental model</h2><a class="sl-anchor-link" href="#mental-model"><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 “Mental model”</span></a></div>
-<ol>
-<li>Canonical truth: <code dir="auto">spec-engine/&#x3C;DOMAIN>/SPEC.json</code> files in git, validated by one shared schema on every surface. Requirement IDs (<code dir="auto">KEY-NNN</code>) are permanent; changes supersede, never overwrite.</li>
-<li>Code binds to requirements with comment tags: <code dir="auto">// @spec KEY-NNN</code> (+ optional level token).</li>
-<li>Tag kind is path-derived: implementation code = implements; test path = verifies.</li>
-<li>The index at <code dir="auto">&#x3C;platformDir>/.spec-engine/index.sqlite</code> is derived and disposable — read commands build it transparently when missing.</li>
-<li>Coverage/drift/propagation are SQL projections over tags — never authored. Drift compares a member’s pin (<code dir="auto">spec-engine@N</code>, one platform-wide scalar) against each referenced requirement’s <code dir="auto">changed_at_version</code>, derived within its domain’s supersede DAG; the platform version is the max domain version, derived too.</li>
-</ol>
+<ul>
+<li>Canonical truth: <code dir="auto">spec-engine/&#x3C;DOMAIN>/SPEC.json</code> in git, one shared schema on every surface. Ids (<code dir="auto">KEY-NNN</code>) are permanent; changes supersede, never overwrite.</li>
+<li>Code binds with <code dir="auto">// @spec KEY-NNN</code>. A test tag may add <code dir="auto">unit</code> | <code dir="auto">integration</code> | <code dir="auto">e2e</code>.</li>
+<li>Tag kind is path-derived: implementation code implements, a test path verifies.</li>
+<li>The index at <code dir="auto">&#x3C;platformDir>/.spec-engine/index.sqlite</code> is derived and disposable.</li>
+<li>Coverage, drift, and propagation are SQL projections over tags. Drift compares a member’s pin (<code dir="auto">spec-engine@N</code>) against each referenced requirement’s <code dir="auto">changed_at_version</code>; the platform version is the max domain version.</li>
+</ul>
+<p>The repo’s <code dir="auto">AGENTS.md</code> is the canonical copy of this page, with every command’s flags and <code dir="auto">--json</code> shape.</p>
 <div class="sl-heading-wrapper level-h2"><h2 id="invocation">Invocation</h2><a class="sl-anchor-link" href="#invocation"><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 “Invocation”</span></a></div>
 <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">bunx</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">@spec-engine/spec-engine</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">&#x3C;command></span><span style="--0:#D6DEEB;--1:#403F53"> [...]   </span><span style="--0:#919F9F;--1:#5F636F"># published npm package (requires Bun)</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">&#x3C;command></span><span style="--0:#D6DEEB;--1:#403F53"> [...]                            </span><span style="--0:#919F9F;--1:#5F636F"># after: bun add -g @spec-engine/spec-engine</span></div></div><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">packages/engine/src/cli.ts</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">&#x3C;command></span><span style="--0:#D6DEEB;--1:#403F53"> [...]  </span><span style="--0:#919F9F;--1:#5F636F"># from a checkout</span></div></div><div class="ec-line"><div class="code"><span style="--0:#82AAFF;--1:#3B61B0">./dist/spec</span><span style="--0:#D6DEEB;--1:#403F53"> </span><span style="--0:#ECC48D;--1:#3B61B0">&#x3C;command></span><span style="--0:#D6DEEB;--1:#403F53"> [...]                     </span><span style="--0:#919F9F;--1:#5F636F"># compiled binary</span></div></div></code></pre><div class="copy"><div aria-live="polite"></div><button title="Copy to clipboard" data-copied="Copied!" data-code="bunx @spec-engine/spec-engine <command> [...]   # published npm package (requires Bun)spec <command> [...]                            # after: bun add -g @spec-engine/spec-enginebun packages/engine/src/cli.ts <command> [...]  # from a checkout./dist/spec <command> [...]                     # compiled binary"><div></div></button></div></figure></div>
 <ul>