@spec-engine/spec-engine 0.2.0 → 0.3.0

package/dist/docs/checks/index.html

@@ -162,7 +162,7 @@
 
 
 
-<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) — loud, never a silent zero</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>error</td><td>An active requirement is implemented but has no verifying test 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">NO_SPEC_CONFIG</code></td><td>warning</td><td>A sibling repo-root under the platform has no <code dir="auto">spec-engine.member.json</code></td></tr><tr><td><code dir="auto">BROKEN_FILE_REF</code></td><td>warning</td><td>An <code dir="auto">@&#x3C;path></code> reference in requirement text does not resolve</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>
+<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) — loud, never a silent zero</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>error</td><td>An active requirement is implemented but has no verifying test 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 sibling repo-root under the platform has no <code dir="auto">spec-engine.member.json</code></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>
 <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>
 
 

package/dist/docs/commands/index.html

@@ -193,7 +193,7 @@
 <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>
 <p><strong>Exit codes:</strong> 0 / 2</p>
 <div class="sl-heading-wrapper level-h3"><h3 id="spec-req-domain-prefix-platformdir"><code dir="auto">spec req &#x3C;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 &#x3C;domain-prefix> [platformDir]”</span></a></div>
-<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">--binds</code> / <code dir="auto">--lives</code>):</strong> appends a born-active entry non-interactively through the validated write seam. Prefix is case-insensitive (<code dir="auto">bil</code> → <code dir="auto">BILLING</code>; ambiguous → exit 2). <code dir="auto">spec req &#x3C;domain></code> alone prints the domain’s charter before authoring.</p>
+<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. Prefix is case-insensitive (<code dir="auto">bil</code> → <code dir="auto">BILLING</code>; ambiguous → exit 2). <code dir="auto">spec req &#x3C;domain></code> alone prints the domain’s charter before authoring.</p>
 <p><strong>Exit codes:</strong> 0 / 2</p>
 <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>
 <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>
@@ -209,7 +209,7 @@
 <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>
 <p><strong>Exit codes:</strong> 0 / 1 / 2</p>
 <div class="sl-heading-wrapper level-h3"><h3 id="spec-supersede-reqid-platformdir"><code dir="auto">spec supersede &#x3C;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 &#x3C;reqId> [platformDir]”</span></a></div>
-<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">--binds</code>/<code dir="auto">--lives</code> default to copies), reindexes, and prints the <strong>retag worklist</strong> — every code site still on the old ID. The target must be Active.</p>
+<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> default to copies), reindexes, and prints the <strong>retag worklist</strong> — every code site still on the old ID. The target must be Active.</p>
 <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>
 <p><code dir="auto">--json</code>: <code dir="auto">{ old_id, new_id, file, spec_version, retag: [...] }</code></p>
 <p><strong>Exit codes:</strong> 0 / 2</p>
@@ -217,7 +217,7 @@
 <p>Cross-domain supersede for taxonomy reorganization: mints the successor as the next id in <code dir="auto">&#x3C;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>
 <p><strong>Exit codes:</strong> 0 / 2</p>
 <div class="sl-heading-wrapper level-h3"><h3 id="spec-amend-reqid-platformdir"><code dir="auto">spec amend &#x3C;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 &#x3C;reqId> [platformDir]”</span></a></div>
-<p>Revise an unshipped requirement’s fields 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">--binds</code>/<code dir="auto">--lives</code>, at least one); untouched fields stay byte-identical. Only Active and Draft entries amend.</p>
+<p>Revise an unshipped requirement’s fields 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>, at least one); untouched fields stay byte-identical. Only Active and Draft entries amend.</p>
 <p><strong>Exit codes:</strong> 0 / 2</p>
 <div class="sl-heading-wrapper level-h3"><h3 id="spec-serve-platformdir---port-n"><code dir="auto">spec serve [platformDir] [--port N]</code></h3><a class="sl-anchor-link" href="#spec-serve-platformdir---port-n"><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 serve [platformDir] [--port N]”</span></a></div>
 <p>Launch the local webapp over the derived index. Binds <code dir="auto">127.0.0.1</code> only. <code dir="auto">--probe</code> boots on an ephemeral port, smoke-tests, and exits.</p>

package/dist/docs/pagefind/pagefind-entry.json

@@ -1 +1 @@
-{"version":"1.5.2","languages":{"en":{"hash":"en_f3d65f37ce","wasm":"en","page_count":11}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","＿"]}
+{"version":"1.5.2","languages":{"en":{"hash":"en_4cf42761c7","wasm":"en","page_count":11}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","＿"]}

package/dist/impl.js

@@ -661,6 +661,23 @@ var init_constants = __esm(() => {
   OUT_HELP = `DB path override (default: <platformDir>/${INDEX_DIR}/${INDEX_DB_FILENAME})`;
 });
 
+// src/parser/requirementLine.ts
+function findRequirementIdLine(rawLines, id, from = 0) {
+  const needle = `"id": "${id}"`;
+  const exact = `${SEAM_INDENT}${needle}`;
+  const start = from > 0 ? from : 0;
+  let loose = -1;
+  for (let i = start;i < rawLines.length; i++) {
+    const line = rawLines[i];
+    if (line === exact || line === `${exact},`)
+      return i;
+    if (loose < 0 && line.includes(needle))
+      loose = i;
+  }
+  return loose;
+}
+var SEAM_INDENT = "      ";
+
 // src/parser/domainJson.ts
 function parseDomainJsonFile(opts) {
   let parsed;
@@ -698,6 +715,7 @@ function parseDomainJson(opts) {
   const updated = data.updated ?? null;
   const rawLines = text.split(`
 `);
+  let lineCursor = 0;
   const working = [];
   const relatesAcc = {
     relations: [],
@@ -718,7 +736,10 @@ function parseDomainJson(opts) {
   };
   for (let idx = 0;idx < data.requirements.length; idx++) {
     const r = data.requirements[idx];
-    const line = deriveRequirementLine(rawLines, r.id, idx);
+    const found = findRequirementIdLine(rawLines, r.id, lineCursor);
+    const line = found >= 0 ? found + 1 : idx + 1;
+    if (found >= 0)
+      lineCursor = found + 1;
     working.push(mapRequirementRow(r, key, sourceFile, spec_version, line));
     flattenRelates(r, sourceFile, line, relatesAcc);
     flattenIssues(r, sourceFile, line, issuesAcc);
@@ -742,11 +763,6 @@ function parseDomainJson(opts) {
     term_citations: termAcc.citations
   };
 }
-function deriveRequirementLine(rawLines, id, idx) {
-  const needle = `"id": "${id}"`;
-  const found = rawLines.findIndex((l) => l.includes(needle));
-  return found >= 0 ? found + 1 : idx + 1;
-}
 function mapRequirementRow(r, key, sourceFile, spec_version, line) {
   const id = r.id;
   const seq = Number(id.split("-")[1]);
@@ -1363,10 +1379,11 @@ class SqliteStorage {
     return row ?? null;
   }
   listDomains() {
-    return [];
+    return this.#db.query(LIST_DOMAINS_SQL).all();
   }
-  getDomain(_key) {
-    return null;
+  getDomain(key) {
+    const row = this.#db.query(GET_DOMAIN_SQL).get({ key });
+    return row ?? null;
   }
   listRequirements(opts) {
     const key = opts?.key;
@@ -1996,7 +2013,7 @@ SELECT
 FROM repos
 WHERE repos.name != 'spec-engine'
 ORDER BY repos.name
-`, FTS_SEARCH_SQL = `SELECT r.id AS req_id, r.key AS key, r.text AS text, r.why AS why, r.source_file AS source_file, r.line AS line, bm25(requirements_fts, 1.0, 0.5) AS rank FROM requirements_fts JOIN requirements r ON r.rowid = requirements_fts.rowid WHERE requirements_fts MATCH $query AND r.status NOT IN ('Superseded', 'Deprecated') ORDER BY rank ASC LIMIT $limit`, RESOLVE_BY_FILES_SQL_PREFIX = "SELECT DISTINCT r.id, r.key, r.seq, r.status, r.superseded_by, r.text, r.why, r.source_file, r.line, r.spec_version, r.changed_at_version, r.superseded_at_version FROM tags t JOIN requirements r ON r.id = t.req_id WHERE t.file IN (", RESOLVE_BY_FILES_SQL_SUFFIX = ") ORDER BY r.key, r.seq", LIST_REPOS_SQL = "SELECT name, path, pinned_spec_version FROM repos ORDER BY name", GET_REPO_SQL = "SELECT name, path, pinned_spec_version FROM repos WHERE name = $name", LIST_TAGS_SQL = `SELECT id, req_id, repo, file, line, kind, level FROM tags
+`, FTS_SEARCH_SQL = `SELECT r.id AS req_id, r.key AS key, r.text AS text, r.why AS why, r.source_file AS source_file, r.line AS line, bm25(requirements_fts, 1.0, 0.5) AS rank FROM requirements_fts JOIN requirements r ON r.rowid = requirements_fts.rowid WHERE requirements_fts MATCH $query AND r.status NOT IN ('Superseded', 'Deprecated') ORDER BY rank ASC LIMIT $limit`, RESOLVE_BY_FILES_SQL_PREFIX = "SELECT DISTINCT r.id, r.key, r.seq, r.status, r.superseded_by, r.text, r.why, r.source_file, r.line, r.spec_version, r.changed_at_version, r.superseded_at_version FROM tags t JOIN requirements r ON r.id = t.req_id WHERE t.file IN (", RESOLVE_BY_FILES_SQL_SUFFIX = ") ORDER BY r.key, r.seq", LIST_REPOS_SQL = "SELECT name, path, pinned_spec_version FROM repos ORDER BY name", GET_REPO_SQL = "SELECT name, path, pinned_spec_version FROM repos WHERE name = $name", LIST_DOMAINS_SQL = "SELECT key, owner, schema, spec_version, source_repo FROM domains ORDER BY key", GET_DOMAIN_SQL = "SELECT key, owner, schema, spec_version, source_repo FROM domains WHERE key = $key", LIST_TAGS_SQL = `SELECT id, req_id, repo, file, line, kind, level FROM tags
   WHERE ($repo IS NULL OR repo = $repo)
     AND ($req_id IS NULL OR req_id = $req_id)
     AND ($file IS NULL OR file = $file)
@@ -3106,49 +3123,6 @@ function matchesSegment(pat, seg) {
   return p === pat.length;
 }
 
-// src/check/format.ts
-function compareRepoNullsLast(a, b) {
-  if (a === b)
-    return 0;
-  if (a === null)
-    return 1;
-  if (b === null)
-    return -1;
-  return a.localeCompare(b);
-}
-function compareDiagnostics(a, b) {
-  const codeCmp = a.code.localeCompare(b.code);
-  if (codeCmp !== 0)
-    return codeCmp;
-  const repoCmp = compareRepoNullsLast(a.repo, b.repo);
-  if (repoCmp !== 0)
-    return repoCmp;
-  const fileCmp = (a.source_file ?? "").localeCompare(b.source_file ?? "");
-  if (fileCmp !== 0)
-    return fileCmp;
-  const lineCmp = (a.line ?? 0) - (b.line ?? 0);
-  if (lineCmp !== 0)
-    return lineCmp;
-  return (a.req_id ?? "").localeCompare(b.req_id ?? "");
-}
-function sortDiagnostics(rows) {
-  return [...rows].sort(compareDiagnostics);
-}
-function renderDiagnostics(rows, mode) {
-  const sorted = sortDiagnostics(rows);
-  if (mode === "json") {
-    return JSON.stringify(sorted);
-  }
-  return sorted.map((d) => {
-    const repo = d.repo ?? "";
-    const file = d.source_file ?? "";
-    const line = d.line ?? "";
-    const reqId = d.req_id ?? "";
-    return `${d.code}	${repo}	${file}:${line}	${reqId}	${d.detail}`;
-  }).join(`
-`);
-}
-
 // src/authoring/domains.ts
 import { existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
 import { join as join8 } from "path";
@@ -3220,21 +3194,150 @@ var init_domains = __esm(() => {
   init_src();
 });
 
-// src/check/grammar.ts
+// src/authoring/filerefs.ts
+import { existsSync as existsSync6 } from "fs";
+import { resolve as resolve7 } from "path";
+function extractRefsFromText(s) {
+  const out = [];
+  for (const m of s.matchAll(FILE_REF_RE)) {
+    const candidate = m[1].replace(/\.+$/, "");
+    if (candidate.includes("/"))
+      out.push(candidate);
+  }
+  return out;
+}
+function resolveFileRef(platformDir, ref) {
+  const root = resolve7(platformDir);
+  const abs = resolve7(root, ref);
+  if (!(abs === root || abs.startsWith(`${root}/`)))
+    return false;
+  return existsSync6(abs);
+}
+var FILE_REF_RE;
+var init_filerefs = __esm(() => {
+  FILE_REF_RE = /(?<![^\s])@([A-Za-z0-9_][A-Za-z0-9_\-./]*)/g;
+});
+
+// src/check/filerefs.ts
 import { join as join9 } from "path";
-function lineOf(rawText, id) {
-  const lines = rawText.split(`
+async function readDomain(platformDir, key) {
+  try {
+    const raw = await Bun.file(join9(platformDir, "spec-engine", key, "SPEC.json")).text();
+    const doc = JSON.parse(raw);
+    return {
+      raw,
+      requirements: Array.isArray(doc.requirements) ? doc.requirements : []
+    };
+  } catch {
+    return null;
+  }
+}
+function rowsForRequirement(platformDir, key, reqId, livesIn, line) {
+  if (!Array.isArray(livesIn))
+    return [];
+  const rows = [];
+  for (const entry of livesIn) {
+    if (typeof entry !== "string")
+      continue;
+    const ref = entry.startsWith("@") ? entry.slice(1) : entry;
+    if (ref.length === 0 || resolveFileRef(platformDir, ref))
+      continue;
+    rows.push({
+      code: DiagnosticCode.BROKEN_FILE_REF,
+      severity: "error",
+      repo: null,
+      source_file: `spec-engine/${key}/SPEC.json`,
+      line,
+      req_id: reqId,
+      detail: `livesIn entry ${entry} does not resolve to a file under the platform root`
+    });
+  }
+  return rows;
+}
+function rowsForDomain(platformDir, key, domain2) {
+  const rows = [];
+  const rawLines = domain2.raw.split(`
 `);
-  const needle = `"id": "${id}"`;
-  for (let i = 0;i < lines.length; i++) {
-    if (lines[i].includes(needle))
-      return i + 1;
+  let lineCursor = 0;
+  for (const req of domain2.requirements) {
+    if (typeof req?.id !== "string")
+      continue;
+    const found = findRequirementIdLine(rawLines, req.id, lineCursor);
+    if (found >= 0)
+      lineCursor = found + 1;
+    const status = typeof req.status === "string" ? req.status.toLowerCase() : "";
+    if (!CHECKED_STATUSES.has(status))
+      continue;
+    rows.push(...rowsForRequirement(platformDir, key, req.id, req.livesIn, found >= 0 ? found + 1 : 0));
+  }
+  return rows;
+}
+async function brokenFileRefDiagnostics(platformDir) {
+  const rows = [];
+  for (const key of listDomainKeys(platformDir)) {
+    const domain2 = await readDomain(platformDir, key);
+    if (domain2 !== null)
+      rows.push(...rowsForDomain(platformDir, key, domain2));
+  }
+  rows.sort((a, b) => (a.source_file ?? "").localeCompare(b.source_file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.req_id ?? "").localeCompare(b.req_id ?? "") || a.detail.localeCompare(b.detail));
+  return rows;
+}
+var CHECKED_STATUSES;
+var init_filerefs2 = __esm(() => {
+  init_src();
+  init_domains();
+  init_filerefs();
+  CHECKED_STATUSES = new Set(["active", "draft"]);
+});
+
+// src/check/format.ts
+function compareRepoNullsLast(a, b) {
+  if (a === b)
+    return 0;
+  if (a === null)
+    return 1;
+  if (b === null)
+    return -1;
+  return a.localeCompare(b);
+}
+function compareDiagnostics(a, b) {
+  const codeCmp = a.code.localeCompare(b.code);
+  if (codeCmp !== 0)
+    return codeCmp;
+  const repoCmp = compareRepoNullsLast(a.repo, b.repo);
+  if (repoCmp !== 0)
+    return repoCmp;
+  const fileCmp = (a.source_file ?? "").localeCompare(b.source_file ?? "");
+  if (fileCmp !== 0)
+    return fileCmp;
+  const lineCmp = (a.line ?? 0) - (b.line ?? 0);
+  if (lineCmp !== 0)
+    return lineCmp;
+  return (a.req_id ?? "").localeCompare(b.req_id ?? "");
+}
+function sortDiagnostics(rows) {
+  return [...rows].sort(compareDiagnostics);
+}
+function renderDiagnostics(rows, mode) {
+  const sorted = sortDiagnostics(rows);
+  if (mode === "json") {
+    return JSON.stringify(sorted);
   }
-  return 0;
+  return sorted.map((d) => {
+    const repo = d.repo ?? "";
+    const file = d.source_file ?? "";
+    const line = d.line ?? "";
+    const reqId = d.req_id ?? "";
+    return `${d.code}	${repo}	${file}:${line}	${reqId}	${d.detail}`;
+  }).join(`
+`);
 }
+
+// src/check/grammar.ts
+import { join as join10 } from "path";
 async function readDeclaredDomain(platformDir, key) {
   try {
-    const raw = await Bun.file(join9(platformDir, "spec-engine", key, "SPEC.json")).text();
+    const raw = await Bun.file(join10(platformDir, "spec-engine", key, "SPEC.json")).text();
     const doc = JSON.parse(raw);
     if (doc.grammar !== "ears")
       return null;
@@ -3247,13 +3350,21 @@ async function readDeclaredDomain(platformDir, key) {
     return null;
   }
 }
-function rowsForDomain(key, domain2) {
+function rowsForDomain2(key, domain2) {
   const rows = [];
+  const rawLines = domain2.raw.split(`
+`);
+  let lineCursor = 0;
   for (const req of domain2.requirements) {
-    if (typeof req?.id !== "string" || typeof req.statement !== "string")
+    if (typeof req?.id !== "string")
+      continue;
+    const found = findRequirementIdLine(rawLines, req.id, lineCursor);
+    if (found >= 0)
+      lineCursor = found + 1;
+    if (typeof req.statement !== "string")
       continue;
     const status = typeof req.status === "string" ? req.status.toLowerCase() : "";
-    if (!CHECKED_STATUSES.has(status))
+    if (!CHECKED_STATUSES2.has(status))
       continue;
     const result = parseEarsStatement(req.statement);
     if (result.ok)
@@ -3263,7 +3374,7 @@ function rowsForDomain(key, domain2) {
       severity: domain2.severity,
       repo: null,
       source_file: `spec-engine/${key}/SPEC.json`,
-      line: lineOf(domain2.raw, req.id),
+      line: found >= 0 ? found + 1 : 0,
       req_id: req.id,
       detail: `${result.problem}. Expected one of:
   ${result.expected}`
@@ -3278,16 +3389,16 @@ async function statementGrammarDiagnostics(platformDir) {
       continue;
     const domain2 = await readDeclaredDomain(platformDir, key);
     if (domain2 !== null)
-      rows.push(...rowsForDomain(key, domain2));
+      rows.push(...rowsForDomain2(key, domain2));
   }
   rows.sort((a, b) => (a.source_file ?? "").localeCompare(b.source_file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.req_id ?? "").localeCompare(b.req_id ?? ""));
   return rows;
 }
-var CHECKED_STATUSES;
+var CHECKED_STATUSES2;
 var init_grammar = __esm(() => {
   init_src();
   init_domains();
-  CHECKED_STATUSES = new Set(["active", "draft"]);
+  CHECKED_STATUSES2 = new Set(["active", "draft"]);
 });
 
 // src/check/proven.ts
@@ -3536,6 +3647,72 @@ var init_statusflip = __esm(() => {
   TERMINAL_STATUSES = new Set(["superseded", "deprecated", "retired"]);
 });
 
+// src/check/supersedes.ts
+import { join as join11 } from "path";
+async function entriesForDomain(platformDir, key) {
+  let raw;
+  let reqs;
+  try {
+    raw = await Bun.file(join11(platformDir, "spec-engine", key, "SPEC.json")).text();
+    const doc = JSON.parse(raw);
+    reqs = Array.isArray(doc.requirements) ? doc.requirements : [];
+  } catch {
+    return [];
+  }
+  const out = [];
+  const rawLines = raw.split(`
+`);
+  let lineCursor = 0;
+  for (const r of reqs) {
+    if (typeof r?.id !== "string")
+      continue;
+    const found = findRequirementIdLine(rawLines, r.id, lineCursor);
+    if (found >= 0)
+      lineCursor = found + 1;
+    out.push({
+      id: r.id,
+      supersedes: typeof r.supersedes === "string" ? r.supersedes : null,
+      line: found >= 0 ? found + 1 : 0,
+      sourceFile: `spec-engine/${key}/SPEC.json`
+    });
+  }
+  return out;
+}
+async function collectEntries(platformDir) {
+  const out = [];
+  for (const key of listDomainKeys(platformDir)) {
+    out.push(...await entriesForDomain(platformDir, key));
+  }
+  return out;
+}
+async function supersedesPointerDiagnostics(platformDir) {
+  const entries = await collectEntries(platformDir);
+  const ids = new Set(entries.map((e) => e.id));
+  const rows = [];
+  for (const e of entries) {
+    if (e.supersedes === null)
+      continue;
+    const detail = e.supersedes === e.id ? `${e.id} declares supersedes on itself` : ids.has(e.supersedes) ? null : `${e.id} supersedes ${e.supersedes} which does not exist`;
+    if (detail === null)
+      continue;
+    rows.push({
+      code: DiagnosticCode.BROKEN_SUPERSEDE,
+      severity: "error",
+      repo: null,
+      source_file: e.sourceFile,
+      line: e.line,
+      req_id: e.id,
+      detail
+    });
+  }
+  rows.sort((a, b) => (a.source_file ?? "").localeCompare(b.source_file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.req_id ?? "").localeCompare(b.req_id ?? ""));
+  return rows;
+}
+var init_supersedes = __esm(() => {
+  init_src();
+  init_domains();
+});
+
 // src/check/unsourced.ts
 function unsourcedChanges(requirements, provenance) {
   const sourced = new Set;
@@ -3841,8 +4018,8 @@ __export(exports_glossary, {
   glossaryCommand: () => glossaryCommand,
   generateGlossary: () => generateGlossary
 });
-import { existsSync as existsSync6, readFileSync } from "fs";
-import { join as join10, resolve as resolve7 } from "path";
+import { existsSync as existsSync7, readFileSync } from "fs";
+import { join as join12, resolve as resolve8 } from "path";
 import { defineCommand as defineCommand3 } from "citty";
 function parseGlossary(md) {
   const terms = [];
@@ -3894,7 +4071,7 @@ function generateGlossary(terms) {
 `;
 }
 function resolvePlatform(platformDirRaw) {
-  const platformDir = resolve7(platformDirRaw ?? process.cwd());
+  const platformDir = resolve8(platformDirRaw ?? process.cwd());
   try {
     assertSpecPlatform(platformDir);
   } catch (e) {
@@ -3903,8 +4080,8 @@ function resolvePlatform(platformDirRaw) {
   return platformDir;
 }
 function readStoreTerms(platformDir) {
-  const specPath = join10(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
-  if (!existsSync6(specPath))
+  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  if (!existsSync7(specPath))
     return [];
   const domain2 = JSON.parse(readFileSync(specPath, "utf8"));
   const reqs = Array.isArray(domain2.requirements) ? domain2.requirements : [];
@@ -3915,12 +4092,12 @@ function readStoreTerms(platformDir) {
   }));
 }
 function glossaryPath(platformDir) {
-  return join10(platformDir, "GLOSSARY.md");
+  return join12(platformDir, "GLOSSARY.md");
 }
 async function migrateGlossary(platformDir, json) {
   const relFile = `spec-engine/${TERM_KEY}/SPEC.json`;
-  const specPath = join10(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
-  if (!existsSync6(specPath)) {
+  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  if (!existsSync7(specPath)) {
     console.error(`spec glossary: no TERM domain (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
   }
@@ -3935,7 +4112,7 @@ async function migrateGlossary(platformDir, json) {
     return;
   }
   const gPath = glossaryPath(platformDir);
-  if (!existsSync6(gPath)) {
+  if (!existsSync7(gPath)) {
     console.error(`spec glossary: no GLOSSARY.md to migrate (expected ${gPath})`);
     process.exit(EXIT.USAGE);
   }
@@ -3982,7 +4159,7 @@ function glossaryDriftDiagnostic(platformDir) {
   if (terms.length === 0)
     return null;
   const gPath = glossaryPath(platformDir);
-  if (!existsSync6(gPath))
+  if (!existsSync7(gPath))
     return null;
   const generated = generateGlossary(terms);
   const committed = readFileSync(gPath, "utf8");
@@ -4001,7 +4178,7 @@ function glossaryDriftDiagnostic(platformDir) {
 function checkGlossary(platformDir, json) {
   const generated = generateGlossary(readStoreTerms(platformDir));
   const gPath = glossaryPath(platformDir);
-  const committed = existsSync6(gPath) ? readFileSync(gPath, "utf8") : "";
+  const committed = existsSync7(gPath) ? readFileSync(gPath, "utf8") : "";
   if (generated === committed) {
     if (json)
       console.log(JSON.stringify({ ok: true }));
@@ -4063,12 +4240,12 @@ var exports_check = {};
 __export(exports_check, {
   checkCommand: () => checkCommand
 });
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname7, join as join11, resolve as resolve8 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname7, join as join13, resolve as resolve9 } from "path";
 import { defineCommand as defineCommand4 } from "citty";
 function readCodeownersText(platformDir) {
-  const path = join11(platformDir, ".github", "CODEOWNERS");
-  if (!existsSync7(path))
+  const path = join13(platformDir, ".github", "CODEOWNERS");
+  if (!existsSync8(path))
     return null;
   return readFileSync2(path, "utf-8");
 }
@@ -4107,7 +4284,7 @@ async function ingestResults(storage2, platformDir, resultsArg, jsonMode, diagno
     }
     return { resultsParsed: undefined, verifyingTags: undefined };
   }
-  const resultsPath = resolve8(platformDir, resultsArg);
+  const resultsPath = resolve9(platformDir, resultsArg);
   if (!isContainedPath(resultsPath, platformDir)) {
     console.error(`spec check: --results path must be inside platformDir (resolved to ${resultsPath})`);
     try {
@@ -4127,7 +4304,7 @@ async function collectChangeReqs(canonicalDir) {
   const relPathById = new Map;
   for (const rel of await findDomainJsonFiles(canonicalDir)) {
     const platformRel = `spec-engine/${rel}`;
-    const text = await Bun.file(join11(canonicalDir, rel)).text();
+    const text = await Bun.file(join13(canonicalDir, rel)).text();
     const parsed = domainReqsFromText(text, platformRel);
     for (const r of parsed.reqs) {
       reqs.push(r);
@@ -4167,7 +4344,7 @@ async function runGovernanceGate(storage2, platformDir, args, diagnostics2, resu
     } catch {}
     process.exit(EXIT.USAGE);
   }
-  const canonicalDir = join11(platformDir, "spec-engine");
+  const canonicalDir = join13(platformDir, "spec-engine");
   const change = await collectChangeReqs(canonicalDir);
   const base = collectBaseReqs(platformDir, ref, diagnostics2);
   diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
@@ -4193,11 +4370,13 @@ function exitAfterCrash(e, storage2) {
 var checkCommand;
 var init_check = __esm(() => {
   init_src();
+  init_filerefs2();
   init_grammar();
   init_propagation_teeth();
   init_proven();
   init_removed();
   init_statusflip();
+  init_supersedes();
   init_unsourced();
   init_constants();
   init_discover();
@@ -4257,7 +4436,7 @@ var init_check = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve8(args.platformDir ?? process.cwd());
+      const platformDir = resolve9(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4287,6 +4466,8 @@ var init_check = __esm(() => {
           diagnostics2.push(...unsourcedChanges(superseded, provenance));
         }
         diagnostics2.push(...await statementGrammarDiagnostics(platformDir));
+        diagnostics2.push(...await brokenFileRefDiagnostics(platformDir));
+        diagnostics2.push(...await supersedesPointerDiagnostics(platformDir));
         const glossaryDrift = glossaryDriftDiagnostic(platformDir);
         if (glossaryDrift !== null)
           diagnostics2.push(glossaryDrift);
@@ -4297,7 +4478,7 @@ var init_check = __esm(() => {
           requireOwnerApproval: args.requireOwnerApproval
         }, diagnostics2, results);
         if (!args.base && gitRefResolves(platformDir, "HEAD")) {
-          const change = await collectChangeReqs(join11(platformDir, "spec-engine"));
+          const change = await collectChangeReqs(join13(platformDir, "spec-engine"));
           const baseParseSink = [];
           const base = collectBaseReqs(platformDir, "HEAD", baseParseSink);
           diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
@@ -4324,8 +4505,8 @@ __export(exports_domain, {
   domainListCommand: () => domainListCommand,
   domainCommand: () => domainCommand
 });
-import { existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
-import { dirname as dirname8, join as join12, resolve as resolve9 } from "path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname8, join as join14, resolve as resolve10 } from "path";
 import { defineCommand as defineCommand5 } from "citty";
 var domainNewCommand, domainListCommand, domainCommand;
 var init_domain2 = __esm(() => {
@@ -4353,7 +4534,7 @@ var init_domain2 = __esm(() => {
     },
     async run({ args }) {
       const raw = args.name;
-      const platformDir = resolve9(args.platformDir ?? process.cwd());
+      const platformDir = resolve10(args.platformDir ?? process.cwd());
       const key = normalizeDomainKey(raw);
       if (key !== raw) {
         console.log(`spec domain: normalized "${raw}" \u2192 ${key}`);
@@ -4363,21 +4544,21 @@ var init_domain2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const dest = join12(platformDir, "spec-engine", key, "SPEC.json");
-      const resolvedDest = resolve9(dest);
-      const resolvedRoot = resolve9(platformDir);
+      const dest = join14(platformDir, "spec-engine", key, "SPEC.json");
+      const resolvedDest = resolve10(dest);
+      const resolvedRoot = resolve10(platformDir);
       if (!(resolvedDest === resolvedRoot || resolvedDest.startsWith(`${resolvedRoot}/`))) {
         console.error(`spec domain new: refusing to write outside platformDir (${resolvedDest})`);
         process.exit(EXIT.USAGE);
         return;
       }
-      if (existsSync8(dest)) {
+      if (existsSync9(dest)) {
         console.error(`refusing to overwrite ${dest}`);
         process.exit(EXIT.USAGE);
         return;
       }
-      const mdSibling = join12(dirname8(dest), "SPEC.md");
-      if (existsSync8(mdSibling)) {
+      const mdSibling = join14(dirname8(dest), "SPEC.md");
+      if (existsSync9(mdSibling)) {
         console.error(`refusing to create ${dest}: domain ${key} already exists as spec-engine/${key}/SPEC.md ` + "\u2014 migrate the SPEC.md first (a fresh empty SPEC.json would shadow it on the next index)");
         process.exit(EXIT.USAGE);
         return;
@@ -4414,7 +4595,7 @@ var init_domain2 = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve9(args.platformDir ?? process.cwd());
+      const platformDir = resolve10(args.platformDir ?? process.cwd());
       try {
         assertSpecPlatform(platformDir);
       } catch (e) {
@@ -4508,7 +4689,7 @@ var exports_map = {};
 __export(exports_map, {
   mapCommand: () => mapCommand
 });
-import { resolve as resolve10 } from "path";
+import { resolve as resolve11 } from "path";
 import { defineCommand as defineCommand6 } from "citty";
 var mapCommand;
 var init_map = __esm(() => {
@@ -4545,7 +4726,7 @@ var init_map = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve10(args.platformDir ?? process.cwd());
+      const platformDir = resolve11(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4595,7 +4776,7 @@ var exports_propagation = {};
 __export(exports_propagation, {
   propagationCommand: () => propagationCommand
 });
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 import { defineCommand as defineCommand7 } from "citty";
 var propagationCommand;
 var init_propagation2 = __esm(() => {
@@ -4643,7 +4824,7 @@ var init_propagation2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve11(args.platformDir ?? process.cwd());
+      const platformDir = resolve12(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4717,7 +4898,7 @@ var exports_query = {};
 __export(exports_query, {
   queryCommand: () => queryCommand
 });
-import { resolve as resolve12 } from "path";
+import { resolve as resolve13 } from "path";
 import { defineCommand as defineCommand8 } from "citty";
 var queryCommand;
 var init_query = __esm(() => {
@@ -4783,7 +4964,7 @@ var init_query = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve12(args.platformDir ?? process.cwd());
+      const platformDir = resolve13(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4872,7 +5053,7 @@ var exports_relations = {};
 __export(exports_relations, {
   relationsCommand: () => relationsCommand
 });
-import { resolve as resolve13 } from "path";
+import { resolve as resolve14 } from "path";
 import { defineCommand as defineCommand9 } from "citty";
 function formatNoRelations(platformDir) {
   return [
@@ -4915,7 +5096,7 @@ var init_relations = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve13(args.platformDir ?? process.cwd());
+      const platformDir = resolve14(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -5051,7 +5232,7 @@ var init_adapter = () => {};
 
 // ../tracker/src/cache.ts
 import { mkdirSync as mkdirSync6 } from "fs";
-import { dirname as dirname9, join as join13 } from "path";
+import { dirname as dirname9, join as join15 } from "path";
 function isFresh(entry, now, ttlMs = CACHE_TTL_MS) {
   const t = Date.parse(entry.fetched_at);
   if (Number.isNaN(t))
@@ -5065,7 +5246,7 @@ function isValidEntry(e) {
   return typeof r.title === "string" && typeof r.status === "string" && typeof r.url === "string" && typeof r.fetched_at === "string";
 }
 function sidecarPath(platformDir) {
-  return join13(platformDir, ".spec-engine", SIDECAR_FILE);
+  return join15(platformDir, ".spec-engine", SIDECAR_FILE);
 }
 async function readCache(platformDir) {
   try {
@@ -5253,7 +5434,7 @@ __export(exports_provenance, {
   provenanceCommand: () => provenanceCommand
 });
 import { statSync as statSync5 } from "fs";
-import { resolve as resolve14 } from "path";
+import { resolve as resolve15 } from "path";
 import { defineCommand as defineCommand10 } from "citty";
 function formatNoProvenance(platformDir) {
   return [
@@ -5314,7 +5495,7 @@ var init_provenance = __esm(() => {
       if (issueId && platformArg === undefined) {
         let isDir = false;
         try {
-          isDir = statSync5(resolve14(issueId)).isDirectory();
+          isDir = statSync5(resolve15(issueId)).isDirectory();
         } catch {
           isDir = false;
         }
@@ -5323,7 +5504,7 @@ var init_provenance = __esm(() => {
           issueId = "";
         }
       }
-      const platformDir = resolve14(platformArg ?? process.cwd());
+      const platformDir = resolve15(platformArg ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -5348,35 +5529,11 @@ var init_provenance = __esm(() => {
   });
 });
 
-// src/authoring/filerefs.ts
-import { existsSync as existsSync9 } from "fs";
-import { resolve as resolve15 } from "path";
-function extractRefsFromText(s) {
-  const out = [];
-  for (const m of s.matchAll(FILE_REF_RE)) {
-    const candidate = m[1].replace(/\.+$/, "");
-    if (candidate.includes("/"))
-      out.push(candidate);
-  }
-  return out;
-}
-function resolveFileRef(platformDir, ref) {
-  const root = resolve15(platformDir);
-  const abs = resolve15(root, ref);
-  if (!(abs === root || abs.startsWith(`${root}/`)))
-    return false;
-  return existsSync9(abs);
-}
-var FILE_REF_RE;
-var init_filerefs = __esm(() => {
-  FILE_REF_RE = /(?<![^\s])@([A-Za-z0-9_][A-Za-z0-9_\-./]*)/g;
-});
-
 // src/authoring/grammar.ts
-import { join as join14 } from "path";
+import { join as join16 } from "path";
 async function grammarConfig(platformDir, key) {
   try {
-    const doc = JSON.parse(await Bun.file(join14(platformDir, "spec-engine", key, "SPEC.json")).text());
+    const doc = JSON.parse(await Bun.file(join16(platformDir, "spec-engine", key, "SPEC.json")).text());
     return {
       grammar: doc.grammar === "ears" ? "ears" : "freeform",
       severity: doc.grammarSeverity === "error" ? "error" : "warning"
@@ -5419,7 +5576,7 @@ __export(exports_req, {
   appendEntry: () => appendEntry
 });
 import { existsSync as existsSync10 } from "fs";
-import { join as join15, resolve as resolve16 } from "path";
+import { join as join17, resolve as resolve16 } from "path";
 import { createInterface as createInterface2 } from "readline";
 import { defineCommand as defineCommand11 } from "citty";
 function resolveDomainKey(input, platformDir) {
@@ -5448,13 +5605,11 @@ async function authorFromFieldFlags(platformDir, key, nextId, textFlag, opts) {
   }
   await printResolvedCharter(platformDir, key);
   const why = (opts.why ?? "").trim();
-  const binds = (opts.binds ?? "").trim();
   const lives = (opts.lives ?? "").trim();
-  warnUnresolvableRefs(platformDir, [requirement, why, binds, lives]);
+  warnUnresolvableRefs(platformDir, [requirement, why, lives]);
   const relFile = await appendEntry(platformDir, key, nextId, {
     requirement,
     why,
-    binds,
     lives,
     issue: (opts.issue ?? "").trim() || undefined
   });
@@ -5484,7 +5639,7 @@ function warnUnresolvableRefs(platformDir, fieldValues) {
 }
 async function appendEntry(platformDir, key, id, fields) {
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join15(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join17(platformDir, "spec-engine", key, "SPEC.json");
   await enforceStatementGrammar(platformDir, key, fields.requirement, "spec req");
   const domain2 = existsSync10(specPath) ? JSON.parse(await Bun.file(specPath).text()) : null;
   if (domain2 === null) {
@@ -5559,10 +5714,6 @@ var init_req = __esm(() => {
         type: "string",
         description: "Why it matters field (only with --text)"
       },
-      binds: {
-        type: "string",
-        description: "Binds field (only with --text)"
-      },
       lives: {
         type: "string",
         description: "Lives in field (only with --text)"
@@ -5583,16 +5734,15 @@ var init_req = __esm(() => {
       const key = resolveDomainKey(input, platformDir);
       const nextId = await nextRequirementId(platformDir, key);
       const textFlag = args.text;
-      const hasFieldFlags = typeof args.why === "string" || typeof args.binds === "string" || typeof args.lives === "string" || typeof args.issue === "string";
+      const hasFieldFlags = typeof args.why === "string" || typeof args.lives === "string" || typeof args.issue === "string";
       if (textFlag === undefined && hasFieldFlags) {
-        console.error("spec req: --why/--binds/--lives/--issue require --text (the Requirement field is mandatory)");
+        console.error("spec req: --why/--lives/--issue require --text (the Requirement field is mandatory)");
         process.exit(EXIT.USAGE);
         return;
       }
       if (textFlag !== undefined) {
         await authorFromFieldFlags(platformDir, key, nextId, textFlag, {
           why: args.why,
-          binds: args.binds,
           lives: args.lives,
           issue: args.issue,
           json: Boolean(args.json)
@@ -5616,13 +5766,11 @@ var init_req = __esm(() => {
         return;
       }
       const why = (await askLine("Why it matters: ")).trim();
-      const binds = (await askLine("Binds: ")).trim();
       const lives = (await askLine("Lives in: ")).trim();
-      warnUnresolvableRefs(platformDir, [requirement, why, binds, lives]);
+      warnUnresolvableRefs(platformDir, [requirement, why, lives]);
       const relFile = await appendEntry(platformDir, key, nextId, {
         requirement,
         why,
-        binds,
         lives
       });
       console.log(`appended ${nextId} to ${relFile}`);
@@ -5644,7 +5792,7 @@ __export(exports_term, {
   termCommand: () => termCommand
 });
 import { existsSync as existsSync11 } from "fs";
-import { join as join16, resolve as resolve17 } from "path";
+import { join as join18, resolve as resolve17 } from "path";
 import { defineCommand as defineCommand12 } from "citty";
 function parseAliases(raw) {
   if (typeof raw !== "string" || raw.trim() === "")
@@ -5661,7 +5809,7 @@ function resolvePlatform2(platformDirRaw) {
   return platformDir;
 }
 async function readTermEnvelope(platformDir, cmd) {
-  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  const specPath = join18(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   if (!existsSync11(specPath)) {
     console.error(`spec ${cmd}: no TERM domain (expected spec-engine/TERM/SPEC.json under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -5670,7 +5818,7 @@ async function readTermEnvelope(platformDir, cmd) {
 }
 async function appendTermEntry(platformDir, id, fields) {
   const relFile = `spec-engine/${TERM_KEY2}/SPEC.json`;
-  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  const specPath = join18(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   const domain2 = await readTermEnvelope(platformDir, "term");
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const entry = {
@@ -5734,7 +5882,7 @@ async function authorOrQuery(opts) {
 }
 async function listTerms(platformDirRaw, json) {
   const platformDir = resolvePlatform2(platformDirRaw);
-  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  const specPath = join18(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   const domain2 = existsSync11(specPath) ? JSON.parse(await Bun.file(specPath).text()) : { requirements: [] };
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const rows = requirements.map((r) => ({
@@ -5766,7 +5914,7 @@ async function resolveReviseTarget(id, platformDirRaw, defRaw) {
     process.exit(EXIT.USAGE);
   }
   const relFile = `spec-engine/${TERM_KEY2}/SPEC.json`;
-  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  const specPath = join18(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   const domain2 = await readTermEnvelope(platformDir, "term revise");
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const req = requirements.find((r) => r?.id === id);
@@ -5842,7 +5990,7 @@ async function resolveConfirmTarget(platformDir, termId) {
 async function locateCitation(platformDir, reqId, termId) {
   const citKey = reqId.slice(0, reqId.indexOf("-"));
   const relFile = `spec-engine/${citKey}/SPEC.json`;
-  const specPath = join16(platformDir, "spec-engine", citKey, "SPEC.json");
+  const specPath = join18(platformDir, "spec-engine", citKey, "SPEC.json");
   if (!existsSync11(specPath)) {
     console.error(`spec term confirm: no domain ${citKey} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -6123,7 +6271,7 @@ __export(exports_supersede, {
   supersedeCommand: () => supersedeCommand
 });
 import { existsSync as existsSync12 } from "fs";
-import { join as join17, resolve as resolve18 } from "path";
+import { join as join19, resolve as resolve18 } from "path";
 import { defineCommand as defineCommand13 } from "citty";
 async function resolveSupersedeTarget(id, platformDir) {
   if (!ID_RE.test(id)) {
@@ -6137,7 +6285,7 @@ async function resolveSupersedeTarget(id, platformDir) {
   }
   const key = id.slice(0, id.indexOf("-"));
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join17(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join19(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync12(specPath)) {
     console.error(`spec supersede: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -6186,8 +6334,7 @@ function resolveSuccessorFields(args, req) {
   const predLives = Array.isArray(req.livesIn) && req.livesIn.length > 0 ? String(req.livesIn[0]) : "";
   const why = (args.why ?? predWhy).trim();
   const lives = (args.lives ?? predLives).trim();
-  const binds = (args.binds ?? "").trim();
-  return { why, lives, binds };
+  return { why, lives };
 }
 function resolveSuccessorTermFields(args, req) {
   const predTerm = typeof req.term === "string" ? req.term : undefined;
@@ -6217,8 +6364,7 @@ function applySupersedeEdit(target, newId, requirement, why, lives, noBump, term
     supersededBy: null,
     relates: [],
     livesIn: lives === "" ? [] : [lives],
-    issues: issue ? [{ role: "created", id: issue }] : [],
-    changedAtVersion: 1
+    issues: issue ? [{ role: "created", id: issue }] : []
   };
   if (termFields !== null) {
     if (termFields.term !== undefined)
@@ -6227,20 +6373,25 @@ function applySupersedeEdit(target, newId, requirement, why, lives, noBump, term
   }
   requirements.push(successor);
   domain2.requirements = requirements;
-  let reportedVersion;
-  if (domain2.key === "TERM") {
-    const currentVersion = typeof domain2.specVersion === "number" ? domain2.specVersion : 1;
-    reportedVersion = noBump ? null : currentVersion + 1;
-    if (reportedVersion !== null)
-      domain2.specVersion = reportedVersion;
-    req.supersededAtVersion = reportedVersion ?? currentVersion;
-  } else {
-    reportedVersion = deriveDomainVersion(requirements);
-    req.supersededAtVersion = reportedVersion;
-  }
+  const reportedVersion = applyVersionStage(target, successor, noBump);
   domain2.updated = localToday();
   return reportedVersion;
 }
+function applyVersionStage(target, successor, noBump) {
+  const { domain: domain2, requirements, req } = target;
+  if (domain2.key !== "TERM") {
+    const derived = deriveDomainVersion(requirements);
+    req.supersededAtVersion = derived;
+    return derived;
+  }
+  const currentVersion = typeof domain2.specVersion === "number" ? domain2.specVersion : 1;
+  const reported = noBump ? null : currentVersion + 1;
+  if (reported !== null)
+    domain2.specVersion = reported;
+  req.supersededAtVersion = reported ?? currentVersion;
+  successor.changedAtVersion = reported ?? currentVersion;
+  return reported;
+}
 async function reindexAndCollectRetag(platformDir, id) {
   const tags = await reindexAndListTags(platformDir, id);
   return tags.map(({ req_id, repo, file, line, kind, level }) => ({
@@ -6287,10 +6438,6 @@ var init_supersede = __esm(() => {
         type: "string",
         description: "Successor's Why it matters (default: copied from the old entry)"
       },
-      binds: {
-        type: "string",
-        description: "Binds value (validated for @-refs; not persisted in JSON \u2014 STOR-01)"
-      },
       lives: {
         type: "string",
         description: "Successor's Lives in (default: copied from the old entry)"
@@ -6322,8 +6469,8 @@ var init_supersede = __esm(() => {
       const target = await resolveSupersedeTarget(id, platformDir);
       const requirement = await resolveSuccessorText(args, id);
       await enforceStatementGrammar(platformDir, target.key, requirement, "spec supersede");
-      const { why, lives, binds } = resolveSuccessorFields(args, target.req);
-      warnUnresolvableRefs(platformDir, [requirement, why, binds, lives]);
+      const { why, lives } = resolveSuccessorFields(args, target.req);
+      warnUnresolvableRefs(platformDir, [requirement, why, lives]);
       const newId = await nextRequirementId(platformDir, target.key);
       const termFields = target.key === "TERM" ? resolveSuccessorTermFields(args, target.req) : null;
       const newVersion = applySupersedeEdit(target, newId, requirement, why, lives, Boolean(args.noBump), termFields, (args.issue ?? "").trim() || undefined);
@@ -6366,12 +6513,12 @@ __export(exports_deprecate, {
   deprecateCommand: () => deprecateCommand
 });
 import { existsSync as existsSync13 } from "fs";
-import { join as join18, resolve as resolve19 } from "path";
+import { join as join20, resolve as resolve19 } from "path";
 import { defineCommand as defineCommand14 } from "citty";
 async function resolveDeprecateTarget(platformDir, id) {
   const key = id.slice(0, id.indexOf("-"));
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join18(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join20(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync13(specPath)) {
     console.error(`spec deprecate: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -6481,11 +6628,11 @@ __export(exports_move, {
   moveCommand: () => moveCommand
 });
 import { existsSync as existsSync14 } from "fs";
-import { join as join19, resolve as resolve20 } from "path";
+import { join as join21, resolve as resolve20 } from "path";
 import { defineCommand as defineCommand15 } from "citty";
 async function loadDomainSide(platformDir, key) {
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join19(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join21(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync14(specPath))
     return null;
   const domain2 = JSON.parse(await Bun.file(specPath).text());
@@ -6719,14 +6866,13 @@ __export(exports_amend, {
   amendCommand: () => amendCommand
 });
 import { existsSync as existsSync15 } from "fs";
-import { join as join20, resolve as resolve21 } from "path";
+import { join as join22, resolve as resolve21 } from "path";
 import { defineCommand as defineCommand16 } from "citty";
 function validateAmendFields(args) {
   const hasText = typeof args.text === "string";
   const hasIssue = typeof args.issue === "string" && args.issue.trim() !== "";
   const hasWhy = typeof args.why === "string";
   const hasLives = typeof args.lives === "string";
-  const hasBinds = typeof args.binds === "string";
   const hasTerm = typeof args.term === "string";
   const hasAliases = typeof args.aliases === "string";
   if (!hasText && !hasWhy && !hasLives && !hasTerm && !hasAliases && !hasIssue) {
@@ -6741,12 +6887,12 @@ function validateAmendFields(args) {
     console.error("spec amend: --term must be a non-empty headword");
     process.exit(EXIT.USAGE);
   }
-  return { hasText, hasWhy, hasLives, hasBinds, hasTerm, hasAliases, hasIssue };
+  return { hasText, hasWhy, hasLives, hasTerm, hasAliases, hasIssue };
 }
 async function locateAmendEntry(platformDir, id) {
   const key = id.slice(0, id.indexOf("-"));
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join20(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join22(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync15(specPath)) {
     console.error(`spec amend: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -6800,9 +6946,6 @@ function applyAmendMutations(req, args, fields) {
     fieldsChanged.push("lives");
     refValues.push(v);
   }
-  if (fields.hasBinds) {
-    refValues.push(args.binds.trim());
-  }
   if (fields.hasTerm) {
     const v = args.term.trim();
     req.term = v;
@@ -6849,10 +6992,6 @@ var init_amend = __esm(() => {
       },
       text: { type: "string", description: "New Requirement (statement) field value" },
       why: { type: "string", description: "New Why it matters field value" },
-      binds: {
-        type: "string",
-        description: "Binds value (validated for @-refs; not persisted in JSON \u2014 STOR-01)"
-      },
       lives: { type: "string", description: "New Lives in (livesIn) field value" },
       issue: {
         type: "string",
@@ -7121,7 +7260,7 @@ __export(exports_resolve, {
   resolveCommand: () => resolveCommand
 });
 import { statSync as statSync6 } from "fs";
-import { join as join21, relative, resolve as resolve23, sep as sep3 } from "path";
+import { join as join23, relative, resolve as resolve23, sep as sep3 } from "path";
 import { defineCommand as defineCommand18 } from "citty";
 function classifyArg(a) {
   if (a.startsWith("--")) {
@@ -7160,7 +7299,7 @@ function splitFilesAndPlatformDir(positionals, fallbackPlatformDir) {
     const resolved = resolve23(last);
     if (statSync6(resolved).isDirectory()) {
       try {
-        if (statSync6(join21(resolved, "spec-engine")).isDirectory()) {
+        if (statSync6(join23(resolved, "spec-engine")).isDirectory()) {
           lastIsPlatformDir = true;
         } else {
           lastIsDirWithoutSpecEngine = true;
@@ -7456,7 +7595,7 @@ __export(exports_gate, {
   gateCommand: () => gateCommand
 });
 import { existsSync as existsSync16, mkdirSync as mkdirSync7 } from "fs";
-import { dirname as dirname10, join as join22, resolve as resolve24 } from "path";
+import { dirname as dirname10, join as join24, resolve as resolve24 } from "path";
 import { defineCommand as defineCommand19 } from "citty";
 function isEpipe(e) {
   if (e === null || typeof e !== "object")
@@ -7472,7 +7611,7 @@ function resolveGateArgs(args) {
     process.exit(EXIT.USAGE);
   }
   const platformDir = resolve24(args.platformDir ?? process.cwd());
-  const hasSpecEngineDir = existsSync16(join22(platformDir, "spec-engine"));
+  const hasSpecEngineDir = existsSync16(join24(platformDir, "spec-engine"));
   if (!hasSpecEngineDir) {
     console.error(formatNotASpecPlatform(platformDir));
     process.exit(EXIT.USAGE);
@@ -7598,7 +7737,7 @@ var init_gate = __esm(() => {
 });
 
 // src/guard/collect.ts
-import { join as join23 } from "path";
+import { join as join25 } from "path";
 function isIgnored(path) {
   return isPathIgnored(path);
 }
@@ -7655,7 +7794,7 @@ async function collectWorktreeReqs(canonicalDir) {
   const activeIds = new Set;
   const supersedesTargets = new Set;
   for (const rel of await findDomainJsonFiles(canonicalDir)) {
-    const text = await Bun.file(join23(canonicalDir, rel)).text();
+    const text = await Bun.file(join25(canonicalDir, rel)).text();
     for (const r of parseReqs(text)) {
       ids.add(r.id);
       if (r.status.toLowerCase() === "active")
@@ -7683,7 +7822,7 @@ async function collectFacts(platformDir, ref, storage2) {
   const deletedSpecFiles = changed.filter((e) => e.status === "D" && isSpecFile(e.path)).map((e) => e.path);
   const base = collectBaseReqs2(platformDir, ref, specPaths);
   const baseTags = collectBaseTags(platformDir, ref, codePaths);
-  const worktree = await collectWorktreeReqs(join23(platformDir, CANONICAL_SPECS_DIR));
+  const worktree = await collectWorktreeReqs(join25(platformDir, CANONICAL_SPECS_DIR));
   const counts = tallyWorktreeTags(storage2);
   return {
     baseReqs: base.reqs,
@@ -10749,7 +10888,7 @@ var init_server = __esm(() => {
 
 // src/server/api.ts
 import { existsSync as existsSync17 } from "fs";
-import { join as join24 } from "path";
+import { join as join26 } from "path";
 function hasTraversalSegment(p) {
   return p.split(/[/\\]/).some((seg) => seg === "..");
 }
@@ -10856,7 +10995,7 @@ function resolveCreateTarget(c, platformDir, body) {
     return { ok: false, res: c.json({ error: "unknown domain key" }, 400) };
   }
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join24(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join26(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync17(specPath))
     return { ok: false, res: c.json({ error: "not found" }, 404) };
   return { ok: true, key, relFile, specPath };
@@ -10876,7 +11015,7 @@ function buildRequirement(body, id) {
 }
 async function locateRequirement(platformDir, id) {
   for (const key of listDomainKeys(platformDir)) {
-    const specPath = join24(platformDir, "spec-engine", key, "SPEC.json");
+    const specPath = join26(platformDir, "spec-engine", key, "SPEC.json");
     const relFile = `spec-engine/${key}/SPEC.json`;
     let domain2;
     try {
@@ -11304,12 +11443,12 @@ __export(exports_docs, {
   createDocsFetchHandler: () => createDocsFetchHandler
 });
 import { existsSync as existsSync19, statSync as statSync7 } from "fs";
-import { join as join25, normalize, sep as sep4 } from "path";
+import { join as join27, normalize, sep as sep4 } from "path";
 import { fileURLToPath } from "url";
 import { defineCommand as defineCommand22 } from "citty";
 function resolveDocsRootFrom(candidates) {
   for (const candidate of candidates) {
-    if (existsSync19(join25(candidate, "index.html")))
+    if (existsSync19(join27(candidate, "index.html")))
       return candidate;
   }
   return null;
@@ -11333,16 +11472,16 @@ function createDocsFetchHandler(root) {
     if (pathname.includes("\x00")) {
       return new Response("Bad request", { status: 400 });
     }
-    const target = normalize(join25(normalRoot, pathname));
+    const target = normalize(join27(normalRoot, pathname));
     if (target !== normalRoot && !target.startsWith(rootPrefix)) {
       return new Response("Not found", { status: 404 });
     }
-    for (const candidate of [target, join25(target, "index.html"), `${target}.html`]) {
+    for (const candidate of [target, join27(target, "index.html"), `${target}.html`]) {
       if (existsSync19(candidate) && statSync7(candidate).isFile()) {
         return new Response(Bun.file(candidate));
       }
     }
-    const notFoundPage = join25(normalRoot, "404.html");
+    const notFoundPage = join27(normalRoot, "404.html");
     if (existsSync19(notFoundPage)) {
       return new Response(Bun.file(notFoundPage), { status: 404 });
     }
@@ -11520,7 +11659,7 @@ import { defineCommand as defineCommand24, runMain, showUsage } from "citty";
 // package.json
 var package_default = {
   name: "@spec-engine/spec-engine",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Cross-repo spec engine \u2014 durable requirements with permanent IDs, bound to code via @spec tags, checked in CI. Ships the spec CLI, the local coverage webapp (spec serve), and offline docs (spec docs).",
   license: "MIT",
   type: "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-engine/spec-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Cross-repo spec engine — durable requirements with permanent IDs, bound to code via @spec tags, checked in CI. Ships the spec CLI, the local coverage webapp (spec serve), and offline docs (spec docs).",
   "license": "MIT",
   "type": "module",