@ngockhoale/ukit 3.4.45 → 3.4.47

package/CHANGELOG.md

@@ -2,12 +2,21 @@
 
 All notable changes to UKit are documented here.
 
-## Unreleased
-
-**`/ukit:ci-check`: manual-only cross-platform CI (not yet released; no version bump).**
-- `cross-platform-ci.yml` is now `workflow_dispatch` only (push trigger removed). No push/pull_request/schedule/workflow_run path can start CI.
-- New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
-- Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
+## 3.4.47 - 2026-10-18
+
+**Supervisor subagent usage attribution and rendered-instruction parity checks.**
+- Record subagent usage at the supervisor's terminal completion/cancellation boundary, using typed operation metadata and existing exactly-once guards. Provider-authenticated usage remains blocked; host transcript values are not relabeled as provider data.
+- Add read-only `render-instructions.mjs --parity` to byte-compare rendered root instructions with existing root files, including fixture-target support and drift diagnostics.
+- Add manual-only `/ukit:ci-check` cross-platform CI tooling; it remains opt-in and never pushes, merges, or publishes.
+- Locally verified on macOS/Node 22. Q-C98-1 and Q-C98-3 remain blocked on provider-authenticated data/privacy approval; no provider identity/pricing/cache model is claimed.
+## 3.4.46 - 2026-10-18
+
+**Completion contract P0: forensic intent, attributable release evidence and conditional NO-GO.**
+- Correct negated/quoted forensic requests and Vietnamese status questions; explicit report artifacts require owned writes and nonempty output. External scratch writes do not count as product changes.
+- Conditional release contracts with a named `release:verify` preflight accept only current-task attributable native failure as terminal `RELEASE_NO_GO`, never publication success. Missing implementation writes still block; passing preflight retains publication obligations. Masked commands and stale receipts remain unproven.
+- Accept standalone `npm view <package> version --prefer-online` evidence without republishing; improve task/obligation diagnostics. OMP artifact checks use the installed project cwd.
+- Exclude only repository coverage/transcript audit scripts from npm; retain runtime and customer assets and the strict artifact budget.
+- Verified locally on macOS/Node 22 with real isolated OMP child-hook chains; no provider calls or GitHub Actions dispatch. Historical release ledger replay remains partial; OMP mid-task freeze remains open. UNIC Decision stays unchanged/off.
 
 ## 3.4.45 - 2026-10-17
 

package/manifests/documentation.yaml

@@ -955,6 +955,18 @@ entries:
     archive_policy: never
     notes: C69 G7 operator doc — timeline render, support bundle contents/exclusions, replay limits
 
+  - id: docs-completion-decision-assessment
+    path: docs/COMPLETION_DECISION_ASSESSMENT.md
+    class: canonical
+    audience: [maintainer]
+    owner: runtime
+    source_of_truth: docs/COMPLETION_DECISION_ASSESSMENT.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: P0 completion contract corrections and offline semantic decision architecture assessment
+
   - id: docs-unic-decision-integration-p1-fix
     path: docs/UNIC-DECISION-INTEGRATION-P1-FIX.md
     class: canonical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.45",
+  "version": "3.4.47",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,8 @@
     "!scripts/audit/c100/implementer-attribution.mjs",
     "!scripts/audit/c100/trees-lifetimes.mjs",
     "!scripts/audit/c100/usage-provenance.mjs",
+    "!scripts/audit/decision-coverage.mjs",
+    "!scripts/audit/subagent-cost/**",
     "template_project/",
     "template_user/",
     "!template_project/**/.smbdelete*",

package/scripts/dev/capture-omp-stall.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// One-shot development capture. Every subprocess is bounded; OMP is never signalled or modified.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readBoundedTail, summarizeSessionTail, buildStallSnapshot, associateSessionEvidence, classifySessionActivity, parseProcessInventory, processInventoryCommand, parseOwnerPids, runBoundedProcess } from '../../src/diagnostics/ompStallSnapshot.js';
+const ownPath = fileURLToPath(import.meta.url);
+const args = process.argv.slice(2);
+const option = (key) => { const at = args.indexOf(key); return at < 0 ? null : args[at + 1]; };
+const worker = process.env.UKIT_STALL_CAPTURE_WORKER === '1';
+
+if (!worker) {
+  const child = spawn(process.execPath, [ownPath, '--worker', ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, UKIT_STALL_CAPTURE_WORKER: '1' } });
+  let output = '';
+  let failed = false;
+  const timer = setTimeout(() => { failed = true; child.kill('SIGKILL'); }, 5000);
+  child.stdout.on('data', (chunk) => {
+    output += chunk;
+    if (Buffer.byteLength(output) > 131072) { failed = true; child.kill('SIGKILL'); }
+  });
+  child.on('error', () => { clearTimeout(timer); console.error('Capture unavailable'); process.exitCode = 1; });
+  child.on('close', async (code) => {
+    clearTimeout(timer);
+    if (code !== 0 || failed) { console.error('Capture incomplete: collector deadline or bounded I/O failure; OMP untouched.'); process.exitCode = 1; return; }
+    try {
+      const report = JSON.parse(output);
+      const dir = path.resolve(option('--output-dir') || path.join(os.tmpdir(), 'ukit-stall-captures'));
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const dirStat = await fs.lstat(dir);
+      if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) throw new Error('unsafe output directory');
+      await fs.chmod(dir, 0o700);
+      let file = null;
+      let handle = null;
+      const startSlot = Date.now() % 8;
+      for (let attempt = 0; attempt < 8 && !file; attempt += 1) {
+        const slot = (startSlot + attempt) % 8;
+        const candidate = path.join(dir, `snapshot-${slot}.json`);
+        try {
+          const existing = await fs.lstat(candidate);
+          if (!existing.isFile() || existing.isSymbolicLink()) continue;
+          await fs.unlink(candidate);
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        file = candidate;
+        const temporary = path.join(dir, `snapshot-${slot}-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`);
+        try {
+          handle = await fs.open(temporary, 'wx', 0o600);
+          await handle.chmod(0o600);
+          await handle.writeFile(`${JSON.stringify(report, null, 2)}\n`);
+          await handle.close();
+          handle = null;
+          await fs.rename(temporary, file);
+        } catch (error) {
+          if (handle) await handle.close();
+          await fs.unlink(temporary).catch(() => {});
+          file = null;
+          if (attempt === 7) throw error;
+        }
+      }
+      if (!file) throw new Error('no safe snapshot slot available');
+      console.log(`${report.captureStatus} — snapshot saved: ${file}`);
+    } catch {
+      console.error('Capture incomplete: private snapshot could not be saved; OMP untouched.');
+      process.exitCode = 1;
+    }
+  });
+} else {
+  const maxSessions = 32;
+  const maxLogs = 8;
+  const home = option('--omp-home') || path.join(os.homedir(), '.omp');
+  const sessionsRoot = option('--sessions-root') || path.join(home, 'agent', 'sessions');
+  const ownersRoot = option('--owners-root') || path.join(home, 'run', 'session-owners');
+  const logsRoot = option('--logs-root') || path.join(home, 'logs');
+  const explicitSession = option('--session');
+  const packageInfo = JSON.parse(await fs.readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+
+  async function discoverTranscripts(root) {
+    const candidates = [];
+    let truncated = false;
+    try {
+      const rootDir = await fs.opendir(root);
+      let visited = 0;
+      for await (const entry of rootDir) {
+        if (++visited > 128) { truncated = true; break; }
+        if (entry.isFile() && entry.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name));
+        if (!entry.isDirectory()) continue;
+        let childCount = 0;
+        try {
+          const childDir = await fs.opendir(path.join(root, entry.name));
+          for await (const child of childDir) {
+            if (++childCount > 128 || candidates.length >= maxSessions) { truncated = true; break; }
+            if (child.isFile() && child.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name, child.name));
+          }
+        } catch { truncated = true; }
+        if (candidates.length >= maxSessions) { truncated = true; break; }
+      }
+      return { state: 'OBSERVED', paths: candidates.slice(0, maxSessions), truncated };
+    } catch { return { state: 'NOT_OBSERVABLE', paths: [], truncated: true }; }
+  }
+
+  async function discoverOwnerIds(root) {
+    try {
+      const dir = await fs.opendir(root);
+      const ids = [];
+      let visited = 0;
+      let truncated = false;
+      for await (const entry of dir) {
+        if (++visited > 128) { truncated = true; break; }
+        if (!entry.isFile() || !entry.name.endsWith('.lock')) continue;
+        const sessionId = entry.name.slice(0, -5);
+        if (/^[\w.-]{1,120}$/.test(sessionId)) ids.push(sessionId);
+        if (ids.length >= maxSessions) { truncated = true; break; }
+      }
+      return { state: 'OBSERVED', ids, truncated };
+    } catch { return { state: 'NOT_OBSERVABLE', ids: [], truncated: true }; }
+  }
+
+  async function runBounded(command, commandArgs, timeout = 650) {
+    return runBoundedProcess(command, commandArgs, { timeoutMs: timeout, maxBuffer: 65536 });
+  }
+
+
+  async function probeOwnerLock(sessionId, rootExists) {
+    if (!rootExists || !/^[\w.-]{1,120}$/.test(sessionId)) return { state: 'NOT_OBSERVABLE', pids: [] };
+    const file = path.join(ownersRoot, `${sessionId}.lock`);
+    try {
+      const stat = await fs.lstat(file);
+      if (!stat.isFile()) return { state: 'NOT_OBSERVABLE', pids: [] };
+    } catch (error) {
+      return error.code === 'ENOENT' ? { state: 'UNHELD', pids: [] } : { state: 'NOT_OBSERVABLE', pids: [] };
+    }
+    if (process.platform === 'win32') {
+      const handles = await runBounded('handle.exe', ['-nobanner', file], 400);
+      if (!handles.ok) return { state: 'NOT_OBSERVABLE', pids: [] };
+      const expected = path.resolve(file).replaceAll('/', '\\').toLowerCase();
+      const matches = handles.stdout.split(/\r?\n/).flatMap((line) => {
+        const match = line.match(/\bpid:\s*(\d+)\s+type:\s*File\b.*?:\s*(.+)$/i);
+        if (!match || match[2].trim().replaceAll('/', '\\').toLowerCase() !== expected) return [];
+        return [Number(match[1])];
+      });
+      const pids = [...new Set(matches)];
+      return pids.length === 1 ? { state: 'OBSERVED', pids } : { state: 'NOT_OBSERVABLE', pids: [] };
+    }
+    const lsof = await runBounded('lsof', ['-t', '--', file], 250);
+    if (lsof.ok) return { state: 'OBSERVED', pids: parseOwnerPids('lsof', lsof.stdout) };
+    if (lsof.exitCode === 1) return /permission|denied|error/i.test(lsof.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
+    if (lsof.errorCode !== 'ENOENT') return { state: 'NOT_OBSERVABLE', pids: [] };
+    const fuser = await runBounded('fuser', ['-f', file], 250);
+    if (fuser.ok) return { state: 'OBSERVED', pids: parseOwnerPids('fuser', `${fuser.stdout}\n${fuser.stderr}`) };
+    if (fuser.exitCode === 1) return /permission|denied|error/i.test(fuser.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
+    return { state: 'NOT_OBSERVABLE', pids: [] };
+  }
+
+
+  async function readProcessInventory() {
+    const [command, commandArgs] = processInventoryCommand(process.platform);
+    const result = await runBounded(command, commandArgs);
+    if (!result.ok) return { state: 'NOT_OBSERVABLE', processes: [], ompProcessCount: null };
+    const processes = parseProcessInventory(process.platform, result.stdout);
+    return { state: 'OBSERVED', processes, ompProcessCount: processes.filter((entry) => /^omp(?:\.exe)?$/i.test(entry.name)).length };
+  }
+
+  async function readOmpLog(pid) {
+    try {
+      const names = [];
+      const directory = await fs.opendir(logsRoot);
+      let visited = 0;
+      for await (const entry of directory) {
+        if (++visited > 256) break;
+        if (entry.isFile() && new RegExp(`^omp\\.\\d{4}-\\d{2}-\\d{2}\\.${pid}\\.log$`).test(entry.name)) names.push(entry.name);
+      }
+      names.sort();
+      const name = names.at(-1);
+      if (!name) return null;
+      const tail = await readBoundedTail(path.join(logsRoot, name), { maxBytes: 32768 });
+      const rows = [];
+      for (const line of tail.text.split('\n')) {
+        try {
+          const row = JSON.parse(line);
+          // Never copy message text, URLs, account fields, headers or response bodies.
+          const timestamp = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? new Date(row.timestamp).toISOString() : null;
+          rows.push({ timestamp,
+            level: ['debug', 'info', 'warn', 'error'].includes(row.level) ? row.level : null,
+            status: Number.isInteger(row.status) ? row.status : null });
+        } catch { /* Partial log row. */ }
+      }
+      return { pid, bytesRead: tail.bytesRead, rows: rows.slice(-16) };
+    } catch { return null; }
+  }
+
+  let discovery;
+  if (explicitSession) discovery = { state: 'OBSERVED', paths: [explicitSession] };
+  else discovery = await discoverTranscripts(sessionsRoot);
+  const transcriptSessions = [];
+  for (const transcriptPath of discovery.paths.slice(0, maxSessions)) {
+    try {
+      const tail = await readBoundedTail(transcriptPath);
+      const summary = summarizeSessionTail(tail.text);
+      const filenameId = path.basename(transcriptPath).replace(/\.jsonl$/i, '');
+      const uuidFromFilename = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(filenameId) ? filenameId : null;
+      const sessionId = summary.sessionId || uuidFromFilename;
+      const summarySessionId = summary.sessionId;
+      summary.sessionId = sessionId;
+      transcriptSessions.push({ sessionId, transcriptPath, summary, sourceCoverage: { sessionTailBytes: tail.bytesRead, truncated: tail.truncated, sessionIdentityObserved: summarySessionId !== null || uuidFromFilename !== null } });
+    } catch { transcriptSessions.push({ sessionId: null, transcriptPath, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } }); }
+  }
+  const ownerDiscovery = await discoverOwnerIds(ownersRoot);
+  const sessions = [...transcriptSessions];
+  for (const sessionId of ownerDiscovery.ids) if (!sessions.some((entry) => entry.sessionId === sessionId)) sessions.push({ sessionId, transcriptPath: null, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } });
+  const boundedSessions = sessions.slice(0, maxSessions);
+  const ownerRootExists = ownerDiscovery.state === 'OBSERVED';
+  const [ownerResults, processInventory] = await Promise.all([
+    Promise.all(boundedSessions.filter((entry) => entry.sessionId).map(async (entry) => [entry.sessionId, await probeOwnerLock(entry.sessionId, ownerRootExists)])),
+    readProcessInventory(),
+  ]);
+  const ownerLocks = Object.fromEntries(ownerResults);
+  const logs = (await Promise.all([...new Set(ownerResults.flatMap(([, lock]) => lock.state === 'OBSERVED' ? lock.pids : []))].slice(0, maxLogs).map(readOmpLog))).filter(Boolean);
+  const associations = associateSessionEvidence({ sessions: boundedSessions, ownerLocks, processInventory, logs });
+  const snapshots = associations.map((association, index) => {
+    const source = boundedSessions[index];
+    const summary = source.summary;
+    const sessionActivity = classifySessionActivity({ association: association.sessionAssociation, summary });
+    return { ...association, sessionActivity, ...(summary || {}), sourceCoverage: source.sourceCoverage };
+  });
+  const activeOwners = snapshots.filter((entry) => entry.sessionAssociation === 'ACTIVE_OWNER');
+  const allLocksUnheld = ownerResults.length === boundedSessions.filter((entry) => entry.sessionId).length
+    && ownerResults.every(([, lock]) => lock.state === 'UNHELD');
+  const coverageComplete = !discovery.truncated && !ownerDiscovery.truncated && sessions.length <= maxSessions;
+  const transcriptsFullyIdentified = transcriptSessions.every((entry) => entry.sessionId !== null);
+  const executionState = activeOwners.length ? 'EXECUTING'
+    : coverageComplete && transcriptsFullyIdentified && ownerDiscovery.state === 'OBSERVED' && processInventory.state === 'OBSERVED'
+      && processInventory.ompProcessCount === 0 && allLocksUnheld ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
+  const activity = activeOwners.length === 1 ? activeOwners[0].sessionActivity
+    : activeOwners.length > 1 ? 'MULTIPLE_ACTIVE_SESSIONS' : executionState === 'NO_EXECUTION' ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
+  const captureStatus = activeOwners.length > 0 && activeOwners.every((entry) => entry.sourceCoverage && entry.summary)
+    && discovery.state === 'OBSERVED' && !discovery.truncated && ownerDiscovery.state === 'OBSERVED' && !ownerDiscovery.truncated
+    && processInventory.state === 'OBSERVED' && ownerResults.every(([, lock]) => lock.state === 'OBSERVED' || lock.state === 'UNHELD')
+    && snapshots.every((entry) => entry.sessionId !== null && entry.identityVerified) ? 'CAPTURE_READY' : 'CAPTURE_PARTIAL';
+  const snapshot = buildStallSnapshot({ executionState, activity, captureStatus,
+    sessionDiscovery: discovery.state, ownerLockDiscovery: ownerDiscovery.state,
+    processInventory: { state: processInventory.state, ompProcessCount: processInventory.ompProcessCount },
+    sessions: snapshots, ompVersion: 'NOT_OBSERVABLE', ukitVersion: packageInfo.version,
+    limitations: ['Persisted transcript events do not prove live stream or gateway state.', 'Unobservable ownership and operation states remain NOT_OBSERVABLE.', 'No OMP freeze root cause is inferred.'] });
+  process.stdout.write(JSON.stringify(snapshot) + '\n');
+}

package/scripts/docs/render-instructions.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 // DOC-102 renderer CLI (SPEC §8.2).
 //   node scripts/docs/render-instructions.mjs --write   (default) regenerate all outputs
-//   node scripts/docs/render-instructions.mjs --check   print DRIFT <path> per mismatch, exit 1
+//   node scripts/docs/render-instructions.mjs --parity  check installed root instructions read-only
+// `--parity` takes precedence over `--check`/`--write`; `--parity-root` overrides only the
+// comparison target directory for fixture/testing use, never the source/layout root.
 import path from 'node:path';
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -12,18 +15,39 @@ import {
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
-const USAGE = 'usage: render-instructions.mjs [--write|--check]';
 
+const USAGE = 'usage: render-instructions.mjs [--write|--check|--parity] [--parity-root <dir>]';
 const args = process.argv.slice(2);
-const unknown = args.filter((a) => a !== '--write' && a !== '--check');
-if (unknown.length > 0) {
-  console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
+const parityRootArg = args.indexOf('--parity-root');
+const parityRoot = parityRootArg === -1 ? repoRoot : path.resolve(args[parityRootArg + 1] || '');
+const unknown = args.filter((a, i) => a !== '--write' && a !== '--check' && a !== '--parity'
+  && a !== '--parity-root' && !(parityRootArg !== -1 && i === parityRootArg + 1));
+if (unknown.length > 0 || (parityRootArg !== -1 && !args[parityRootArg + 1])) {
+  console.error(`${USAGE}\nunknown flag or missing value: ${unknown[0] || '--parity-root'}`);
+  process.exit(2);
+}
+if (parityRootArg !== -1 && !args.includes('--parity')) {
+  console.error(`${USAGE}\n--parity-root requires --parity`);
   process.exit(2);
 }
 
 const mode = args.includes('--check') ? 'check' : 'write';
+const parity = args.includes('--parity');
 
 try {
+  if (parity) {
+    const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
+    const targets = [...rendered].filter(([target]) => target === 'CLAUDE.md' || target === 'AGENTS.md');
+    const drift = targets.filter(([target, content]) => {
+      const file = path.join(parityRoot, target);
+      return !fs.existsSync(file) || !fs.readFileSync(file).equals(Buffer.from(content));
+    });
+    for (const [target] of drift) console.log(`DRIFT ${target}`);
+    if (drift.length > 0) process.exit(1);
+    console.log(`PARITY OK ${targets.length} files`);
+    process.exit(0);
+  }
+
   if (mode === 'check') {
     const drift = await checkRenderedInstructions({ repoRoot });
     for (const target of drift) {

package/src/core/agentRuntime/supervisor.js

@@ -47,8 +47,8 @@ import {
   durationMs,
   reasonCodeForFailure,
   projectRootFromRuntimeDir,
+  recordSubagentUsage,
 } from './telemetry.js';
-
 const SUPERVISOR_FLAG = 'decisionRuntime.supervisor.stage';
 // G6 (DR-09): `decisionRuntime.promotion.stage` — absent/malformed → 'off';
 // 'shadow' consults selectWaitPolicy at the caller-wait decision and records a
@@ -396,6 +396,13 @@ export function createSupervisor(opts = {}) {
             errorCode: reasonCodeForFailure({ cancelReason: op.cancelReason ?? 'cancel_requested' }),
             exitCode: op.exitInfo?.code,
           });
+          if (op.spansClosed) {
+            recordSubagentUsage(telemetry, op.telemetryCtx, {
+              components: op.spec?.subagentUsage?.components,
+              parentRunId: op.spec?.parentRunId,
+              usage: op.spec?.subagentUsage?.usage,
+            });
+          }
         });
       }
     }, limits.killGraceMs));
@@ -521,6 +528,13 @@ export function createSupervisor(opts = {}) {
         exitCode: op.exitInfo?.code,
       });
     }
+    if (op.spansClosed) {
+      recordSubagentUsage(telemetry, op.telemetryCtx, {
+        components: op.spec?.subagentUsage?.components,
+        parentRunId: op.spec?.parentRunId,
+        usage: op.spec?.subagentUsage?.usage,
+      });
+    }
   }
 
   function onExit(op, code, signal) {

package/src/core/executionContracts.js

@@ -194,25 +194,39 @@ function nativeOperationGoal(domain, actionable, text) {
 // FIRST item of an enumeration ("Do not implement fixes, modify source code, restart services, ...") and
 // the later items became actionable orders (MIXED + service-runtime). English negators now scope to the
 // sentence end (', and'/', or' continue the list; a bare 'and <verb>' or but/then starts a new clause);
-// Vietnamese negators stay clause-local. Noun uses of verbs ("write/verification advisory", "each proposed
+// Vietnamese negators scope to the sentence end as well. Noun uses of verbs ("write/verification advisory", "each proposed
 // fix", "state change") name things, not orders. Neutralised spans become blanks, never new orders.
 const NON_ORDER_VERBS = 'implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|restart|sua|viet|chinh|them|tao|xoa';
 function neutralizeNonOrders(text) {
   return String(text)
     .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|shall\\s+not)\\s+[^.;\\n]*?(?=(?<!,)\\s+(?:and|va)\\s+(?:${NON_ORDER_VERBS})\\b|\\s+(?:but|nhung|then|however)\\b|[.;\\n]|$)`, 'g'), ' ')
+    .replace(new RegExp(`\\b(?:khong|chua)\\s+[^.;\\n]*?(?=\\s+(?:nhung|tuy nhien)\\b|[.;\\n]|$)`, 'g'), ' ')
+    .replace(/"[^"\n]*\s[^"\n]*"|`[^`\n]*\s[^`\n]*`|\u201c[^\u201d\n]*\u201d/g, ' ')
+    .replace(/\b(?:neu\s+(?:phai|can|thieu|khong du|bang chung chua du)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
+    .replace(/[^.;\n]*\b(?:nao|gi|sao|the nao|bao nhieu)\b[^.;\n]*\?/g, ' ')
+    .replace(/\bchinh\s+xac\b|\b(?:phuong an|cach|de xuat|ban)\s+(?:sua|fix)\b/g, ' ')
     .replace(/\bwrite\s*\/\s*verification\b|\bverification\s*\/\s*write\b|\bwrite\s+(?:or|and)\s+verification\b/g, ' ')
     .replace(/\b(?:state|status)\s+changes?\b/g, ' ')
     .replace(/\b(?:proposed|suggested|recommended|minimal|each|the|an?|any|that|this|no|which|exact|smallest|possible)\s+fix(?:es)?\b/g, ' ');
 }
 
 export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {}) {
-  const text = neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/đ/g, 'd').toLowerCase());
+  // A named preflight and both explicit branches are required; a failed arbitrary test is not a release policy.
+  const releaseText = String(promptText).normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[đĐ]/g, 'd').toLowerCase();
+  const preflight = releaseText.match(/\b(?:yarn\s+release:verify|npm\s+run\s+release:verify)\b/)?.[0];
+  const releasePolicy = preflight && /\b(?:if|neu|only when|only if)\b[^\n.;]*(?:pass|go)\b[^\n.;]*(?:release|publish)\b/.test(releaseText)
+    && /\b(?:fail|no-go)\b[^\n.;]*(?:do not publish|don't publish|no publish|khong publish|khong npm publish)\b/.test(releaseText)
+    ? { kind: 'conditional-release', preflight } : null;
+  const text = neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase());
   const clauses = text.split(/\s*(?:[;\n,]|\.(?:\s+|$)|\band\b|\bthen\b|\bva\b)\s*/);
   const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
     && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));
   const codeChangeVerb = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause));
+  const reportArtifact = String(promptText).match(/(?:^|\s)((?:docs\/|reports\/)[A-Za-z0-9_./-]+\.(?:md|txt))(?=\s|[.,;:]|$)/)?.[1];
+  const documentation = !sourceOrder && !/\b(?:implement|fix|refactor|modify|edit|update|sua|chinh)\b/.test(actionable.join(' ')) && reportArtifact && actionable.some((clause) => /\b(?:write|create|save|viet|tao|luu)\b/.test(clause))
+    && /\b(?:report|bao cao|analysis|phan tich|document)\b/.test(text);
   const hasOperationId = /\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/.test(text);
   // A cron/job MENTION is not an operation: with a code-change verb in the request, an
   // operation needs a concrete target id; otherwise it is a coding task about scheduling.
@@ -237,13 +251,13 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
   // lookup verb AND no mutation vocabulary anywhere in the request (fail-closed otherwise).
   const mutationWord = /\b(?:implement|fix|refactor|modify|edit|write|update|add|create|build|make|install|deploy|remove|delete|rename|replace|change|sua|viet|chinh|them|tao|xoa|doi|cai|cap nhat)\b/.test(text);
   const statusReport = !mutationWord && !operation && !config
-    && /\b(?:check|status|report|show|summari[sz]e|result|results|kiem tra|bao cao|trang thai|ket qua)\b/.test(text);
-  const readOnly = (/\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text) || statusReport)
+    && /\b(?:check|status|report|show|summari[sz]e|result|results|kiem tra|bao cao|trang thai|ket qua|da len chua)\b/.test(text);
+  const readOnly = (/\b(?:audit|inspect|review|analyze|analyse|explain|read|investigate|debug|forensic|root cause|kiem tra|phan tich|dieu tra|doc log|tim hieu)\b/.test(text) || statusReport)
     && !sourceOrder && !codeChangeVerb && !operation && !config;
   const taskKind = operation ? (sourceOrder || (nativeDomain !== 'scheduled-job' && codeChangeVerb) ? 'MIXED' : 'OPERATIONAL')
-    : config ? 'CONFIGURATION' : readOnly ? 'READ_ONLY' : 'CODE_IMPLEMENTATION';
+    : config ? 'CONFIGURATION' : documentation ? 'DOCUMENTATION_OUTPUT' : readOnly ? 'READ_ONLY' : 'CODE_IMPLEMENTATION';
   const id = text.match(/\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/)?.[0] || null;
-  return { taskKind, ...(taskKind === 'READ_ONLY' && statusReport ? { statusReport: true } : {}), ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
+  return { taskKind, ...(releasePolicy ? { releasePolicy } : {}), ...(documentation ? { reportArtifact } : {}), ...(taskKind === 'READ_ONLY' && statusReport ? { statusReport: true } : {}), ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
     ...(operation && nativeDomain !== 'scheduled-job' ? { operationGoal: nativeOperationGoal(nativeDomain, actionable, text) } : {}),
     ...(operation && nativeDomain === 'scheduled-job' ? { operationGoal: { domain: 'scheduled-job', target: id, desiredState: /\b(?:delete|remove|cancel|xoa|huy|absent|removed|deleted|no longer|khong con)\b/.test(actionable.join(' ')) ? 'absent' : 'present',
       completionSemantics: /\b(?:ensure|dam bao)\b/.test(text) ? 'ensure-state' : 'execute-and-verify' } } : {}) };
@@ -254,7 +268,7 @@ export function applyTaskSemantics(contract, semantic) {
   const operationOnly = semantic.taskKind === 'OPERATIONAL'
     || (semantic.taskKind === 'CONFIGURATION' && semantic.configurationScope === 'external');
   return { ...(contract || {}), ...semantic,
-    completionEvidence: operationOnly ? ['operation-verification']
+    completionEvidence: semantic.taskKind === 'DOCUMENTATION_OUTPUT' ? ['report-artifact'] : operationOnly ? ['operation-verification']
       : semantic.taskKind === 'MIXED' ? [...new Set([...evidence, 'write-evidence', 'operation-verification'])]
         : semantic.taskKind === 'READ_ONLY' && semantic.statusReport ? []
         : semantic.taskKind === 'READ_ONLY' ? (evidence.length === 1 && evidence[0] === 'verification-evidence' ? evidence : ['impact-evidence']) : evidence };