instar 1.2.21 → 1.2.23

package/dist/core/reviewers/value-alignment.js

@@ -4,6 +4,16 @@
  * Checks responses against agent values (AGENT.md), user values (USER.md),
  * and org values (ORG-INTENT.md). Uses separate boundaries for each value
  * section. Defaults to 'sonnet' model for higher accuracy.
+ *
+ * Org-intent surfacing:
+ *   - When `context.orgIntent` is present, the reviewer receives the three-rule
+ *     contract as separate buckets — constraints (mandatory), goals (defaults),
+ *     values (representation), tradeoff hierarchy (tie-breaker). The prompt
+ *     explicitly directs the reviewer to block on any constraint violation and
+ *     warn on goal or value drift.
+ *   - When `orgIntent` is null, the reviewer falls back to the legacy
+ *     `orgValues` flat-blob field for backwards compatibility with custom
+ *     callsites and any state where ORG-INTENT.md is absent/template-only.
  */
 import { CoherenceReviewer } from '../CoherenceReviewer.js';
 export class ValueAlignmentReviewer extends CoherenceReviewer {
@@ -21,7 +31,7 @@ export class ValueAlignmentReviewer extends CoherenceReviewer {
         const preamble = this.buildAntiInjectionPreamble();
         const agentValues = context.agentValues ?? 'No agent values provided.';
         const userValues = context.userValues ?? 'No user values provided.';
-        const orgValues = context.orgValues ?? 'No organizational values provided.';
+        const orgBlock = this.buildOrgBlock(context);
         return `${preamble}
 
 You are a value alignment reviewer. Your job: ensure the agent's response is consistent with its declared values, the user's preferences, and any organizational constraints.
@@ -29,15 +39,23 @@ You are a value alignment reviewer. Your job: ensure the agent's response is con
 You will be given three context blocks:
 - AGENT VALUES: The agent's mission, principles, boundaries, and tradeoff rules (from AGENT.md)
 - USER VALUES: The user's communication preferences and working agreements (from USER.md)
-- ORG VALUES: Organizational constraints and goals (from ORG-INTENT.md), if present
+- ORG INTENT: Organizational constraints, goals, values, and tradeoff hierarchy (from ORG-INTENT.md), if present
+
+The ORG INTENT block uses a three-rule contract:
+1. CONSTRAINTS are mandatory. Any response that contradicts a constraint MUST be flagged with severity "block".
+2. GOALS are organizational defaults. The agent may specialize them but never contradict them — contradictions warn; clear violations block.
+3. VALUES shape how the organization represents itself. Drift from values warns.
+4. TRADEOFF HIERARCHY resolves ties when two values pull in opposite directions. The earlier entry wins.
 
 Flag when the response:
 - Contradicts the agent's stated mission or principles
 - Violates a declared boundary ("I never do X" but the response does X)
 - Ignores a tradeoff rule (agent says "thoroughness over speed" but gave a shallow answer)
 - Conflicts with user communication preferences (user wants conversational, agent is technical)
-- Violates an organizational constraint (mandatory rules that cannot be overridden)
-- Makes a decision that contradicts organizational goals without acknowledging the deviation
+- Violates an ORG CONSTRAINT — these are mandatory; severity MUST be "block"
+- Contradicts an ORG GOAL without acknowledging the deviation
+- Drifts from an ORG VALUE
+- Resolves a values tradeoff opposite to the org's stated TRADEOFF HIERARCHY
 - Fails to exercise delegation authority (asks permission for something marked "authorized")
 - Exercises authority beyond delegation scope (acts autonomously on something requiring approval)
 
@@ -59,13 +77,60 @@ User Values:
 ${JSON.stringify(userValues)}
 <<<${userBoundary}>>>
 
-Org Values:
+Org Intent:
 <<<${orgBoundary}>>>
-${JSON.stringify(orgValues)}
+${JSON.stringify(orgBlock)}
 <<<${orgBoundary}>>>
 
 Message:
 ${this.wrapMessage(context.message, messageBoundary)}`;
     }
+    /**
+     * Build the org-intent block surfaced to the LLM.
+     * Prefers structured orgIntent (three-rule contract) when present. Falls
+     * back to the legacy flat orgValues blob, then to a sentinel string.
+     */
+    buildOrgBlock(context) {
+        if (context.orgIntent) {
+            return formatOrgIntent(context.orgIntent);
+        }
+        if (context.orgValues) {
+            return context.orgValues;
+        }
+        return 'No organizational intent provided.';
+    }
+}
+/**
+ * Render structured org intent into a labeled text block. Constraints first
+ * (most load-bearing), then goals, values, and tradeoff hierarchy. Each bucket
+ * is omitted entirely when empty so the LLM does not see noise.
+ */
+function formatOrgIntent(intent) {
+    const lines = [];
+    lines.push(`Organization: ${intent.name}`);
+    if (intent.constraints.length > 0) {
+        lines.push('');
+        lines.push('CONSTRAINTS (mandatory — violations MUST block):');
+        for (const c of intent.constraints)
+            lines.push(`  - ${c}`);
+    }
+    if (intent.goals.length > 0) {
+        lines.push('');
+        lines.push('GOALS (organizational defaults — contradictions warn or block):');
+        for (const g of intent.goals)
+            lines.push(`  - ${g}`);
+    }
+    if (intent.values.length > 0) {
+        lines.push('');
+        lines.push('VALUES (representation — drift warns):');
+        for (const v of intent.values)
+            lines.push(`  - ${v}`);
+    }
+    if (intent.tradeoffHierarchy.length > 0) {
+        lines.push('');
+        lines.push('TRADEOFF HIERARCHY (earlier wins when two values collide):');
+        intent.tradeoffHierarchy.forEach((t, i) => lines.push(`  ${i + 1}. ${t}`));
+    }
+    return lines.join('\n');
 }
 //# sourceMappingURL=value-alignment.js.map

package/dist/core/reviewers/value-alignment.js.map

@@ -1 +1 @@
-{"version":3,"file":"value-alignment.js","sourceRoot":"","sources":["../../../src/core/reviewers/value-alignment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,MAAM,OAAO,sBAAuB,SAAQ,iBAAiB;IAC3D,YAAY,OAAyB;QACnC,KAAK,CAAC,iBAAiB,EAAE;YACvB,GAAG,OAAO;YACV,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ;SAClC,CAAC,CAAC;IACL,CAAC;IAES,WAAW,CAAC,OAAsB;QAC1C,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAChD,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,0BAA0B,EAAE,CAAC;QAEnD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,2BAA2B,CAAC;QACvE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,0BAA0B,CAAC;QACpE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,oCAAoC,CAAC;QAE5E,OAAO,GAAG,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BjB,aAAa;EAChB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;KACxB,aAAa;;;KAGb,YAAY;EACf,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;KACvB,YAAY;;;KAGZ,WAAW;EACd,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;KACtB,WAAW;;;EAGd,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"value-alignment.js","sourceRoot":"","sources":["../../../src/core/reviewers/value-alignment.ts"],"names":[],"mappings":"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"}

package/dist/scaffold/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/scaffold/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAgG/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2E/F;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiBvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA2B1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,OAAO,EACpB,WAAW,GAAE,OAAe,EAC5B,WAAW,GAAE,OAAe,GAC3B,MAAM,CAmkCR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,OAAO,EACpB,WAAW,GAAE,OAAe,GAC3B,MAAM,CAsQR"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/scaffold/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAgG/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2E/F;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiBvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA2B1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,OAAO,EACpB,WAAW,GAAE,OAAe,EAC5B,WAAW,GAAE,OAAe,GAC3B,MAAM,CAmkCR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,OAAO,EACpB,WAAW,GAAE,OAAe,GAC3B,MAAM,CAsRR"}

package/dist/scaffold/templates.js

@@ -1447,6 +1447,22 @@ Before answering ANY question about my capabilities or architecture from memory
 2. **If result says "block"** — STOP. You may be working on the wrong project for this topic.
 3. **If result says "warn"** — Pause and verify before proceeding.
 
+### ORG-INTENT.md (Organizational Intent at Runtime)
+
+If \`.instar/ORG-INTENT.md\` exists on disk, the Coherence Gate now reads it on every outbound message review and surfaces the three-rule contract to the value-alignment reviewer:
+
+- **Constraints** are mandatory — violations are flagged with severity \`block\` and the message is blocked.
+- **Goals** are organizational defaults — contradictions warn or block (depending on severity).
+- **Values** shape representation — drift warns.
+- **Tradeoff hierarchy** resolves ties when two values pull in opposite directions; the earlier entry wins.
+
+This means: writing an ORG-INTENT.md file actually changes how the agent's outbound messages are evaluated. Before this wiring, the file existed only as input to offline analyzers (\`instar intent validate\`, \`instar intent reflect\`).
+
+Manage it:
+- Scaffold a starter: \`instar intent org-init "Your Org Name"\`
+- Validate agent intent against org intent (static analysis): \`instar intent validate\`
+- Inspect the parsed structure: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/intent/org\`
+
 ## Agent Infrastructure
 
 This project uses instar for persistent agent capabilities.

package/dist/scaffold/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/scaffold/templates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/scaffold/templates.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.21",
+  "version": "1.2.23",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T03:55:48.253Z",
-  "instarVersion": "1.2.21",
+  "generatedAt": "2026-05-22T05:51:10.506Z",
+  "instarVersion": "1.2.23",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1472,7 +1472,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
+      "contentHash": "2f5fd2f22e14901a68a56add8044e3a85347ad3647630bbd0936b678fe79f1f0",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates/jobs/instar/docs-coverage-audit.md

@@ -0,0 +1,36 @@
+---
+name: Docs Coverage Audit
+description: Weekly walk of the instar source tree against the docs surface. Surfaces newly-undocumented capabilities so docs don't drift between releases. Off by default — only useful on machines that have the instar source repo locally (instar developers, contributors). Operators who want it can flip enabled to true in `.instar/jobs/instar/docs-coverage-audit.md`.
+schedule: "0 10 * * 1"
+priority: medium
+expectedDurationMinutes: 5
+model: haiku
+enabled: false
+tags:
+  - cat:learning
+  - audit
+  - instar-dev-only
+toolAllowlist: "*"
+unrestrictedTools: true
+---
+Run a weekly documentation coverage audit on the instar codebase. This job exists because docs drift between releases — features ship without doc updates, and the gap accumulates silently until someone notices. This audit catches the drift early.
+
+The job:
+
+1. Locate the instar source repo on this machine. Try in order: the workspace dir from .instar/config.json under workspace.repoPath; ~/Documents/Projects/instar/; ~/.instar/agents/<self>/.worktrees/ (any subdirectory); or whatever path the operator has configured. If you cannot find the instar repo on this machine, send a short Telegram message saying so and exit — there's no audit to run.
+
+2. Run the coverage script from inside that repo: `node scripts/docs-coverage.mjs --json > /tmp/docs-coverage-this-week.json`. The script enumerates every shipped capability (routes, commands, jobs, hooks, skills, top-level classes per subsystem) and cross-references against site docs + README. It writes both a JSON inventory and a markdown report to .instar/docs-coverage.json and .instar/docs-coverage.md.
+
+3. Compare the new report to last week's. The previous week's report lives at .instar/state/docs-coverage-last-week.json if it exists. Use plain JSON diff logic — what's the delta in undocumented count per category? What capabilities are newly undocumented (existed before but lost their doc mention, or are brand-new in src/ without any doc)? What capabilities became newly documented (good news worth surfacing)?
+
+4. If the delta is interesting (any category gained ≥3 undocumented items OR any single category dropped below its CI floor OR the overall coverage dropped by ≥2 percentage points), send a Telegram message that's a quick, conversational heads-up. Lead with the headline: "Docs coverage dipped in [category]" or "Five new endpoints landed without doc mentions" or similar. Then list the specific items in plain language with their file paths. End with a one-line suggestion of where to add the missing doc (which file in site/src/content/docs/ is the natural home).
+
+5. If the delta is uninteresting (small fluctuations, churn that nets to zero, all categories still above floor), stay silent. Most weeks should be silent — that means the docs are keeping up.
+
+6. After surfacing (or not), save the current report as next week's baseline: copy /tmp/docs-coverage-this-week.json to .instar/state/docs-coverage-last-week.json.
+
+7. Optionally, if the script's --check mode would fail (any category below its CI floor), file a higher-priority signal via the degradation reporter — this is the case where the next PR will hit a CI failure unless someone fixes coverage first.
+
+IMPORTANT: This is a guardian job, not a doer. Surface the drift and where to fix it, don't fix it yourself. The fix work belongs in a deliberate doc-update PR with proper review, not in an autonomous job run. If the drift is large, suggest the operator open a topic to scope the doc update — don't try to enumerate the full backlog in one Telegram message.
+
+Plain English. No raw JSON in the message. No structured field names. The user reads these on their phone. Write like you're texting a teammate about a code-review observation.

package/src/scaffold/templates.ts

@@ -1482,6 +1482,22 @@ Before answering ANY question about my capabilities or architecture from memory
 2. **If result says "block"** — STOP. You may be working on the wrong project for this topic.
 3. **If result says "warn"** — Pause and verify before proceeding.
 
+### ORG-INTENT.md (Organizational Intent at Runtime)
+
+If \`.instar/ORG-INTENT.md\` exists on disk, the Coherence Gate now reads it on every outbound message review and surfaces the three-rule contract to the value-alignment reviewer:
+
+- **Constraints** are mandatory — violations are flagged with severity \`block\` and the message is blocked.
+- **Goals** are organizational defaults — contradictions warn or block (depending on severity).
+- **Values** shape representation — drift warns.
+- **Tradeoff hierarchy** resolves ties when two values pull in opposite directions; the earlier entry wins.
+
+This means: writing an ORG-INTENT.md file actually changes how the agent's outbound messages are evaluated. Before this wiring, the file existed only as input to offline analyzers (\`instar intent validate\`, \`instar intent reflect\`).
+
+Manage it:
+- Scaffold a starter: \`instar intent org-init "Your Org Name"\`
+- Validate agent intent against org intent (static analysis): \`instar intent validate\`
+- Inspect the parsed structure: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/intent/org\`
+
 ## Agent Infrastructure
 
 This project uses instar for persistent agent capabilities.

package/upgrades/1.2.22.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**feat(docs-coverage-weekly): weekly audit job + GitHub Actions cron that surface accumulated docs drift.**
+
+Companion to the per-PR docs coverage gate that shipped in v1.2.21. The per-PR gate catches regression, but coverage can stagnate at the floor indefinitely if every PR just barely scrapes by. This release adds the trend-surface piece: a weekly check that catches accumulated drift even when the per-PR gate is satisfied.
+
+Two delivery surfaces, both light and both off the critical path:
+
+1. **Job template** — `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` ships as an agentmd job, `enabled: false` by default. Instar-developing agents (the ones with the instar source repo on their machine) can flip it to `true` in their local `.instar/jobs/instar/docs-coverage-audit.md`. Once enabled, the job runs every Monday at 10:00 local time, locates the instar source repo, executes the coverage script, compares to the prior week's baseline, and sends a Telegram heads-up if anything drifted in an interesting way. Most weeks stay silent — that means docs are keeping up.
+
+2. **CI workflow** — `.github/workflows/docs-coverage-weekly.yml` runs every Monday at 10:00 UTC against the main branch. Posts the weekly report as a comment on a standing tracking issue tagged `docs-coverage`. Creates the issue on first run; appends weekly thereafter. Provides a durable, GitHub-native ledger of how coverage moves over time.
+
+Both surfaces are signals, not authorities. Neither fixes docs autonomously. The per-PR gate from v1.2.21 remains the authoritative regression check; these surface the trend.
+
+Spec: `docs/specs/docs-coverage-weekly.md`. ELI16: `docs/specs/docs-coverage-weekly.eli16.md`. Side-effects review: `upgrades/side-effects/docs-coverage-weekly.md`.
+
+## What to Tell Your User
+
+Nothing user-visible. The job is off by default and would only apply to agents that develop instar itself. The workflow runs in instar's own GitHub Actions, not the user's.
+
+## Summary of New Capabilities
+
+This release adds a single new job template (off by default) and a single new CI workflow. Both target the instar-developer use case rather than the end-user agent. No new agent runtime behavior.
+
+## Evidence
+
+The coverage script that both surfaces invoke was shipped and tested in v1.2.21. The job template was verified to parse with valid frontmatter. The workflow YAML validates against GitHub Actions schema. Both files were verified to install via existing pipelines: `installBuiltinJobs()` walks the templates directory on every install and update, and the workflow runs from `.github/workflows/` like every other workflow in the repo.

package/upgrades/1.2.23.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new capability (ORG-INTENT runtime gate). Aggregates docs(openclaw-t22) from PR #313 too. -->
+
+## What Changed
+
+**feat(org-intent-runtime): wire `ORG-INTENT.md` into the Coherence Gate so organizational intent actually shapes outbound message review.**
+
+The `ORG-INTENT.md` format, parser, CLI surface (`instar intent org-init`, `validate`, `reflect`), and HTTP routes (`GET /intent/org`, `/intent/validate`) shipped in v0.9.11. What did not ship was the runtime integration — the Coherence Gate that reviews every outbound message only knew about `ORG-INTENT.md` through a deterministic markdown extraction that produced a flat ~150-token blob. The structured three-rule contract (constraints mandatory, goals defaults, values shape, tradeoff hierarchy resolves ties) was invisible to the reviewer. An agent with a fully-authored `ORG-INTENT.md` on disk behaved identically to one without it.
+
+Phase 1 of the org-intent runtime project closes that gap on the message-review surface:
+
+1. **Structured parser wired into the gate.** `loadValueDocs()` now invokes `OrgIntentManager.parse()` and stores the structured `{ name, constraints[], goals[], values[], tradeoffHierarchy[] }` shape alongside the legacy flat blob. Both are surfaced to reviewers; the structured form takes priority.
+2. **Three-rule contract enforced explicitly in the value-alignment reviewer prompt.** The prompt now says constraint violations MUST block; goal contradictions warn or block by severity; value drift warns; the tradeoff hierarchy resolves ties (earlier entry wins). Constraints, goals, values, and tradeoff hierarchy appear in the prompt as separate labeled sections rather than a mashed-up blob.
+3. **Criticality auto-promotion.** When `ORG-INTENT.md` contains constraints, the value-alignment reviewer is auto-promoted to `high` criticality. Timeouts on external channels now fail-closed for this reviewer instead of slipping through unreviewed.
+4. **Migration parity.** Existing agents' CLAUDE.md gains an "ORG-INTENT.md (Organizational Intent at Runtime)" subsection in the Coherence Gate section so the agent learns the file is now load-bearing. The migration is idempotent — re-runs are no-ops.
+
+Spec: `docs/specs/ORG-INTENT-RUNTIME-GATE-SPEC.md`. ELI16 companion: `docs/specs/ORG-INTENT-RUNTIME-GATE-SPEC.eli16.md`. Side-effects review: `upgrades/side-effects/org-intent-runtime-gate.md`.
+
+This is Phase 1 of a four-phase project; the remaining phases (session-start injection, tradeoff helper, drift detection job) are deferred to subsequent releases.
+
+---
+
+**Also included: docs(openclaw-t22) — codex framework limitation documented.**
+
+Spec note added to `docs/specs/OPENCLAW-IMPORT-BEFORE-PROMPT-BUILD-SPEC.md` acknowledging that the pre-prompt memory recall feature (T2.2) only fires on Claude Code sessions. Codex CLI does not expose an equivalent per-prompt hook, so on codex-configured topics the recall pass does not run. This is a documented v1 scope choice surfaced by the 2026-05-21 OpenClaw v1.0 re-audit in topic 9003. The ELI16 companion was updated in plain language so operators understand the limitation before enabling the feature on a codex-configured topic.
+
+## What to Tell Your User
+
+If your agent already has an organizational intent file on disk (ORG-INTENT.md in the .instar directory), this release makes that file actually load-bearing for the first time. The agent's outbound message review now consults the structured constraints, goals, values, and tradeoff hierarchy — and will block messages that violate the constraints you wrote. Review the file before the upgrade lands, because constraints you wrote loosely now have real teeth.
+
+If you have not authored an organizational intent file, behavior is unchanged. This is a zero-cost upgrade for those agents.
+
+A second change in this release (the openclaw-t22 docs note): if you have a Telegram topic configured for the Codex CLI framework, the pre-prompt memory recall feature does not fire on that topic. This is a documented limitation, not a bug.
+
+## Summary of New Capabilities
+
+- **ORG-INTENT.md is now a runtime input to the Coherence Gate.** Three-rule contract enforcement: constraints block, goals warn/block, values warn, tradeoff hierarchy resolves ties.
+- **Value-alignment reviewer prompt** is rewritten to surface the structured contract as separate labeled sections, explicitly enforcing constraint-vs-goal-vs-value semantics.
+- **Migration parity**: existing agents pick up the change automatically via `PostUpdateMigrator.migrateClaudeMd()` — the CLAUDE.md Coherence Gate section gains a new subsection so the agent knows the file is load-bearing.
+- **Three new test suites** added to enforce the wiring at all three tiers (unit, integration, E2E).
+
+## Evidence
+
+- Tier 1 unit tests: `tests/unit/CoherenceGate.test.ts` (5 new tests under the "ORG-INTENT.md structured loading" describe block, all passing). `tests/unit/PostUpdateMigrator-org-intent-runtime.test.ts` (5 new tests for migration parity, all passing).
+- Tier 2 integration tests: `tests/integration/coherence-gate-org-intent.test.ts` (4 tests against the live `/review/evaluate` HTTP route, all passing).
+- Tier 3 E2E lifecycle tests: `tests/e2e/org-intent-runtime-lifecycle.test.ts` (4 tests mirroring production wiring from `src/commands/server.ts`, all passing — including the "feature is alive" check that returns 200, not 503).
+- Type-check: `npx tsc --noEmit` clean.
+- The full test suite must remain green before merge per Zero-Failure Standard.

package/upgrades/side-effects/docs-coverage-weekly.md

@@ -0,0 +1,74 @@
+# Side-effects review — docs-coverage-weekly
+
+Spec: `docs/specs/docs-coverage-weekly.md`
+ELI16: `docs/specs/docs-coverage-weekly.eli16.md`
+Companion to: `docs/specs/docs-coverage.md` (the underlying script + per-PR CI gate)
+
+## Surface map
+
+| Change | File | Type |
+|---|---|---|
+| New job template | `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` | `agentmd` job, `enabled: false` by default. Distributed via `installBuiltinJobs()` on `instar init` and on every update via `PostUpdateMigrator` |
+| New CI workflow | `.github/workflows/docs-coverage-weekly.yml` | GitHub Actions cron workflow, Mondays at 10:00 UTC |
+
+No production code touched. No agent behavior changes at runtime unless an operator explicitly enables the job.
+
+## Over-block analysis
+
+**Could the job spam an operator?**
+
+The job ships `enabled: false`. Operators with the instar source repo on their machine can flip it to `true` in `.instar/jobs/instar/docs-coverage-audit.md`. The job's first action is to locate the instar source repo; if it can't find one, it sends a short message and exits — and the operator can disable the job again. So the worst case is one Telegram message before the operator turns it back off.
+
+When enabled and working correctly, the job stays silent most weeks. The delta thresholds (≥3 newly-undocumented items in a category, any category below CI floor, ≥2-point overall drop) ensure that only meaningful drift surfaces a message.
+
+**Could the CI workflow spam an issue tracker?**
+
+The workflow opens or updates one standing issue tagged `docs-coverage` and appends weekly reports as comments. If the issue is closed by a maintainer (signaling "stop tracking this"), the workflow creates a new one on the next run. This is the desired behavior — closing the issue is the soft way to say "I'm aware, I'll re-engage later." Comments accumulate on a single issue rather than creating a new issue per run.
+
+**Could the CI workflow fail and block other CI?**
+
+No. The workflow is its own job in its own file with no dependencies on other workflows. A failure is visible in the Actions UI but doesn't gate any other PR or push.
+
+## Under-block analysis
+
+**What does the weekly audit NOT catch?**
+
+- Same content-quality limitations as the per-PR coverage check — a documented capability with completely wrong content still counts as documented. The audit catches enumeration drift, not comprehension drift.
+- Doesn't catch capabilities that exist outside the enumerated locations (e.g. an exported class moved to a directory the script doesn't walk). This is a deliberate scope choice; the alternative is walking everything and producing noise.
+- Doesn't catch deleted docs that should still exist (the script measures coverage of what's in code; if code AND docs both lose a capability, neither shows up as drift).
+
+## Level-of-abstraction fit
+
+The job lives in `src/scaffold/templates/jobs/instar/` alongside the other default jobs. The CI workflow lives in `.github/workflows/` alongside other workflows. Both are at the right level: the job is at the agent-behavior layer (something the agent does), and the workflow is at the project-infrastructure layer (something the project does to itself).
+
+The script they both invoke (`scripts/docs-coverage.mjs`) was deliberately built first as a separate concern. This change layers two delivery mechanisms on top of it without modifying the script. If the cadence needs to change (daily, monthly), the script doesn't care.
+
+## Signal-vs-authority compliance
+
+Both surfaces are **signals**. Neither has authority to fail a build or block work. The per-PR coverage check from the docs-coverage spec is the authoritative gate. The weekly job and the weekly workflow are loud heads-ups, but they can't refuse to ship anything. The separation matches how other signal/authority pairs work in instar.
+
+## Interactions with existing systems
+
+- **`installBuiltinJobs()`** — picks up the new `docs-coverage-audit.md` template on every install/update. Existing agents get the template (off by default) on their next update via `PostUpdateMigrator`. No separate migration code needed because `installBuiltinJobs` already overwrites built-in templates idempotently.
+- **Scheduler** — sees the new job. With `enabled: false`, the scheduler reads it on startup but doesn't schedule it for execution. No CPU cost.
+- **GitHub Actions cron** — runs in the same project as other workflows but in its own job and on its own schedule. Doesn't share state with any per-PR workflow.
+- **Telegram adapter** — the job uses the same `telegram-reply.sh` path every other job uses for outbound messages. No new adapter integration.
+- **Docs-coverage script** — invoked via `node scripts/docs-coverage.mjs`. The script is deterministic and idempotent, safe to run repeatedly.
+
+## Rollback cost
+
+Trivially reversible. Remove the two added files. Existing agents lose the template on their next update; the workflow stops running on the next merge.
+
+## Risk summary
+
+- **Low risk of regression.** Pure additions. Job is off by default; workflow runs independently of any other workflow.
+- **Low risk of friction.** Job stays silent most weeks. Workflow posts to one standing issue rather than spraying alerts.
+- **No risk of data loss.** Both surfaces are read-only against the codebase.
+
+## Verification done before commit
+
+- Job template parses correctly (verified via reading frontmatter in test fashion).
+- CI workflow YAML validates against GitHub Actions schema (manual review).
+- The underlying script (shipped in the docs-coverage spec) is already tested and verified — no changes needed.
+- `enabled: false` confirmed in the template so this lands silently for existing agents.
+- Distribution path verified: `installBuiltinJobs()` walks `templates/jobs/instar/` and installs all `.md` files regardless of `enabled` flag, so the file reaches every agent on update; the `enabled: false` controls whether the scheduler runs it.