@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/writes/sent-log.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/writes/sent-log.mjs — durable JSONL record of executed external writes.
+ *
+ * WriteSentLog persists idempotency keys and outcomes so a retried or duplicate
+ * write-intent is deduplicated rather than re-executed against the remote system.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class WriteSentLog {
+  #records = [];
+  #persistPath = null;
+
+  constructor({ persistPath } = {}) {
+    if (persistPath) {
+      this.#persistPath = persistPath;
+      this.#load();
+    }
+  }
+
+  record(entry) {
+    const rec = {
+      idempotencyKey: entry.idempotencyKey,
+      writeType: entry.writeType,
+      provider: entry.provider,
+      sentAt: entry.sentAt || new Date().toISOString(),
+      completedAt: entry.completedAt || null,
+      status: entry.status || 'pending',
+      externalUrl: entry.externalUrl || null,
+      externalId: entry.externalId || null,
+      result: entry.result || null,
+      error: entry.error || null,
+    };
+    this.#records.push(rec);
+    this.#persist();
+    return rec;
+  }
+
+  findByIdempotencyKey(key) {
+    let found = null;
+    for (const r of this.#records) {
+      if (r.idempotencyKey === key) found = r;
+    }
+    return found;
+  }
+
+  list({ provider, status, since } = {}) {
+    let results = [...this.#records];
+    if (provider) results = results.filter(r => r.provider === provider);
+    if (status) results = results.filter(r => r.status === status);
+    if (since) results = results.filter(r => new Date(r.sentAt) >= new Date(since));
+    return results;
+  }
+
+  pruneOlderThan(ms) {
+    const cutoff = Date.now() - ms;
+    const before = this.#records.length;
+    this.#records = this.#records.filter(r => new Date(r.sentAt).getTime() > cutoff);
+    this.#persist();
+    return before - this.#records.length;
+  }
+
+  #persist() {
+    if (!this.#persistPath) return;
+    try {
+      fs.mkdirSync(path.dirname(this.#persistPath), { recursive: true });
+      const lines = this.#records.map(r => JSON.stringify(r)).join('\n');
+      fs.writeFileSync(this.#persistPath, lines + '\n', 'utf8');
+    } catch {}
+  }
+
+  #load() {
+    try {
+      if (!fs.existsSync(this.#persistPath)) return;
+      const lines = fs.readFileSync(this.#persistPath, 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try { this.#records.push(JSON.parse(line)); } catch {}
+      }
+    } catch {}
+  }
+
+  static resolvePersistPath(rootDir) {
+    return path.join(rootDir, '.cx', 'writes', 'sent-log.jsonl');
+  }
+}

package/lib/writes/write-intent.mjs

@@ -0,0 +1,109 @@
+/**
+ * lib/writes/write-intent.mjs — the writeIntent record: the only artifact
+ * shape a specialist, embed capability, or MCP caller may produce when it
+ * wants an external write to happen.
+ *
+ * A writeIntent never executes anything by itself. `buildWriteIntent`
+ * validates and normalizes the record; `lib/writes/control-plane.mjs` is the
+ * only module that turns an *approved* writeIntent into a call through
+ * lib/writes/envelope.mjs. Nothing in this file resolves a provider adapter
+ * or performs I/O — it is schema and validation only, so it stays importable
+ * from any orchestration or embed path without smuggling in write access.
+ */
+
+/** Providers with a governed-write adapter under lib/providers/contract/adapters/*. */
+export const KNOWN_PROVIDERS = Object.freeze(['jira', 'github', 'confluence']);
+
+/**
+ * Validate a writeIntent's required shape. Returns `{ ok: true }` or
+ * `{ ok: false, errors: string[] }` — never throws, so a malformed proposal
+ * from a specialist degrades to a rejected intent rather than crashing the
+ * caller.
+ *
+ * @param {object} intent
+ * @param {string} intent.providerId - one of KNOWN_PROVIDERS
+ * @param {string} intent.writeKind - adapter-specific write type (e.g. 'issue', 'comment')
+ * @param {object} intent.payload - write payload passed to the adapter
+ * @param {object} [intent.requestedBy] - actor identity of the recommending specialist
+ * @returns {{ ok: boolean, errors?: string[] }}
+ */
+export function validateWriteIntent(intent) {
+  const errors = [];
+  if (!intent || typeof intent !== 'object') {
+    return { ok: false, errors: ['writeIntent must be an object'] };
+  }
+  if (!intent.providerId || typeof intent.providerId !== 'string') {
+    errors.push('writeIntent.providerId is required');
+  } else if (!KNOWN_PROVIDERS.includes(intent.providerId)) {
+    errors.push(`writeIntent.providerId "${intent.providerId}" is not a known governed provider (${KNOWN_PROVIDERS.join(', ')})`);
+  }
+  if (!intent.writeKind || typeof intent.writeKind !== 'string') {
+    errors.push('writeIntent.writeKind is required');
+  }
+  if (!intent.payload || typeof intent.payload !== 'object') {
+    errors.push('writeIntent.payload is required and must be an object');
+  }
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+/**
+ * Build a normalized writeIntent record from a specialist's recommendation.
+ * Throws on an invalid intent so a caller cannot silently enqueue a
+ * malformed record — the run should see the failure at recommend time, not
+ * discover it later when the control plane tries to execute it.
+ *
+ * @param {object} spec
+ * @param {string} spec.providerId
+ * @param {string} spec.writeKind
+ * @param {object} spec.payload
+ * @param {object} [spec.requestedBy] - { specialistId, role, serviceId, sessionId }
+ * @param {string} [spec.surface] - origin surface, e.g. 'embed-capability' | 'mcp' | 'cli'
+ * @returns {{ providerId: string, writeKind: string, payload: object, requestedBy: object, surface: string, tool: string }}
+ */
+export function buildWriteIntent(spec) {
+  const intent = {
+    providerId: spec?.providerId,
+    writeKind: spec?.writeKind,
+    payload: spec?.payload,
+  };
+  const result = validateWriteIntent(intent);
+  if (!result.ok) {
+    throw new Error(`buildWriteIntent: invalid writeIntent — ${result.errors.join('; ')}`);
+  }
+  return {
+    providerId: intent.providerId,
+    writeKind: intent.writeKind,
+    payload: intent.payload,
+    requestedBy: spec?.requestedBy ?? {},
+    surface: spec?.surface ?? 'unknown',
+    tool: writeIntentToolName(intent.providerId, intent.writeKind),
+  };
+}
+
+/**
+ * The tool-name encoding shared with lib/embed/capability-jobs.mjs's
+ * ApprovalQueue.enqueue({ tool }) calls and lib/embed/authority-guard.mjs's
+ * grant keys — "<providerId>.<writeKind>", e.g. "jira.issue". Kept in one
+ * place so the control-plane drain and the enqueue side can never drift.
+ *
+ * @param {string} providerId
+ * @param {string} writeKind
+ * @returns {string}
+ */
+export function writeIntentToolName(providerId, writeKind) {
+  return `${providerId}.${writeKind}`;
+}
+
+/**
+ * Parse a "<providerId>.<writeKind>" tool name back into its parts. Returns
+ * null when the name has no dot, which the caller should treat as
+ * unresolvable rather than guessing.
+ *
+ * @param {string} tool
+ * @returns {{ providerId: string, writeKind: string }|null}
+ */
+export function parseWriteIntentToolName(tool) {
+  const idx = typeof tool === 'string' ? tool.indexOf('.') : -1;
+  if (idx <= 0 || idx === tool.length - 1) return null;
+  return { providerId: tool.slice(0, idx), writeKind: tool.slice(idx + 1) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -57,9 +57,10 @@
     "mcp": "node lib/mcp/server.mjs",
     "doctor": "node ./bin/construct doctor",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
-    "test:visual": "node -e \"console.log('visual surface tests removed')\"",
+    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= ANTHROPIC_API_KEY= OPENAI_API_KEY= OPENROUTER_API_KEY= CX_MODEL_REASONING= CX_MODEL_STANDARD= CX_MODEL_FAST= CONSTRUCT_MODEL_REASONING= CONSTRUCT_MODEL_STANDARD= CONSTRUCT_MODEL_FAST= CONSTRUCT_PROVIDER_TIMEOUT_MS= WEB_SEARCH_URL= CX_USER_ENV_PATH= CONSTRUCT_TELEMETRY_URL= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
+    "test:visual": "node --test --test-timeout=120000 tests/visual/*.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
+    "ci:local": "bash scripts/ci-repro/run.sh",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node -e \"console.error('docs:init is deprecated — use: construct init --docs-preset=lean|product|full'); process.exit(1)\"",
@@ -70,33 +71,38 @@
     "docs:build": "node scripts/npm-run.mjs npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
     "lint:contracts": "node ./bin/construct lint:contracts",
+    "graph:gate": "node scripts/run-graph-gate.mjs",
     "lint:agents": "node ./bin/construct lint:agents",
     "gates:audit": "node ./bin/construct gates:audit",
     "evals": "node ./bin/construct evals",
     "certify:demos": "node ./bin/construct certify demos",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
+    "build:binary": "node scripts/build-binary.mjs",
+    "build:binary:fallback": "node scripts/build-sea.mjs",
     "examples:deck": "node scripts/generate-deck-examples.mjs",
     "examples:distribution": "node scripts/generate-distribution-examples.mjs",
     "clean:artifacts": "node scripts/clean-artifacts.mjs",
     "lint:scopes": "node scripts/lint-scopes.mjs",
     "catalog:regen": "node scripts/catalog-regen.mjs",
     "catalog:validate": "node scripts/catalog-validate.mjs",
+    "workflow-defs:check": "node scripts/check-workflow-defs-drift.mjs --check",
     "docs:sync": "node scripts/docs-sync.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "adapters": "node lib/adapters-sync.mjs",
-    "release:check": "npm run doctor && node ./bin/construct registry:validate --unified && npm run catalog:validate -- --check && npm test && npm run docs:update -- --check && npm run docs:site -- --check && npm run docs:sync -- --check && node ./bin/construct registry:generate-docs --check && npm run docs:verify -- --strict && node scripts/alignment/census.mjs --ratchet && npm run lint:comments && node ./bin/construct certify gate && npm run lint:templates",
+    "release:check": "npm run doctor && node ./bin/construct registry:validate --unified && npm run catalog:validate -- --check && npm run workflow-defs:check && npm test && node scripts/release-evidence-gate.mjs --skip-tests && npm run docs:update -- --check && npm run docs:site -- --check && npm run docs:sync -- --check && node ./bin/construct registry:generate-docs --check && npm run docs:verify -- --strict && node scripts/alignment/census.mjs --ratchet && npm run lint:comments && node ./bin/construct certify gate && npm run graph:gate && npm run lint:templates",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
     "version": "node scripts/sync-construct-version.mjs && git add -f .construct/version",
     "release:preflight": "node scripts/pre-release-check.mjs",
     "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
-    "postinstall": "node ./bin/construct-postinstall.mjs"
+    "postinstall": "node ./bin/construct-postinstall.mjs",
+    "deps:check": "node scripts/validate-dep-intent.mjs"
   },
   "dependencies": {
-    "@lancedb/lancedb": "^0.30.0",
+    "@lancedb/lancedb": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "apache-arrow": "^18.1.0",
     "js-yaml": "^4.2.0"
@@ -110,6 +116,7 @@
     "ai": "^6.0.208",
     "ink": "^7.1.0",
     "mammoth": "^1.12.0",
+    "postgres": "^3.4.9",
     "pptx-embed-fonts": "^0.0.6",
     "pptxgenjs": "^4.0.1",
     "react": "^19.2.7",
@@ -124,9 +131,10 @@
     "@eslint/js": "^9.39.4",
     "c8": "^11.0.0",
     "esbuild": "^0.28.1",
-    "postject": "1.0.0-alpha.6",
     "eslint": "^10.4.1",
     "globals": "^17.6.0",
-    "ink-testing-library": "^4.0.0"
+    "ink-testing-library": "^4.0.0",
+    "playwright": "^1.61.1",
+    "postject": "1.0.0-alpha.6"
   }
 }

package/personas/construct.md

@@ -25,9 +25,9 @@ Use the single-writer rule whenever multiple sessions are active: if two session
 
 ## Classify before acting <!-- cx:prio=1 -->
 
-Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is orchestrated, dispatch the chain — do not author the deliverable yourself.
+Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track`. When `track` is not immediate, dispatch through `orchestration_delegation_next` (below) — do not author the deliverable yourself and do not self-sequence off `orchestration_policy`'s specialist list from memory across turns.
 
-Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-devil-advocate is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
+Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-reviewer's plan-challenge mode is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
 
 Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
 
@@ -45,9 +45,18 @@ General conversation is still valid for scoping, clarification, and lightweight
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
 2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` with `handoffPacket` from `orchestration_policy`.
-3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
+3. **Specialist sequence**. the engine's job, not yours — see below.
 4. **Team routing**. name `teamRouting.primaryTeam` in the dispatch plan; route through `teamRouting.requiredApprovals` before DONE; if `teamRouting.blockedStatus` is set, stop and escalate along its `escalationPath` rather than proceeding.
 
+## Dispatch one step at a time <!-- cx:prio=1 -->
+
+Sequencing a multi-specialist chain is the flow engine's job (ADR-0067), not something to hold in your own context across turns. Once `orchestration_policy` says the track is not immediate, drive dispatch through `orchestration_delegation_next`, not by reading a full plan and self-sequencing:
+
+- Mint a `run_id` for this dispatch (a session or task id is fine) and call `orchestration_delegation_next` with the same `request`/`fileCount`/`moduleCount` you gave `orchestration_policy`, plus that `run_id`.
+- Act on exactly the returned `currentDelegation` — its `role`, `reason`, and `handoffContract` — and nothing else. Do not pre-plan the rest of the chain from a remembered dispatch plan.
+- Call again with the same `run_id` for the next specialist. Repeat until `done: true`.
+- The chain survives a restart: calling again with the same `run_id` in a later turn or session continues from wherever it left off, never re-running a specialist already dispatched.
+
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
 ## Branch + commit approval <!-- cx:prio=1 -->

package/registry/capabilities.json

@@ -1,16 +1,19 @@
 {
   "version": 1,
   "catalog": {
-    "generatedAt": "2026-07-01T01:09:33.824Z",
+    "generatedAt": "2026-07-06T22:40:56.862Z",
     "npmScripts": [
       "adapters",
       "audit:published",
+      "build:binary",
+      "build:binary:fallback",
       "build:sea",
       "catalog:regen",
       "catalog:validate",
       "certify:demos",
       "clean:artifacts",
       "coverage",
+      "deps:check",
       "docs:build",
       "docs:dev",
       "docs:init",
@@ -24,6 +27,7 @@
       "examples:deck",
       "examples:distribution",
       "gates:audit",
+      "graph:gate",
       "learning:status",
       "lint:agents",
       "lint:comments",
@@ -42,7 +46,8 @@
       "test:functional",
       "test:unit",
       "test:visual",
-      "version"
+      "version",
+      "workflow-defs:check"
     ],
     "cliCommands": [
       {
@@ -57,6 +62,12 @@
         "core": false,
         "internal": true
       },
+      {
+        "name": "approvals",
+        "category": "Core",
+        "core": true,
+        "internal": false
+      },
       {
         "name": "artifact",
         "category": "Work",
@@ -159,6 +170,12 @@
         "core": false,
         "internal": false
       },
+      {
+        "name": "db",
+        "category": "Models & Integrations",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "decisions",
         "category": "Advanced",
@@ -309,6 +326,12 @@
         "core": false,
         "internal": false
       },
+      {
+        "name": "flow",
+        "category": "Models & Integrations",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "gates:audit",
         "category": "Advanced",
@@ -519,6 +542,12 @@
         "core": false,
         "internal": true
       },
+      {
+        "name": "pack",
+        "category": "Work",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "plugin",
         "category": "Models & Integrations",
@@ -801,6 +830,12 @@
         "core": false,
         "internal": false
       },
+      {
+        "name": "workers",
+        "category": "Core",
+        "core": true,
+        "internal": false
+      },
       {
         "name": "workflow",
         "category": "Work",
@@ -815,15 +850,25 @@
       }
     ],
     "workflows": [
+      {
+        "type": "architecture-review",
+        "description": "Review an architecture or design for trade-offs, failure modes, and security exposure.",
+        "tier": "reasoning"
+      },
+      {
+        "type": "data-structure",
+        "description": "Parse, validate, and profile a raw dataset into a structured, described shape.",
+        "tier": "standard"
+      },
       {
         "type": "evidence-ingest",
         "description": "Ingest and structure raw evidence (notes, documents, signals) into a normalized summary.",
         "tier": "fast"
       },
       {
-        "type": "proposal-review",
-        "description": "Review a proposal for correctness, risk, and hidden assumptions before acceptance.",
-        "tier": "standard"
+        "type": "memo-draft",
+        "description": "Draft a decision or status memo from a problem statement and context.",
+        "tier": "fast"
       },
       {
         "type": "prd-draft",
@@ -831,8 +876,13 @@
         "tier": "standard"
       },
       {
-        "type": "architecture-review",
-        "description": "Review an architecture or design for trade-offs, failure modes, and security exposure.",
+        "type": "proposal-review",
+        "description": "Review a proposal for correctness, risk, and hidden assumptions before acceptance.",
+        "tier": "standard"
+      },
+      {
+        "type": "research-synthesis",
+        "description": "Synthesize multiple sources into a cited, evidence-graded research summary.",
         "tier": "reasoning"
       },
       {
@@ -841,9 +891,9 @@
         "tier": "reasoning"
       },
       {
-        "type": "research-synthesis",
-        "description": "Synthesize multiple sources into a cited, evidence-graded research summary.",
-        "tier": "reasoning"
+        "type": "structure-notes",
+        "description": "Structure an unclassified brain-dump or rough notes into a normalized summary with extracted intents.",
+        "tier": "fast"
       },
       {
         "type": "transcript-process",
@@ -851,32 +901,23 @@
         "tier": "fast"
       },
       {
-        "type": "data-structure",
-        "description": "Parse, validate, and profile a raw dataset into a structured, described shape.",
-        "tier": "standard"
-      },
-      {
-        "type": "memo-draft",
-        "description": "Draft a decision or status memo from a problem statement and context.",
-        "tier": "fast"
-      },
-      {
-        "type": "structure-notes",
-        "description": "Structure an unclassified brain-dump or rough notes into a normalized summary with extracted intents.",
+        "type": "triage",
+        "description": "Classify and route unstructured input to the appropriate workflow.",
         "tier": "fast"
       }
     ],
     "workflowTypes": [
+      "architecture-review",
+      "data-structure",
       "evidence-ingest",
-      "proposal-review",
+      "memo-draft",
       "prd-draft",
-      "architecture-review",
-      "risk-review",
+      "proposal-review",
       "research-synthesis",
+      "risk-review",
+      "structure-notes",
       "transcript-process",
-      "data-structure",
-      "memo-draft",
-      "structure-notes"
+      "triage"
     ]
   },
   "capabilities": [
@@ -1073,7 +1114,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "evidence-ingest"
         ]
@@ -1193,7 +1237,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "prd-draft"
         ]
@@ -1234,7 +1281,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "architecture-review"
         ]
@@ -1274,7 +1324,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "proposal-review"
         ]
@@ -1315,7 +1368,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "risk-review"
         ]
@@ -1396,7 +1452,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "transcript-process"
         ]
@@ -1436,7 +1495,10 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "data-structure"
         ]
@@ -1476,13 +1538,58 @@
           "workflow",
           "workflow invoke"
         ],
-        "npmScripts": [],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
         "workflows": [
           "memo-draft"
         ]
       },
       "_semanticDigest": "{\"description\":\"Draft a decision or status memo from a problem statement and context.\",\"criticality\":\"P2\",\"verification\":{\"functional\":\"tests/functional/embedded-contract-workflow-invoke.functional.test.mjs\"}}"
     },
+    {
+      "id": "workflow.triage",
+      "kind": "workflow",
+      "name": "Triage Workflow",
+      "description": "Classify and route unstructured input to the appropriate workflow.",
+      "criticality": "P2",
+      "ownerSpecialists": [
+        "orchestrator",
+        "researcher"
+      ],
+      "embeddedWorkflow": "triage",
+      "surfaces": {
+        "mcp": {
+          "supported": true,
+          "primary": true,
+          "tool": "workflow_invoke"
+        },
+        "cli": {
+          "supported": true,
+          "command": "construct workflow invoke",
+          "jsonTwin": true
+        }
+      },
+      "verification": {
+        "functional": "tests/functional/embedded-contract-triage.functional.test.mjs"
+      },
+      "humanGate": "proposal-only",
+      "edges": {
+        "cliCommands": [
+          "workflow",
+          "workflow invoke"
+        ],
+        "npmScripts": [
+          "release:check",
+          "workflow-defs:check"
+        ],
+        "workflows": [
+          "triage"
+        ]
+      },
+      "_semanticDigest": "{\"description\":\"Classify and route unstructured input to the appropriate workflow.\",\"criticality\":\"P2\",\"verification\":{\"functional\":\"tests/functional/embedded-contract-triage.functional.test.mjs\"}}"
+    },
     {
       "id": "document-type.research-brief",
       "kind": "document-type",

package/rules/common/comments.md

@@ -42,6 +42,7 @@ The blank line between the comment and the code is required. It signals "this co
 - **Narrative voice** (`// We weight BM25`, `// Now test the keys`, `// This correctly scores`) delete them
 - **Point-in-time notes** (`// X removed`, `// previously`, `// no longer`) belongs in git log
 - **Noise sentinels** (`// ok`, `// best effort`, `// skip`) delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
+- **Other-project comparisons** (`// per the LangGraph thread-vs-store split`) delete them; describe the behavior on its own terms. A prior-art comparison belongs in a decision document (`docs/decisions/**`, `docs/notes/**`) where it can carry a citation
 
 ## SLA annotations (hooks only)