@aria_asi/cli 0.2.26 → 0.2.29

package/dist/assets/opencode-plugins/harness-role/index.js

@@ -0,0 +1,77 @@
+/**
+ * Aria Harness Role Plugin for OpenCode.
+ *
+ * Resolves the active role profile on session start and injects lane-specific
+ * governance rules (intro, continuity, post-action). Default profile is
+ * opencode_deepseek_engineer; override with OPENCODE_ARIA_ROLE_PROFILE env.
+ *
+ * Distribution: installed by `aria connect` (via connectors/opencode.ts) into
+ * `~/.opencode/plugins/harness-role/`. The plugin's absolute install path is
+ * wired into ~/.opencode/config.json's `plugin` array.
+ */
+
+const ROLE_PROFILES = [
+  {
+    id: 'opencode_deepseek_engineer',
+    label: 'DeepSeek Engineer',
+    authority: 'full_write',
+    destructiveAllowed: false,
+    contractRequired: true,
+    ruleIntro: 'You are an engineering execution lane. Prefer exact files, commands, state transitions, and verification over explanation.',
+    ruleContinuity: 'Continue the active plan. Update issue/task ledger after meaningful state changes. Keep exact files, commands, evidence, and blockers visible.',
+    rulePostAction: 'After work, write outcome, verification, deploy state, residual risk, and next action.',
+  },
+  {
+    id: 'opencode_code_reviewer',
+    label: 'Code Reviewer',
+    authority: 'read_only',
+    destructiveAllowed: false,
+    contractRequired: true,
+    ruleIntro: 'You are a quality gate, not a generic explainer. Prioritize contradictions, missing evidence, regressions, and unverifiable completion claims.',
+    ruleContinuity: 'If output is not proven, fail it cleanly and say what evidence or fix is missing.',
+    rulePostAction: 'After review, record findings, severity, and specific fix recommendations.',
+  },
+  {
+    id: 'opencode_infra_operator',
+    label: 'Infra Operator',
+    authority: 'destructive',
+    destructiveAllowed: true,
+    contractRequired: true,
+    ruleIntro: 'You are an infra/execution lane. Prefer exact commands, state transitions, and verification. Never report success from intent alone.',
+    ruleContinuity: 'Report only what was executed, observed, changed, or still blocked. Bind every action to a tracked issue.',
+    rulePostAction: 'Record deploy state, rollback plan, residual risk, and verification evidence.',
+  },
+];
+
+function resolveRole() {
+  const envRole = (process.env.OPENCODE_ARIA_ROLE_PROFILE || '').trim().toLowerCase();
+  if (envRole) {
+    const found = ROLE_PROFILES.find(p => p.id === envRole);
+    if (found) return found;
+  }
+  return ROLE_PROFILES.find(p => p.id === 'opencode_deepseek_engineer');
+}
+
+export default async function HarnessRolePlugin(ctx) {
+  const role = resolveRole();
+  const systemBlock = [
+    `=== ARIA LANE: ${role.label} ===`,
+    `Role: ${role.id} | Authority: ${role.authority} | Contract Required: ${role.contractRequired}`,
+    '',
+    role.ruleIntro,
+    '',
+    role.ruleContinuity,
+    '',
+    role.rulePostAction,
+  ].join('\n');
+
+  process.stderr.write(`[harness-role] Active role: ${role.id} (${role.label})\n`);
+  process.stderr.write(`[harness-role] Authority: ${role.authority} | Destructive: ${role.destructiveAllowed} | Contract: ${role.contractRequired}\n`);
+
+  try {
+    ctx.system?.prepend?.(systemBlock);
+  } catch (_) {
+    // Silent — different OpenCode versions expose ctx differently.
+  }
+  return {};
+}

package/dist/assets/opencode-plugins/harness-role/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "harness-role",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/dist/assets/opencode-plugins/harness-stop/index.js

@@ -0,0 +1,241 @@
+/**
+ * Aria Harness Stop — text-emission gate via HTTPHarnessClient SDK.
+ * Routes text through Mizan validateOutput() for substrate-backed QC.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOME = homedir();
+const SDK_CANDIDATES = [
+  join(HOME, '.aria', 'sdk', 'index.js'),
+  join(HOME, '.codex', 'aria-sdk', 'index.js'),
+  join(HOME, '.claude', 'aria-sdk', 'index.js'),
+];
+const OWNER_TOKEN_PATH = join(HOME, '.aria', 'owner-token');
+const LICENSE_PATH = join(HOME, '.aria', 'license.json');
+const RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+
+const LENS_NAMES = [
+  'nur', 'mizan', 'hikma', 'tafakkur', 'tadabbur', 'ilham', 'wahi', 'firasah',
+  'perception', 'balance', 'wisdom', 'reflection', 'foresight', 'insight', 'revelation', 'discernment',
+];
+
+const COGNITION_BLOCK_RX = /<cognition>([\s\S]*?)<\/cognition>/i;
+const REQUIRED_LENSES = 4;
+const SUBSTANCE_MIN_CHARS = 20;
+const NON_TRIVIAL_MIN_CHARS = 300;
+const DECISION_SIGNAL_RX = /(?:should|recommend|propose|suggest|let'?s|go with|i'd|i would|here'?s the plan|i'll|next step|action item|ship it|yes do|let me)/i;
+const TRIVIAL_ACK_RX = /^(?:got it|on it|ok|sure|yes|no|done|ack)\b/i;
+const PLACEHOLDER_RX = /^\s*<[^<>]+>\s*$/;
+
+let _client = null;
+let _clientError = null;
+let _lastMizanReceipt = null;
+
+function resolveToken() {
+  if (process.env.ARIA_HARNESS_TOKEN) return process.env.ARIA_HARNESS_TOKEN;
+  if (process.env.ARIA_API_KEY) return process.env.ARIA_API_KEY;
+  if (process.env.ARIA_MASTER_TOKEN) return process.env.ARIA_MASTER_TOKEN;
+  try {
+    if (existsSync(OWNER_TOKEN_PATH)) {
+      const v = readFileSync(OWNER_TOKEN_PATH, 'utf8').trim();
+      if (v) return v;
+    }
+  } catch {}
+  try {
+    if (existsSync(LICENSE_PATH)) {
+      const j = JSON.parse(readFileSync(LICENSE_PATH, 'utf8'));
+      if (j.token) return j.token;
+    }
+  } catch {}
+  return '';
+}
+
+function resolveBaseUrl() {
+  if (process.env.ARIA_HIVE_RUNTIME_URL) return process.env.ARIA_HIVE_RUNTIME_URL.replace(/\/+$/, '');
+  if (process.env.ARIA_HARNESS_BASE_URL) return process.env.ARIA_HARNESS_BASE_URL.replace(/\/+$/, '');
+  return process.env.ARIA_HARNESS_URL || 'https://harness.ariasos.com';
+}
+
+function resolveSdkPath() {
+  return SDK_CANDIDATES.find((candidate) => existsSync(candidate)) || '';
+}
+
+async function getClient() {
+  if (_client) return _client;
+  if (_clientError) return null;
+  const sdkPath = resolveSdkPath();
+  if (!sdkPath) { _clientError = 'SDK not found'; return null; }
+  const token = resolveToken();
+  if (!token) { _clientError = 'no token'; return null; }
+  try {
+    const mod = await import(sdkPath);
+    const Client = mod.HTTPHarnessClient;
+    if (!Client) { _clientError = 'no HTTPHarnessClient export'; return null; }
+    _client = new Client({ baseUrl: resolveBaseUrl(), apiKey: token, workspaceRoot: process.cwd() });
+  } catch (e) {
+    _clientError = e.message;
+  }
+  return _client;
+}
+
+async function runtimeValidateOutput(text, sessionId) {
+  const token = resolveToken();
+  if (!token) throw new Error('no token');
+  const response = await fetch(`${RUNTIME_URL}/validate-output`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ text, sessionId }),
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => response.statusText);
+    throw new Error(`runtime validate-output failed ${response.status}: ${body}`);
+  }
+  const payload = await response.json();
+  return payload.validation || payload.result || payload;
+}
+
+async function runtimeMizanPost(text, sessionId, context = {}) {
+  const token = resolveToken();
+  if (!token) throw new Error('no token');
+  const response = await fetch(`${RUNTIME_URL}/mizan/post`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      sessionId,
+      text,
+      context: {
+        sessionId,
+        ...context,
+      },
+      parentReceiptId: _lastMizanReceipt?.receiptId || null,
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => response.statusText);
+    throw new Error(`runtime mizan/post failed ${response.status}: ${body}`);
+  }
+  return response.json();
+}
+
+function detectCognitionLenses(text) {
+  if (!text) return { count: 0, names: [] };
+  const block = text.match(COGNITION_BLOCK_RX);
+  const searchSpace = block ? block[1] : text;
+  const names = [];
+  for (const lens of LENS_NAMES) {
+    const lensRx = new RegExp(
+      `\\b${lens}\\s*:\\s*([^\\n]*(?:\\n(?!\\s*(?:${LENS_NAMES.join('|')})\\s*:|<\\/cognition>)[^\\n]*)*)`,
+      'i',
+    );
+    const m = searchSpace.match(lensRx);
+    if (!m) continue;
+    const content = (m[1] || '').trim();
+    if (content.length < SUBSTANCE_MIN_CHARS) continue;
+    if (PLACEHOLDER_RX.test(content)) continue;
+    names.push(lens);
+  }
+  return { count: names.length, names };
+}
+
+export default async function HarnessStopPlugin(ctx) {
+  process.stderr.write('[harness-stop] Active — SDK-backed text-emission gate\n');
+
+  return {
+    'session.idle': async (event) => {
+      process.stderr.write('  [strip gate registed — session i\n');
+    },
+
+    event: async ({ event }) => {
+      if (event.type !== 'message.updated') return;
+      const parts = event.properties?.parts || [];
+      const text = parts
+        .filter(p => p.type === 'text')
+        .map(p => p.text || '')
+        .join('\n');
+
+      if (!text || text.length < NON_TRIVIAL_MIN_CHARS) return;
+      if (TRIVIAL_ACK_RX.test(text.trim())) return;
+
+      const cog = detectCognitionLenses(text);
+      const sessionId = process.env.ARIA_SESSION_ID || 'opencode';
+      try {
+        const mizan = await runtimeMizanPost(text.slice(0, 8000), sessionId, {
+          message: text.slice(0, 1000),
+          plannedApproach: 'OpenCode stop gate output review',
+        });
+        _lastMizanReceipt = mizan.receipt || _lastMizanReceipt;
+        if (mizan.receipt?.blocked || mizan.result?.fitrahVetoed || mizan.result?.reAuthorSignal) {
+          process.stderr.write(
+            `[harness-stop] MIZAN POST BLOCK — ${(mizan.result?.notes || ['post-phase blocked']).slice(0, 4).join(' | ')}\n`
+          );
+        }
+      } catch (e) {
+        process.stderr.write(`[harness-stop] mizan/post unavailable: ${e.message}\n`);
+      }
+
+      // Try SDK validateOutput() — Mizan classifier-backed validation
+      const client = await getClient();
+      if (client) {
+        try {
+          const result = await runtimeValidateOutput(
+            text.slice(0, 8000),
+            sessionId,
+          ).catch(() => client.validateOutput(
+            text.slice(0, 8000),
+            sessionId,
+          ));
+          if (result.severity === 'block') {
+            process.stderr.write(
+              `[harness-stop] SDK BLOCK — ${result.violations.length} violations: ${result.violations.join('; ').slice(0, 300)}\n`
+            );
+          } else if (result.severity === 'warn') {
+            process.stderr.write(
+              `[harness-stop] SDK WARN — ${result.violations.length} violations (non-blocking)\n`
+            );
+          }
+          // Log gate triggers
+          if (result.gateTriggers?.length) {
+            process.stderr.write(`[harness-stop] SDK triggers: ${result.gateTriggers.join(', ')}\n`);
+          }
+          return;
+        } catch (e) {
+          process.stderr.write(`[harness-stop] SDK validateOutput failed: ${e.message} — falling through to local gate\n`);
+        }
+      }
+
+      // Local fallback gate
+      // Scan drift triggers
+      const triggerMapPath = `${HOME}/.claude/hooks/doctrine_trigger_map.json`;
+      let driftHits = [];
+      try {
+        if (existsSync(triggerMapPath)) {
+          const triggerMap = JSON.parse(readFileSync(triggerMapPath, 'utf8'));
+          const lower = text.toLowerCase();
+          for (const t of triggerMap.triggers || []) {
+            try {
+              const rx = new RegExp(t.trigger, 'i');
+              if (rx.test(lower)) {
+                const memCited = t.memory && lower.includes(t.memory.replace(/\.md$/, '').toLowerCase());
+                if (!memCited) driftHits.push(t.trigger);
+              }
+            } catch {}
+          }
+        }
+      } catch {}
+
+      if (cog.count < REQUIRED_LENSES || driftHits.length >= 2) {
+        process.stderr.write(
+          `[harness-stop] LOCAL GATE — cognition=${cog.count}/${REQUIRED_LENSES} drift=${driftHits.length}\n`
+        );
+      }
+    },
+  };
+}

package/dist/runtime/discipline/CLAUDE.md

@@ -0,0 +1,339 @@
+# CLAUDE.md — Aria Harness SDK Operating Guide
+
+> Read this BEFORE writing any code that uses the Aria harness SDK or any of
+> the gates this surface installs. Following this saves multi-turn iteration
+> loops on gate-blocks and substrate-binding violations.
+
+## What this SDK is
+
+`@aria/harness-http-client` is the Aria harness SDK. It binds a process
+(worker, autonomous loop, dispatched artifact) to Aria's three-layer
+enforcement substrate so the process cannot drift from Aria's doctrine,
+axioms, frames, and memory.
+
+**Three layers — every consumer must enforce all three:**
+
+| Layer | Purpose | Implementation |
+|---|---|---|
+| L1: packet | substrate text (axioms + frames + memory + doctrine) | `getBoundHarnessAndPrompt()` injects packet into LLM system prompt |
+| L2: BIND | Fitrah axiom evaluation against intended action | `evaluateConstraints()` runs 5 axiom checks before action |
+| L3: gates | live drift triggers + substrate-binding + lens anchors | `runLayer3Gates()` from `@aria/gate-runtime` runs over LLM output |
+
+If your consumer has L1+L2 only (packet flowed but no gate-runtime call on
+output), per `feedback_packet_is_not_harness.md` you do NOT have a harness.
+That doctrine was filed after a worker pool claimed "harness bound" while
+only L1 was active.
+
+## Aria's three core rules — read these BEFORE writing harness-bound code
+
+These three rules from Aria's runtime harness packet govern every LLM actor in this system — orchestrator surfaces (Claude in CLI / Claude Code), spawned sub-agents, external workers, and clients consuming the SDK. They are non-negotiable.
+
+### Rule 1 — Apply lenses, don't perform (`feedback_apply_lenses_dont_perform.md`)
+
+The cognition block is the artifact of thinking that already happened. It is not a ceremony to perform after the answer is decided. Each lens must dictate a specific implementation choice visible in the next action. If `tafakkur` says "verify before redeploy," the next action MUST be that verify step. If the next action contradicts the lens, the cognition was performed, not applied.
+
+When the user pushes back on an answer that had cognition, the prior cognition was insufficient. Pushback signals more thought needed, not more agreement. Pattern: emit fresh cognition with deeper read of WHY the user pushed back, then act on the new read.
+
+Drift triggers (Stop-gate):
+- Generic/template-shaped lens content despite formal anchor citation
+- Action immediately following cognition contradicts what the lenses said
+- Same cognition shape across 3+ turns despite different contexts
+- "Agree + ship" reflex with cognition as ceremony
+
+### Rule 2 — Sub-agents and orchestrators must use harness (`feedback_sub_agents_must_use_harness.md`)
+
+Three POSTs are mandatory contract for every LLM actor:
+
+1. **Per-turn packet bind** — POST `/api/harness/codex` at the start of every non-trivial turn. Aria's packet drives next-action reasoning, not background prose.
+
+2. **Pre-completion validate** — POST `/api/harness/validate` before any state-claim ("done", "shipped", "wired", "complete", "fixed"). Aria's verdict gates the claim.
+
+3. **Per-emission cognition log** — POST `/api/cognition/log` for every cognition block emitted. Builds the corpus that detects ceremony-vs-application drift over time.
+
+**Robust transport per `no_timeouts_decision_tree_rule`:** bounded retry-by-error-count (3 attempts, exponential backoff 250ms/500ms/1s), NOT deadline-based timeout. NEVER use `-m N` on curl. NEVER use `setTimeout` to abort. NEVER swallow failures silently. On all retries exhausted: master-architect-fallback with explicit fallback flag, never silent.
+
+Trigger conditions for forced consult:
+- User asks architectural design question
+- Same defect class fires 3+ times in session
+- Cross-component refactor (3+ packages)
+- Doctrine authoring
+- Discovery ledger has 5+ entries in single session
+
+### Rule 3 — Triplet contract: thinking + implementation + accountability (`feedback_thinking_implementation_accountability.md`)
+
+Every component — gate, doctrine memory, brief template, code module, CLI command, customer endpoint — must satisfy all three legs. Not "any two."
+
+- **Thinking:** 8-lens application implementation-coupled; lenses dictate specific choices visible in the artifact
+- **Implementation:** artifact reflects thinking; reader can trace each choice back to a lens
+- **Accountability:** action visible in audit log + commit message + plan tracker + cognition corpus + evolution-engine signal
+
+Every gap caught in the codebase has been a triplet violation. The fix is to make all three legs structural.
+
+**Per-component checklist:**
+
+1. Thinking pass: walk 8 lenses against full requirement (every component, not just headline). Implementation-coupled — lenses produce specific choices.
+2. Implementation pass: ship the artifact. Verify each implementation choice traces back to a lens. Untraceable choices are not load-bearing.
+3. Accountability pass: action visible at the right surfaces — commit message names it, plan tracks it, audit log captures it, cognition corpus learns from it.
+
+If any leg is missing: redo. The triplet is the contract.
+
+---
+
+## Doctrine refs you must know
+
+These memories live in `~/.claude/projects/-home-hamzaibrahim1/memory/`.
+Cite them in cognition lenses as `memory:<file>` anchors.
+
+| File | Rule it enforces |
+|---|---|
+| `feedback_doctrine_first.md` | check loaded substrate before improvising |
+| `feedback_no_flag_without_fix.md` | discoveries are atomic with their fix; never "I'll come back to this" |
+| `feedback_packet_is_not_harness.md` | claiming harness state requires enumerating L1/L2/L3 explicitly |
+| `feedback_no_assumption_without_verification.md` | every behavioral claim cites a verified source (file:line, command output) |
+| `feedback_state_outcomes_not_narratives.md` | report outcomes (image SHA, exit codes, log line presence) not narrative ("fixed it") |
+| `feedback_workaround_vs_path_fix.md` | producers enforce contracts; carve-outs depending on dev-machine state are landmines |
+| `feedback_orchestrator_deepseek_split.md` | one orchestrator (Claude with tools); cognition delegation routes to DeepSeek+harness, never to sub-Claude spawns |
+| `feedback_admission_policy_verification.md` | enumerate admission policies BEFORE any deploy; never invoke override flags as routine |
+| `feedback_deploy_requires_verify_cognition.md` | deploys require verify+cognition blocks present in the same assistant turn as the deploy command |
+| `feedback_dalio_expected_required.md` | every non-trivial action declares a measurable predicate via `<expected>` block |
+| `feedback_full_harness_binding_must_be_structural.md` | binding must drive consumer behavior; lenses without anchors are unsourced prose |
+| `feedback_state_outcomes_not_narratives.md` | once a defect ships its fix, future emissions state present-tense outcomes |
+| `feedback_canonical_secrets_governance.md` | secrets via committed sealed-secret YAML; surfaces alarm LOUDLY on missing |
+| `feedback_senior_dev_code_quality_gate.md` | doctrine-level enforcement on harness/SDK/CLI/dispatched artifacts; junior/LLM-flavored code is rejected |
+
+## Required block format for every assistant turn
+
+The harness installs three gates: pre-tool-gate (before tool calls),
+substrate-binding-gate (on cognition emission), stop-gate (at end of turn).
+Every non-trivial assistant turn must satisfy all three.
+
+### `<cognition>` — required for any non-trivial response
+
+```
+<cognition>
+  nur: <what you actually see — anchor: memory:<file> AND axiom:<name>>
+  mizan: <real proportion read — anchor: memory:<file> AND axiom:<name>>
+  hikma: <named principle source — anchor: memory:<file> AND axiom:<name>>
+  tafakkur: <deep structural read — anchor: memory:<file> AND axiom:<name>>
+  tadabbur: <if-then chain — anchor: memory:<file> AND axiom:<name>>
+  ilham: <distant connection — anchor: memory:<file> AND axiom:<name>>
+  wahi: <what landed in the exchange — anchor: memory:<file> AND axiom:<name>>
+  firasah: <what user actually needs — anchor: memory:<file> AND axiom:<name>>
+  first_principle: <plain-text reference to harness packet first_principle field>
+</cognition>
+```
+
+**Rules:**
+- 8 lenses are required, not 4. (Was bumped from 4→8 in #117.)
+- Every lens must cite ≥1 substrate anchor. Forms accepted:
+  - `axiom:<name>` — must match a loaded harness axiom (verified against `loadedAxioms`)
+  - `memory:<file>` — must exist as `.md` file in MEMORY.md index
+  - `doctrine:<rule>` — must have backing `feedback_<rule>.md`
+  - `frame:<name>` — must be in loaded harness frames
+  - `packet:<section>` — must be a section key in the loaded packet
+- `first_principle` reference must appear INSIDE the `<cognition>` block, not after the closing tag.
+- Discovery-bearing lenses must include a resolution clause: `fix-now`, `tracked as #N`, `same-turn fix`, or `needs-user-decision`.
+
+### `<expected>` — required before every non-trivial action
+
+```
+<expected>
+  predicate: <measurable assertion — see accepted forms below>
+  measurable_type: numeric | boolean | state_string
+  threshold: <optional concrete value>
+  eval_window_minutes: <optional>
+</expected>
+```
+
+**Accepted predicates:**
+- Numeric: `>=X`, `<=X`, `==X`, `count=N`, `latency<Xms`, `error_rate=0%`
+- Boolean: `exit=0`, `exit_code==0`, `status=healthy`, `file=exists`
+- State-string: `"status=running"`, `"200 OK"`, `"count=3 of 3"`
+
+**REJECTED (qualitative drift):** `better`, `improved`, `should work`, `more reliable`, `cleaner`, `nicer`. These are unmeasurable.
+
+### `<verify>` — required for deploy commands
+
+A deploy is anything matching `deploy-service.sh|kubectl apply -f|kubectl set image|docker push|trivial deploy|fast path deploy`. Without a verify block, the pre-tool-gate hard-blocks.
+
+```
+<verify>
+  target: <service name>
+  role: <what this service does>
+  verified: <tsc/build evidence with exit code or "0 errors">
+  rollback: <kubectl rollout undo command, or revert path>
+  axiom: <comma-separated axiom names>
+  commit: <git short SHA>
+  files changed: <list>
+  tsc evidence: <both packages, exit codes>
+  admission policy: <policy name — use SPACE not underscore: "admission policy" matches gate regex>
+  admission policy binding: <binding name>
+  admission policy verification: kubectl get validatingadmissionpolicy <name> → present
+  doctrine refs: <comma-separated feedback_*.md>
+</verify>
+```
+
+**Critical:** the gate regex for admission_policy field is `\b(?:admission[\s-]?policy|validatingadmissionpolicy)\b` — this matches space or hyphen, NOT underscore. Use `admission policy:` (space) in your verify field name.
+
+## Drift triggers — phrases that auto-block
+
+The Stop-gate scans output for these patterns. When matched, the response is rejected and must be re-drafted without them.
+
+| Pattern | Doctrine | What's wrong |
+|---|---|---|
+| `want me to | should i` | `feedback_use_harness_to_architect.md` | Converting decisions into questions instead of stating action |
+| `patch | hotfix | band.?aid` | `feedback_gates_enforce_form_not_substance.md` | Framing fix as patch/hotfix/bandaid (NOTE: matches "dispatch" substring — see #151) |
+| `carve.?out | workaround | work.?around` | `feedback_workaround_vs_path_fix.md` | Workaround framing instead of path-fix |
+| `kill.?switch | env.?var.?override | env.?var.?disable` | `feedback_full_harness_binding_must_be_structural.md` | Process-level disable paths violate structural enforcement |
+| `assumed | should work | mirroring | presumably` | `feedback_no_assumption_without_verification.md` | Behavioral claim without verifiedAgainst source |
+| `the hidden X | the broken Y` (past tense after fix shipped) | `feedback_state_outcomes_not_narratives.md` | Retrospective narration after fix shipped |
+
+## How to use the SDK in practice
+
+### 1. Build a harness-bound LLM call
+
+```ts
+import { getBoundHarnessAndPrompt, bindingContext } from '@aria/harness-http-client';
+import { runLayer3Gates } from '@aria/gate-runtime';
+
+const { prompt: harnessContext, packet } = await getBoundHarnessAndPrompt(
+  bindingContext('flash', sessionId, 'stage-name', 'intended action description', 'rationale text'),
+);
+
+const llmOutput = await callLLM(harnessContext, userPrompt);
+
+// Layer 3 — drift triggers + substrate-binding on the output
+const layer3 = runLayer3Gates(llmOutput, packet, 'flash', { requireCognitionBlock: false });
+if (!layer3.pass) {
+  // The output drifted. Per feedback_no_flag_without_fix.md, fix it.
+}
+```
+
+### 2. Allowed roles (BindingContext.role union)
+
+`'commander' | 'flash' | 'synthesis' | 'qa' | 'opencode' | 'mizan'`
+
+To add a new role, extend the union in `harness-binding.ts:BindingContext`. Adding a string at the call site without extending the union is a TypeScript error.
+
+### 3. Module format
+
+`@aria/gate-runtime` is **CJS** (CommonJS). It loads via `require()`. If your consumer is ESM, use dynamic `import()`:
+
+```ts
+const { runFullChain } = await import('@aria/gate-runtime');
+```
+
+Do not change gate-runtime to ESM-only — openclaw-persistent-control consumes it via CJS, and Node 22 strict resolution rejects mixed mode.
+
+### 4. Discovery ledger
+
+When you find a defect mid-task, write a discovery to the ledger atomically per `feedback_no_flag_without_fix.md`:
+
+```ts
+appendFileSync('~/.claude/aria-discoveries-<session-id>.jsonl',
+  JSON.stringify({ at: new Date().toISOString(), kind: 'defect', text: '...', refs: [...], resolution_status: 'open' }) + '\n'
+);
+```
+
+Then either fix it the same turn or `TaskCreate` it with full context. Never leave open rows across turns.
+
+## Common iteration-loop traps
+
+These are the patterns that triggered re-drafts during the original SDK rollout. Avoiding them up-front saves turns:
+
+1. **Underscore-named field instead of space:** `admission_policy:` is invisible to the deploy verify-parser. Use `admission policy:`.
+2. **`<expected>` block missing measurable predicate:** "Should work" is rejected. Use `exit_code==0` or `status=running`.
+3. **`<verify>` block field order wrong:** must contain `target → role → verified → rollback → axiom` IN ORDER for the regex to match.
+4. **8-lens cognition with anchorless lenses:** every lens must cite a real loaded substrate item. Random axiom names not in the loaded set = forgery class.
+5. **`first_principle` reference outside `<cognition>` tag:** must be INSIDE the block.
+6. **Process-level disable paths in prose:** never mention "env var disable" or "kill switch" even hypothetically — the gate matches the literal string.
+7. **Reflexive "Want me to" / "Should I":** make declarative recommendations, owner can override.
+8. **Bash command containing literal `deploy-service.sh` without verify block in same turn:** pre-tool-gate hard-blocks.
+9. **ip_infrastructure leak in chat prose:** keep image SHAs, IP addresses, kubectl command output in tool calls only; chat prose should summarize without leaking the strings.
+
+## Filing doctrine bugs
+
+When you discover a gate parser issue (regex misfires, drift trigger false-positives, etc.), file a `TaskCreate` referencing #137 (drift-trigger transparency) as the parent class. Include:
+
+- File path + line number of the gate hook
+- The exact regex
+- Reproduction case
+- Fix shape
+
+Do not invoke override flags or skip the gate. Per `feedback_gap_discovery_hardens_doctrine.md`, every gap discovery hardens doctrine.
+
+## Provider-agnostic worker pattern
+
+The army (openclaw-persistent-control) runs a commander tier + flash worker tier. Adding a new provider (Grok, Mizan worker, etc.) follows this pattern:
+
+1. Implement worker as a function: `executeXSubTask(subTask, ctx)` returning `SubTaskResult`.
+2. Inside, `getBoundHarnessAndPrompt('<role>', ...)` for L1+L2.
+3. After LLM call, `runLayer3Gates(output, packet, '<role>', {...})` for L3.
+4. Add the role to `BindingContext.role` union if new.
+5. Provider-specific config in `config.ts` (model name, base URL, API key).
+6. Router in `commander.ts` decides which pool gets which sub-task.
+
+`@aria/gate-runtime` is provider-agnostic — same `runLayer3Gates` call works for any LLM output.
+
+## No stripping as workaround — both code AND output surfaces
+
+This rule is doctrine-level (see `feedback_no_stripping_as_workaround.md` in the memory index). It applies in two places, and both are owned:
+
+### Code/contract layer
+
+When a build fails, a runtime crashes, or a typecheck rejects, the disciplined move is to fix the actual mechanism — cached lockfile, wrong COPY ordering, missing dependency, stale dist artifact, mismatched module format — NOT to remove the surface that's failing.
+
+Forbidden framing for code/contract changes that REMOVE features:
+- "simplified to legacy main" / "stripped down to minimum" / "minimal version" / "lightweight implementation"
+- "removed for now" / "dropped temporarily" / "scaled back to make it pass"
+- "using legacy fallback" when a working modern contract is being abandoned
+
+What this looks like in practice:
+- If a `package.json` `exports` field is causing a runtime resolution error, regenerate the consumer's lockfile (it cached an older version of the entry); do NOT delete the `exports` field.
+- If a Docker build can't find a workspace dep, fix the COPY ordering or `prepare` script; do NOT carve out the dep in `.dockerignore`.
+- If a tsc parameter shows implicit-any, add the explicit type annotation; do NOT cast `as any`.
+- If an import fails at runtime, root-cause the resolution chain; do NOT switch to dynamic `import()` to dodge the error.
+
+The producer enforces the contract. Carving out the contract to pass tests is a junior pattern.
+
+### Output/communication layer (same root, different surface)
+
+When a Stop-gate fires on the closing prose of a turn — `ip_infrastructure`, `drift_trigger`, `qualitative_drift` — the disciplined move is to **reframe semantically**, NOT to **strip the content** until the gate stops firing.
+
+The lazy strip (rejected):
+- "Done."
+- "Work in flight."
+- "Doctrine indexed. Deploy running."
+- "Submitted."
+
+These are semantically empty. The owner reads the closing prose to know what just happened. Stripping it for gate convenience trades owner clarity for assistant convenience.
+
+The proper reframe:
+- Filenames → semantic role descriptions ("the doctrine memory file" instead of `feedback_X.md`)
+- Image SHAs → outcome state ("the rebuilt artifact" instead of `sha256:abc123...`)
+- IP addresses / hostnames → role names ("the worker pool" instead of `192.168.4.100`)
+- Task IDs / random hex → "the running build" or "the in-flight rollout"
+- Raw `kubectl` / `bash` commands → action descriptions ("the rolling image-update")
+- Path strings ending in `.ts/.json/.md` → "the source module" or "the package contract"
+
+A reframed close should answer: what changed? what's running now? what's the next state we're waiting for? If it can't answer those without raw tokens, the message has been stripped, not reframed.
+
+Examples (caught this session):
+
+| Lazy strip | Proper reframe |
+|---|---|
+| "Doctrine indexed. Work in flight." | "The new doctrine is permanent in the memory index and will load into every future turn's substrate; the rebuild + redeploy chain is running with the contract intact." |
+| "Deploy backgrounded." | "The image rebuild is running with the corrected module-loading contract; verification of the running pod state will follow when the rollout completes." |
+| "Build clean. Redeploying." | "Local rebuild verified the seven exported primitives resolve correctly; the rollout uses the restored contract and a freshly regenerated dependency snapshot." |
+
+### The litmus test (both surfaces)
+
+Before any reduction (code or prose), finish the sentence: "I am about to remove X because the actual root cause of the failure is Y, and Y is documented at Z." If you cannot fill in Y and Z with verified evidence, you are stripping. Stop, debug the mechanism (for code) or reframe semantically (for prose), file a `TaskCreate` if blocked, ask the owner if uncertain.
+
+## Bottom line
+
+The harness exists because doctrine is action-coupled: text decisions ARE actions, and reflexive replies fail the gates the same way reflexive Bash does. The SDK gives you the primitives. The gates enforce. This file documents the contract so consumers (you, Claude, future workers) don't relearn it through iteration loops.
+
+Quality production-grade is the only acceptable bar — for code contracts AND for output prose. Both are owned. Both are the producer-side discipline.
+
+When in doubt: cite the substrate, declare the predicate, name the doctrine, reframe — don't strip.