@sentropic/track 0.96.2 → 0.97.1

package/dist/cli/desync.d.ts

@@ -7,11 +7,12 @@ export interface DesyncFinding {
     hint: string;
 }
 /**
- * SPEC §4 round-trip / desync rule: when an Item's `body` references a markdown file (a single-line
- * path ending in `.md`), that file MUST exist and its H1 title MUST match the Item title. A missing
- * file or a title mismatch is a desync finding (MVP reports; it never auto-repairs). Inline-prose
- * bodies (the common case, incl. BRANCH-imported items) are not file references and are skipped.
- * Each finding carries a `hint` — a suggested fix the human/agent may apply (track never does).
+ * SPEC §4 round-trip / desync rule: when an Item's `body` is a markdown file reference (see
+ * {@link resolveMarkdownRef}), that file MUST exist and its H1 title MUST match the Item title. A
+ * missing file or a title mismatch is a desync finding (MVP reports; it never auto-repairs).
+ * Inline-prose bodies (the common case, incl. BRANCH-imported items and spec citations) are not file
+ * references and are skipped. Each finding carries a `hint` — a suggested fix the human/agent may
+ * apply (track never does).
  */
 export declare function desyncFindings(state: State, cwd: string): DesyncFinding[];
 //# sourceMappingURL=desync.d.ts.map

package/dist/cli/desync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"desync.d.ts","sourceRoot":"","sources":["../../src/cli/desync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CAkCzE"}
+{"version":3,"file":"desync.d.ts","sourceRoot":"","sources":["../../src/cli/desync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAA;CACb;AA6CD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CAmCzE"}

package/dist/cli/desync.js

@@ -1,20 +1,70 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 /**
- * SPEC §4 round-trip / desync rule: when an Item's `body` references a markdown file (a single-line
- * path ending in `.md`), that file MUST exist and its H1 title MUST match the Item title. A missing
- * file or a title mismatch is a desync finding (MVP reports; it never auto-repairs). Inline-prose
- * bodies (the common case, incl. BRANCH-imported items) are not file references and are skipped.
- * Each finding carries a `hint` — a suggested fix the human/agent may apply (track never does).
+ * Decide whether an item `body` is a markdown *file reference* (SPEC §4 round-trip). Returns the
+ * resolved path plus whether it exists on disk, or `null` for everything that is NOT a reference —
+ * prose, a `.md`-suffixed domain/email, or any body that is not unambiguously a single path.
+ *
+ * The round-trip rule must also fire on a *missing* file, so existence alone cannot be the gate: for
+ * an absent file we still need a syntactic decision "did the author mean a path?". That decision is
+ * deliberately CONSERVATIVE — precision over recall — because the reported defect was prose being
+ * mistaken for a path, and a `.md`-suffix is a false signal (`.md` is also Moldova's ccTLD, and any
+ * sentence can end in a "…foo.md" citation). The gate is:
+ *
+ *   1. If the resolved path EXISTS on disk, it is a reference (ground truth — bare or nested, with
+ *      spaces or not). This is what validates a real spec file's H1 against the item title.
+ *   2. Otherwise it is a reference only when the body is a single, unambiguous path *token*:
+ *        - it contains a directory separator `/` (a nested path such as `docs/specs/foo.md`); a
+ *          bare word / domain / email like `service.md` or `contact@service.md` is NOT a reference
+ *          unless it actually exists (rule 1), so `.md` TLDs never desync;
+ *        - it contains NO whitespace — prose that merely cites a spec ("… Spec: docs/x.md") has
+ *          interior whitespace and is not a path token;
+ *        - it contains no `:` — a glued prose label ("Ref:docs/x.md", "See:docs/x.md") is prose,
+ *          not a clean path (`:` is not used in this repo's paths).
+ *
+ * POLICY — ESCALATED to the conductor (two intentional, reversible defaults):
+ *   (a) A MISSING path that contains whitespace (e.g. `docs/Getting Started.md`) is skipped as
+ *       prose. This is IRREDUCIBLE: a spaced path is character-for-character indistinguishable from
+ *       a spaced prose body that ends in a "…/foo.md" citation (both have whitespace + `/` + `.md`),
+ *       so flagging the former necessarily re-flags the latter — i.e. re-opens the reported bug. The
+ *       repo's spec-file convention uses hyphenated, space-free names, so precision-first is safe
+ *       here today. If spaced spec filenames are ever adopted, relax the `\s` rule below (one line)
+ *       and accept that prose citations will desync again.
+ *   (b) A MISSING bare name (no `/`) is not validated, so `.md` domains/emails never desync. A bare
+ *       spec is validated only once it exists (rule 1).
+ */
+function resolveMarkdownRef(body, cwd) {
+    if (!body.endsWith('.md'))
+        return null;
+    const path = isAbsolute(body) ? body : join(cwd, body);
+    if (existsSync(path))
+        return { path, exists: true };
+    if (/\s/.test(body))
+        return null; // prose / spaced citation — not a single path token
+    if (!body.includes('/'))
+        return null; // bare word / domain / email that does not exist
+    if (body.includes(':'))
+        return null; // glued prose label (Ref:/See:/Spec:) — not a clean path
+    return { path, exists: false }; // a clean, nested, missing path: a genuine desync
+}
+/**
+ * SPEC §4 round-trip / desync rule: when an Item's `body` is a markdown file reference (see
+ * {@link resolveMarkdownRef}), that file MUST exist and its H1 title MUST match the Item title. A
+ * missing file or a title mismatch is a desync finding (MVP reports; it never auto-repairs).
+ * Inline-prose bodies (the common case, incl. BRANCH-imported items and spec citations) are not file
+ * references and are skipped. Each finding carries a `hint` — a suggested fix the human/agent may
+ * apply (track never does).
  */
 export function desyncFindings(state, cwd) {
     const findings = [];
     for (const item of state.items.values()) {
         const ref = item.body?.trim();
-        if (ref === undefined || !/^[^\n]+\.md$/.test(ref))
+        if (ref === undefined)
+            continue;
+        const resolved = resolveMarkdownRef(ref, cwd);
+        if (resolved === null)
             continue;
-        const path = isAbsolute(ref) ? ref : join(cwd, ref);
-        if (!existsSync(path)) {
+        if (!resolved.exists) {
             findings.push({
                 kind: 'desync',
                 itemId: item.id,
@@ -23,7 +73,7 @@ export function desyncFindings(state, cwd) {
             });
             continue;
         }
-        const h1 = /^#\s+(.+?)\s*$/m.exec(readFileSync(path, 'utf8'))?.[1];
+        const h1 = /^#\s+(.+?)\s*$/m.exec(readFileSync(resolved.path, 'utf8'))?.[1];
         if (h1 === undefined) {
             // SPEC §4 requires the H1 to MATCH the title; a file with no H1 cannot match.
             findings.push({

package/dist/cli/desync.js.map

@@ -1 +1 @@
-{"version":3,"file":"desync.js","sourceRoot":"","sources":["../../src/cli/desync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAY5C;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,GAAW;IACtD,MAAM,QAAQ,GAAoB,EAAE,CAAA;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAA;QAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC5D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QACnD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,gCAAgC,GAAG,EAAE;gBAC7C,IAAI,EAAE,WAAW,GAAG,mBAAmB,IAAI,CAAC,KAAK,qCAAqC;aACvF,CAAC,CAAA;YACF,SAAQ;QACV,CAAC;QACD,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAClE,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,8EAA8E;YAC9E,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,kCAAkC,GAAG,EAAE;gBAC/C,IAAI,EAAE,0BAA0B,IAAI,CAAC,KAAK,SAAS,GAAG,GAAG;aAC1D,CAAC,CAAA;QACJ,CAAC;aAAM,IAAI,EAAE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,OAAO,EAAE,oBAAoB,IAAI,CAAC,KAAK,MAAM,GAAG,GAAG;gBAC3D,IAAI,EAAE,sCAAsC,EAAE,oBAAoB,GAAG,WAAW,IAAI,CAAC,KAAK,GAAG;aAC9F,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}
+{"version":3,"file":"desync.js","sourceRoot":"","sources":["../../src/cli/desync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAY5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAS,kBAAkB,CAAC,IAAY,EAAE,GAAW;IACnD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACtD,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;IACnD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA,CAAC,oDAAoD;IACrF,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA,CAAC,iDAAiD;IACtF,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA,CAAC,yDAAyD;IAC7F,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA,CAAC,kDAAkD;AACnF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,GAAW;IACtD,MAAM,QAAQ,GAAoB,EAAE,CAAA;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAA;QAC7B,IAAI,GAAG,KAAK,SAAS;YAAE,SAAQ;QAC/B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAC7C,IAAI,QAAQ,KAAK,IAAI;YAAE,SAAQ;QAC/B,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,gCAAgC,GAAG,EAAE;gBAC7C,IAAI,EAAE,WAAW,GAAG,mBAAmB,IAAI,CAAC,KAAK,qCAAqC;aACvF,CAAC,CAAA;YACF,SAAQ;QACV,CAAC;QACD,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC3E,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,8EAA8E;YAC9E,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,kCAAkC,GAAG,EAAE;gBAC/C,IAAI,EAAE,0BAA0B,IAAI,CAAC,KAAK,SAAS,GAAG,GAAG;aAC1D,CAAC,CAAA;QACJ,CAAC;aAAM,IAAI,EAAE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,OAAO,EAAE,oBAAoB,IAAI,CAAC,KAAK,MAAM,GAAG,GAAG;gBAC3D,IAAI,EAAE,sCAAsC,EAAE,oBAAoB,GAAG,WAAW,IAAI,CAAC,KAAK,GAAG;aAC9F,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/track",
-  "version": "0.96.2",
+  "version": "0.97.1",
   "description": "Typed product-backlog and spec/plan/UAT system of record for the sentropic ecosystem (record-only MVP).",
   "license": "MIT",
   "author": "Fabien Antoine",