@nurix/nustack 0.23.14 → 0.23.16

package/dist/records.schema.json

@@ -2682,6 +2682,436 @@
       ],
       "additionalProperties": false
     },
+    "SessionBrief": {
+      "type": "object",
+      "properties": {
+        "previousHandover": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "sessionId": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "runtime": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 64
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "handover": {
+                  "type": "string",
+                  "maxLength": 20000
+                },
+                "createdAt": {
+                  "type": "string",
+                  "maxLength": 64
+                }
+              },
+              "required": [
+                "sessionId",
+                "runtime",
+                "handover",
+                "createdAt"
+              ],
+              "additionalProperties": {}
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "openObligations": {
+          "type": "object",
+          "properties": {
+            "total": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "items": {
+              "maxItems": 50,
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "naturalKey": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  },
+                  "planAnchor": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "maxLength": 256
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "sessionId": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "maxLength": 128
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "payload": {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": {}
+                  },
+                  "createdAt": {
+                    "type": "string",
+                    "maxLength": 64
+                  }
+                },
+                "required": [
+                  "naturalKey",
+                  "planAnchor",
+                  "sessionId",
+                  "payload",
+                  "createdAt"
+                ],
+                "additionalProperties": {}
+              }
+            }
+          },
+          "required": [
+            "total",
+            "items"
+          ],
+          "additionalProperties": {}
+        },
+        "generatedAt": {
+          "type": "string",
+          "maxLength": 64
+        }
+      },
+      "required": [
+        "previousHandover",
+        "openObligations",
+        "generatedAt"
+      ],
+      "additionalProperties": {}
+    },
+    "SessionEvent": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "runtimeSessionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "start",
+            "end"
+          ]
+        },
+        "occurredAt": {
+          "type": "string",
+          "allOf": [
+            {
+              "type": "string",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+            },
+            {
+              "type": "string",
+              "pattern": "T\\d{2}:\\d{2}:\\d{2}"
+            }
+          ]
+        },
+        "extension": {
+          "type": "object",
+          "properties": {
+            "runtime": {
+              "type": "string",
+              "enum": [
+                "claude_code",
+                "codex",
+                "opencode",
+                "copilot_cli",
+                "nustack"
+              ]
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "harnessSemver": {
+              "type": "string",
+              "maxLength": 64,
+              "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+            },
+            "harnessDigest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            },
+            "configDigest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            },
+            "handover": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 20000
+            }
+          },
+          "required": [
+            "runtime"
+          ],
+          "additionalProperties": false
+        },
+        "isEngineSession": {
+          "type": "boolean"
+        },
+        "startCommit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,64}$"
+        }
+      },
+      "required": [
+        "sessionId",
+        "phase",
+        "occurredAt",
+        "extension"
+      ],
+      "additionalProperties": false
+    },
+    "SessionEventsRequest": {
+      "type": "object",
+      "properties": {
+        "events": {
+          "maxItems": 200,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "sessionId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "runtimeSessionId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "phase": {
+                "type": "string",
+                "enum": [
+                  "start",
+                  "end"
+                ]
+              },
+              "occurredAt": {
+                "type": "string",
+                "allOf": [
+                  {
+                    "type": "string",
+                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+                  },
+                  {
+                    "type": "string",
+                    "pattern": "T\\d{2}:\\d{2}:\\d{2}"
+                  }
+                ]
+              },
+              "extension": {
+                "type": "object",
+                "properties": {
+                  "runtime": {
+                    "type": "string",
+                    "enum": [
+                      "claude_code",
+                      "codex",
+                      "opencode",
+                      "copilot_cli",
+                      "nustack"
+                    ]
+                  },
+                  "model": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128
+                  },
+                  "harnessSemver": {
+                    "type": "string",
+                    "maxLength": 64,
+                    "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+                  },
+                  "harnessDigest": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  },
+                  "configDigest": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  },
+                  "handover": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 20000
+                  }
+                },
+                "required": [
+                  "runtime"
+                ],
+                "additionalProperties": false
+              },
+              "isEngineSession": {
+                "type": "boolean"
+              },
+              "startCommit": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{7,64}$"
+              }
+            },
+            "required": [
+              "sessionId",
+              "phase",
+              "occurredAt",
+              "extension"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "labelRows": {
+          "maxItems": 200,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "sessionId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "agentType": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "path": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "maxLength": 512
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "estimatedTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "returnedTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "handler": {
+                "type": "string",
+                "enum": [
+                  "outline",
+                  "bypass",
+                  "digest",
+                  "full_read",
+                  "local_model",
+                  "redirect",
+                  "pack_hit",
+                  "pack_miss"
+                ]
+              },
+              "checkResult": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "enum": [
+                      "pass",
+                      "fail",
+                      "budget",
+                      "unavailable",
+                      "latched"
+                    ]
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "isBypassUsed": {
+                "type": "boolean"
+              },
+              "latencyMs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "tokensKeptOut": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              "createdAt": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "id",
+              "sessionId",
+              "agentType",
+              "path",
+              "estimatedTokens",
+              "returnedTokens",
+              "handler",
+              "checkResult",
+              "isBypassUsed",
+              "latencyMs",
+              "tokensKeptOut",
+              "createdAt"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "events",
+        "labelRows"
+      ],
+      "additionalProperties": false
+    },
     "SessionRowExtension": {
       "type": "object",
       "properties": {

package/dist/vendor/harness/rules/bookkeeping.js

@@ -0,0 +1,44 @@
+// packages/harness/src/rules/bookkeeping.ts - The `bookkeeping` rule: a changed path owned by a document (narrower
+// glob wins) whose owning document is not in the same change set. etna's commit wall, ported as a change rule so the
+// status check can block owned code merged without its document. A caller's `RuleWaiver` scoped to `bookkeeping` and
+// naming the owning document drops the finding. docs/architecture/systems/harness-records.md speaks for it (Status
+// check and enforcement).
+import { waiverCovers } from './context.js';
+import { owningDoc, scanOwningDocs } from './ownership.js';
+/** The waiver kind a bookkeeping finding is covered by: the caller names the owning document in backticks. */
+export const BOOKKEEPING_WAIVER_KIND = 'bookkeeping';
+const touchedPaths = (change) => (change.status === 'R' && change.from ? [change.path, change.from] : [change.path]);
+export function bookkeepingRule(ctx, docsRoot) {
+    const changes = ctx.changes ?? [];
+    if (changes.length === 0)
+        return [];
+    const inChangeSet = new Set(changes.flatMap(touchedPaths));
+    const docs = scanOwningDocs(ctx.head, docsRoot);
+    if (docs.length === 0)
+        return [];
+    const missing = new Map();
+    for (const change of changes) {
+        for (const path of touchedPaths(change)) {
+            if (path.startsWith(`${docsRoot}/`) || path.endsWith('.md'))
+                continue;
+            const owner = owningDoc(ctx.head, path, docs);
+            if (!owner)
+                continue;
+            const candidates = [owner.doc.doc, ...owner.tied.map((entry) => entry.doc)];
+            if (candidates.some((doc) => inChangeSet.has(doc)))
+                continue;
+            const paths = missing.get(owner.doc.doc) ?? [];
+            if (!paths.includes(path))
+                paths.push(path);
+            missing.set(owner.doc.doc, paths);
+        }
+    }
+    const findings = [];
+    for (const [doc, paths] of missing) {
+        if (waiverCovers(ctx.waivers ?? [], BOOKKEEPING_WAIVER_KIND, doc, ctx.today))
+            continue;
+        for (const path of paths)
+            findings.push({ id: 'bookkeeping.owner_not_updated', path, message: `${path} is owned by ${doc}, which this change does not update` });
+    }
+    return findings;
+}

package/dist/vendor/harness/rules/changeRules.js

@@ -35,11 +35,18 @@ export function planGateRule(ctx, root) {
     }
     return findings;
 }
-/** Completion integrity for every gated plan at head: discharged ledgers, active Spec docs, their checklists, an Abandoned plan's backlog. */
+/**
+ * Completion integrity for the gated plans at head: discharged ledgers, active Spec docs, their checklists, an Abandoned
+ * plan's backlog. With a change set, only the plans it adds or modifies are judged, so a change is never blocked by an
+ * older plan's debt it did not touch; with none, every plan at head is.
+ */
 export function ledgerRule(ctx, root) {
     const findings = [];
     const folder = plansFolder(root);
+    const touched = ctx.changes ? new Set(ctx.changes.filter((change) => change.status !== 'D').map((change) => change.path)) : null;
     for (const path of markdownIn(ctx.head, folder)) {
+        if (touched && !touched.has(path))
+            continue;
         const file = basenamePosix(path);
         const text = ctx.head.read(path) ?? '';
         if (!/^\*\*Gates:\*\*/m.test(text))

package/dist/vendor/harness/rules/index.js

@@ -7,6 +7,7 @@ import { changelogEntryRule, changelogRule, frozenRecordRule, ledgerRule, planGa
 import { outputGateRule } from './outputGate.js';
 import { ownershipRule } from './ownership.js';
 import { packageTableRule } from './packageTable.js';
+import { bookkeepingRule } from './bookkeeping.js';
 import { branchWorktreeRule, commitClaimRule, exitStopRule, foreignClaimRule, liveCommandRule, openDenialsRule, queueRule } from './sessionWalls.js';
 export * from './context.js';
 export { resolveDocsRoot, docsRootDeclaration, DEFAULT_DOCS_ROOT, DOCS_ROOT_SOURCES } from './docsRoot.js';
@@ -15,7 +16,9 @@ export { listPlans, openGatedPlans, planScopePaths, inPlanScope, undischargedRow
 export { changelogExemptFile, frozenReason, protectedListPath } from './changeRules.js';
 export { approvedPackages, rejectedPackages, APPROVED_TABLE_PATH } from './packageTable.js';
 export { AGENT_BRANCH_PREFIX, parseAgentRef } from './outputGate.js';
-/** Every rule id, append-only: an id is never renamed or removed. The last six delegate to other rules. */
+export { BOOKKEEPING_WAIVER_KIND } from './bookkeeping.js';
+export { PLAN_KEY_PATTERN, PLAN_KEY_SCAN_BYTES, formatPlanKey, readPlanKey, planKeyOf } from './planKey.js';
+/** Every rule id, append-only: an id is never renamed or removed. Every id in RULE_ALIASES delegates to other rules. */
 export const RULE_IDS = [
     'ownership',
     'plan-gate',
@@ -39,6 +42,8 @@ export const RULE_IDS = [
     'file-gate',
     'bash-write-screen',
     'harness-checks',
+    'bookkeeping',
+    'bookkeeping-clean',
 ];
 export const isRuleId = (value) => RULE_IDS.includes(value);
 /** Seed ids naming a check another rule already makes: each runs its targets, whose findings keep their own ids. */
@@ -48,7 +53,8 @@ export const RULE_ALIASES = {
     'commit-gate': ['changelog'],
     'file-gate': ['plan-gate'],
     'bash-write-screen': ['frozen-record', 'protected-file'],
-    'harness-checks': ['ownership', 'ledger', 'changelog'],
+    'harness-checks': ['ownership', 'ledger', 'changelog', 'bookkeeping'],
+    'bookkeeping-clean': ['bookkeeping'],
 };
 const SESSION_RULES = ['branch-worktree', 'live-command', 'commit-claim', 'foreign-claim', 'open-denials', 'exit-stop', 'queue'];
 /** Change rules judge trees and a change set; session rules judge one session's action or facts, at the hook. */
@@ -63,6 +69,7 @@ const DIRECT_READS = {
     'changelog-entry': [...DOCS_SOURCES, '@docs/history/plans/**/*.md', '@docs/history/changelog/**/*.md'],
     'package-table': ['**/package.json', '.claude/hooks/approved-packages.md', '.claude/rules/general.md', '.claude/rules/testing.md'],
     'protected-file': [...DOCS_SOURCES, '@docs/operations/protected-files.md'],
+    bookkeeping: [...DOCS_SOURCES, '@docs/**/*.md'],
 };
 /** The path patterns each rule reads, docs-root-relative ones written `@docs/…`; a delegating id's is its targets' union. */
 export const RULE_READS = Object.fromEntries(RULE_IDS.map((id) => [id, [...new Set((RULE_ALIASES[id] ?? [id]).flatMap((target) => DIRECT_READS[target] ?? []))]]));
@@ -83,6 +90,7 @@ const RULES = {
     'open-denials': openDenialsRule,
     'exit-stop': exitStopRule,
     queue: queueRule,
+    bookkeeping: (ctx) => bookkeepingRule(ctx, docsRootOf(ctx)),
 };
 export class UnknownRuleError extends Error {
     constructor(id) {

package/dist/vendor/harness/rules/planKey.js

@@ -0,0 +1,49 @@
+// packages/harness/src/rules/planKey.ts - The plan key's one grammar: the header line `**Plan key:** <projectId>:<anchor>`
+// a plan is written with at creation and never changes after, a rename included. Not a rule id; the status check, the
+// CLI and the plan template writer read the same pattern. docs/architecture/systems/harness-records.md speaks for it
+// (Record kinds, Status check and enforcement).
+/**
+ * The key line. The anchor group restates ph07 Decision 4's plan anchor grammar (`^\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*$`)
+ * rather than importing `@nurix/contracts`, which the bundled CLI may not carry.
+ */
+export const PLAN_KEY_PATTERN = /^\*\*Plan key:\*\* ([^\s:]{1,128}):(\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*)$/m;
+/** How far into a plan the key is looked for: a header-bytes read of this many bytes parses as a full read does. */
+export const PLAN_KEY_SCAN_BYTES = 4096;
+const KEY_LINE = /^\*\*Plan key:\*\*/;
+export function formatPlanKey(projectId, anchor) {
+    return `**Plan key:** ${projectId}:${anchor}`;
+}
+/** The newline-terminated lines that end within the first PLAN_KEY_SCAN_BYTES bytes, so a cut line never parses. */
+function scannedLines(text) {
+    const bytes = new TextEncoder().encode(text);
+    const head = bytes.length > PLAN_KEY_SCAN_BYTES ? bytes.subarray(0, PLAN_KEY_SCAN_BYTES) : bytes;
+    const decoded = new TextDecoder('utf-8', { fatal: false }).decode(head);
+    const lastNewline = decoded.lastIndexOf('\n');
+    if (lastNewline === -1)
+        return [];
+    return decoded.slice(0, lastNewline).split('\n').map((line) => line.replace(/\r$/, ''));
+}
+/** The key the plan's header block declares, or null: no line, a malformed line, or two lines. */
+export function readPlanKey(text) {
+    const lines = scannedLines(text);
+    const title = lines.findIndex((line) => /^# /.test(line));
+    const header = [];
+    for (const line of lines.slice(title + 1)) {
+        if (/^## /.test(line))
+            break;
+        header.push(line);
+    }
+    const keyLines = header.filter((line) => KEY_LINE.test(line));
+    if (keyLines.length !== 1)
+        return null;
+    const match = PLAN_KEY_PATTERN.exec(keyLines[0]);
+    return match ? { projectId: match[1], anchor: match[2] } : null;
+}
+/** The plan's key: the declared one, else `projectId` with the file name's anchor. */
+export function planKeyOf(text, path, projectId) {
+    const declared = readPlanKey(text);
+    if (declared)
+        return { ...declared, isDeclared: true };
+    const file = path.slice(path.lastIndexOf('/') + 1).replace(/\.md$/, '');
+    return { projectId, anchor: file, isDeclared: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.23.14",
+  "version": "0.23.16",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -34,9 +34,9 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/contracts": "2.0.1",
-    "@nurix/nustack.studio": "0.0.0",
+    "@nurix/contracts": "2.0.2",
     "@nurix/harness": "0.0.0",
+    "@nurix/nustack.studio": "0.0.0",
     "@nurix/nustack.ui": "0.0.0"
   },
   "publishConfig": {