intentdna 1.7.4 → 1.8.0

package/dist/workflow/index.d.ts

@@ -0,0 +1,3 @@
+export { AUTHORING_PACKET_SCHEMA_VERSION, buildAuthoringPacket, type AuthoringPacket, type AuthoringPacketExample, type AuthoringPacketOptions, } from "./authoring-packet.js";
+export { createWorkflowDraft, createWorkflowEditPlan, createWorkflowEditPlanFromWorkflow, buildWorkflowDesignPacket, workflowDraftExamples, workflowDraftToTemplateYaml, workflowDraftToYaml, type WorkflowDraft, type WorkflowDraftExample, type WorkflowDraftExampleId, type WorkflowDraftInput, type WorkflowDraftValidation, type WorkflowDraftDef, type WorkflowDesignPacket, type WorkflowEditOperation, type WorkflowEditPlan, type WorkflowEditPlanInput, type WorkflowTemplateEvidenceLink, type WorkflowTemplateLineage, type WorkflowTemplateContext, } from "./draft.js";
+export { SUGGESTION_REVIEW_PATH, SUGGESTION_REVIEW_STALE_LOCK_MS, WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION, appendSuggestionReviewReceipt, buildSuggestionReviewReceipt, findTerminalSuggestionReceipt, normalizeReviewDecision, readSuggestionReviewReceipts, sha256Canonical, suggestionBindingDigest, type SuggestionReviewDecision, type WorkflowSuggestionForReview, type WorkflowSuggestionReviewReceipt, type WorkflowSuggestionReviewSnapshot, } from "./suggestion-review.js";

package/dist/workflow/index.js

@@ -0,0 +1,3 @@
+export { AUTHORING_PACKET_SCHEMA_VERSION, buildAuthoringPacket, } from "./authoring-packet.js";
+export { createWorkflowDraft, createWorkflowEditPlan, createWorkflowEditPlanFromWorkflow, buildWorkflowDesignPacket, workflowDraftExamples, workflowDraftToTemplateYaml, workflowDraftToYaml, } from "./draft.js";
+export { SUGGESTION_REVIEW_PATH, SUGGESTION_REVIEW_STALE_LOCK_MS, WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION, appendSuggestionReviewReceipt, buildSuggestionReviewReceipt, findTerminalSuggestionReceipt, normalizeReviewDecision, readSuggestionReviewReceipts, sha256Canonical, suggestionBindingDigest, } from "./suggestion-review.js";

package/dist/workflow/suggestion-review.d.ts

@@ -0,0 +1,65 @@
+export declare const WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION = "intentdna.workflow_suggestion_review_receipt.v1";
+export declare const SUGGESTION_REVIEW_PATH: string;
+export declare const SUGGESTION_REVIEW_STALE_LOCK_MS = 30000;
+export type SuggestionReviewDecision = "accept" | "reject" | "defer";
+export interface WorkflowSuggestionForReview {
+    id: string;
+    evidenceRefs?: Array<{
+        type: string;
+        ref: string;
+    }>;
+}
+export interface WorkflowSuggestionReviewSnapshot {
+    asset: string;
+    workflowId: string;
+    suggestion: WorkflowSuggestionForReview;
+}
+export interface WorkflowSuggestionReviewReceipt {
+    schema_version: typeof WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION;
+    receipt_id: string;
+    reviewed_at: string;
+    asset: string;
+    workflow_id: string;
+    suggestion_id: string;
+    decision: SuggestionReviewDecision;
+    suggestion_digest: string;
+    binding_digest: string;
+    evidence_refs: Array<{
+        type: string;
+        ref: string;
+    }>;
+    source: "k4_human_review";
+}
+export declare function sha256Canonical(value: unknown): string;
+export declare function suggestionBindingDigest(params: {
+    asset: string;
+    workflowId: string;
+    suggestionId: string;
+    suggestionDigest: string;
+    evidenceRefs: Array<{
+        type: string;
+        ref: string;
+    }>;
+}): string;
+export declare function isSuggestionReviewReceipt(value: unknown): value is WorkflowSuggestionReviewReceipt;
+export declare function normalizeReviewDecision(value: string | undefined): SuggestionReviewDecision | undefined;
+export declare function buildSuggestionReviewReceipt(params: {
+    snapshot: WorkflowSuggestionReviewSnapshot;
+    decision: SuggestionReviewDecision;
+    reviewedAt?: string;
+}): WorkflowSuggestionReviewReceipt;
+export declare function readSuggestionReviewReceipts(projectDir: string): Promise<WorkflowSuggestionReviewReceipt[]>;
+export declare function findTerminalSuggestionReceipt(params: {
+    projectDir: string;
+    asset: string;
+    workflowId: string;
+    suggestionId: string;
+    bindingDigest: string;
+}): Promise<WorkflowSuggestionReviewReceipt | undefined>;
+export declare function appendSuggestionReviewReceipt(params: {
+    projectDir: string;
+    receipt: WorkflowSuggestionReviewReceipt;
+}): Promise<{
+    path: string;
+    existing?: WorkflowSuggestionReviewReceipt;
+}>;

package/dist/workflow/suggestion-review.js

@@ -0,0 +1,245 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, rm } from "node:fs/promises";
+import { join } from "node:path";
+export const WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION = "intentdna.workflow_suggestion_review_receipt.v1";
+export const SUGGESTION_REVIEW_PATH = join(".dna", "reviews", "workflow-suggestions.jsonl");
+export const SUGGESTION_REVIEW_STALE_LOCK_MS = 30_000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+export function sha256Canonical(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+export function suggestionBindingDigest(params) {
+    return sha256Canonical({
+        asset: params.asset,
+        workflowId: params.workflowId,
+        suggestionId: params.suggestionId,
+        suggestionDigest: params.suggestionDigest,
+        evidenceRefs: params.evidenceRefs.map((ref) => `${ref.type}:${ref.ref}`).sort(),
+    });
+}
+export function isSuggestionReviewReceipt(value) {
+    if (!isRecord(value))
+        return false;
+    const decision = value.decision;
+    const evidenceRefs = value.evidence_refs;
+    if (value.schema_version !== WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION ||
+        typeof value.receipt_id !== "string" ||
+        typeof value.reviewed_at !== "string" ||
+        Number.isNaN(Date.parse(value.reviewed_at)) ||
+        typeof value.asset !== "string" ||
+        typeof value.workflow_id !== "string" ||
+        typeof value.suggestion_id !== "string" ||
+        (decision !== "accept" && decision !== "reject" && decision !== "defer") ||
+        typeof value.suggestion_digest !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.suggestion_digest) ||
+        typeof value.binding_digest !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.binding_digest) ||
+        value.source !== "k4_human_review" ||
+        !Array.isArray(evidenceRefs) ||
+        !evidenceRefs.every((ref) => isRecord(ref) && typeof ref.type === "string" && typeof ref.ref === "string")) {
+        return false;
+    }
+    const expectedBinding = suggestionBindingDigest({
+        asset: value.asset,
+        workflowId: value.workflow_id,
+        suggestionId: value.suggestion_id,
+        suggestionDigest: value.suggestion_digest,
+        evidenceRefs: evidenceRefs,
+    });
+    return value.binding_digest === expectedBinding &&
+        value.receipt_id === `wsr_${expectedBinding.slice(0, 16)}_${decision}`;
+}
+export function normalizeReviewDecision(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "accept" || normalized === "reject" || normalized === "defer")
+        return normalized;
+    return undefined;
+}
+export function buildSuggestionReviewReceipt(params) {
+    const reviewedAt = params.reviewedAt ?? new Date().toISOString();
+    const suggestionDigest = sha256Canonical(params.snapshot.suggestion);
+    const evidenceRefs = params.snapshot.suggestion.evidenceRefs ?? [];
+    const bindingDigest = suggestionBindingDigest({
+        asset: params.snapshot.asset,
+        workflowId: params.snapshot.workflowId,
+        suggestionId: params.snapshot.suggestion.id,
+        suggestionDigest,
+        evidenceRefs,
+    });
+    return {
+        schema_version: WORKFLOW_SUGGESTION_REVIEW_SCHEMA_VERSION,
+        receipt_id: `wsr_${bindingDigest.slice(0, 16)}_${params.decision}`,
+        reviewed_at: reviewedAt,
+        asset: params.snapshot.asset,
+        workflow_id: params.snapshot.workflowId,
+        suggestion_id: params.snapshot.suggestion.id,
+        decision: params.decision,
+        suggestion_digest: suggestionDigest,
+        binding_digest: bindingDigest,
+        evidence_refs: evidenceRefs,
+        source: "k4_human_review",
+    };
+}
+function assertSafeReviewDirectory(path, stats) {
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Refusing non-directory or symlinked K4 review path: ${path}`);
+    }
+}
+async function existingProjectLocalDirectory(path) {
+    try {
+        const stats = await lstat(path);
+        assertSafeReviewDirectory(path, stats);
+        return true;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+async function ensureProjectLocalDirectory(path) {
+    if (await existingProjectLocalDirectory(path))
+        return;
+    try {
+        await mkdir(path, { recursive: false });
+    }
+    catch (err) {
+        if (!(err && typeof err === "object" && "code" in err && err.code === "EEXIST"))
+            throw err;
+    }
+    assertSafeReviewDirectory(path, await lstat(path));
+}
+async function ensureSuggestionReviewDirectory(projectDir, leaf) {
+    const dnaDir = join(projectDir, ".dna");
+    await ensureProjectLocalDirectory(dnaDir);
+    const directory = join(dnaDir, leaf);
+    await ensureProjectLocalDirectory(directory);
+    return directory;
+}
+async function readSuggestionReviewFile(path) {
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        return await handle.readFile("utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function appendSuggestionReviewFile(path, line) {
+    const handle = await open(path, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(line, "utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function recoverStaleSuggestionReviewLock(lockDir, now) {
+    try {
+        const stats = await lstat(lockDir);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error(`Refusing non-directory or symlinked K4 review lock: ${lockDir}`);
+        }
+        if (now - stats.mtimeMs < SUGGESTION_REVIEW_STALE_LOCK_MS)
+            return false;
+        await rm(lockDir, { recursive: true, force: true });
+        return true;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return true;
+        throw err;
+    }
+}
+async function withSuggestionReviewLock(projectDir, action) {
+    const locksDir = await ensureSuggestionReviewDirectory(projectDir, "locks");
+    const lockDir = join(locksDir, "workflow-suggestion-review.lock");
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        try {
+            await mkdir(lockDir, { recursive: false });
+            try {
+                return await action();
+            }
+            finally {
+                await rm(lockDir, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            if (err && typeof err === "object" && "code" in err && err.code === "EEXIST") {
+                if (await recoverStaleSuggestionReviewLock(lockDir, Date.now()))
+                    continue;
+                await new Promise((resolve) => setTimeout(resolve, 25));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error("Timed out waiting for workflow suggestion review lock");
+}
+export async function readSuggestionReviewReceipts(projectDir) {
+    const dnaDir = join(projectDir, ".dna");
+    if (!await existingProjectLocalDirectory(dnaDir))
+        return [];
+    const reviewsDir = join(dnaDir, "reviews");
+    if (!await existingProjectLocalDirectory(reviewsDir))
+        return [];
+    const path = join(projectDir, SUGGESTION_REVIEW_PATH);
+    try {
+        const raw = await readSuggestionReviewFile(path);
+        return raw.split("\n").filter((line) => line.trim().length > 0).flatMap((line) => {
+            try {
+                const parsed = JSON.parse(line);
+                if (isSuggestionReviewReceipt(parsed))
+                    return [parsed];
+            }
+            catch {
+                // Ignore corrupt historical receipt lines; validation remains fail-closed.
+            }
+            return [];
+        });
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+export async function findTerminalSuggestionReceipt(params) {
+    const receipts = await readSuggestionReviewReceipts(params.projectDir);
+    return receipts.find((receipt) => receipt.asset === params.asset &&
+        receipt.workflow_id === params.workflowId &&
+        receipt.suggestion_id === params.suggestionId &&
+        receipt.binding_digest === params.bindingDigest);
+}
+export async function appendSuggestionReviewReceipt(params) {
+    return withSuggestionReviewLock(params.projectDir, async () => {
+        const existing = await findTerminalSuggestionReceipt({
+            projectDir: params.projectDir,
+            asset: params.receipt.asset,
+            workflowId: params.receipt.workflow_id,
+            suggestionId: params.receipt.suggestion_id,
+            bindingDigest: params.receipt.binding_digest,
+        });
+        if (existing)
+            return { path: join(params.projectDir, SUGGESTION_REVIEW_PATH), existing };
+        const reviewsDir = await ensureSuggestionReviewDirectory(params.projectDir, "reviews");
+        const path = join(reviewsDir, "workflow-suggestions.jsonl");
+        await appendSuggestionReviewFile(path, JSON.stringify(params.receipt) + "\n");
+        return { path };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",

package/spec/README.md

@@ -1,58 +1,25 @@
 # Intent DNA — Spec Index
 
-[← Back to Repo Wiki](../docs/README.md)
+Status: normative
 
-This directory contains engineering specs. Use [ROADMAP.md](../ROADMAP.md) as the current planning authority and [DESIGN.md](../DESIGN.md) as the long-term architecture authority.
+This directory keeps only technical contracts still referenced by the current constitution and roadmap. Use [`../DESIGN.md`](../DESIGN.md) as the architecture authority and [`../ROADMAP.md`](../ROADMAP.md) as the milestone authority.
 
-## Status legend
-
-- **Canonical** — current contract or design reference.
-- **Active reference** — still useful for current implementation and maintenance.
-- **Completed / historical** — implementation handoff or bugfix record; use for context before changing the related area.
-- **Deferred** — design direction captured, not currently being built.
-
-## Specs
+## Retained Specs
 
 | Spec | Status | Purpose |
-|------|--------|---------|
-| [schema-spec.md](schema-spec.md) | Canonical | Intent DNA document structure, genes, roles, workflows, cascade, Enterprise bundle inheritance, RuntimeDecisionEvent, and IR contract. |
-| [foundation-hardening.md](foundation-hardening.md) | Active reference | Reliability, governance, MCP, and tool-experience hardening plan. |
-| [hooks-infra-harness-hardening.md](hooks-infra-harness-hardening.md) | Active reference | Hook boundary schema, enforcement result types, state manager, context/reflection/workflow gates. |
-| [workflow-pipeline.md](workflow-pipeline.md) | Active reference | Workflow pipeline design and state management unification. |
-| [parallel-isolation.md](parallel-isolation.md) | Deferred / design reference | Parallel execution and worktree isolation model. |
-| [multi-config.md](multi-config.md) | Active reference | Multi-template config management, namespace conflicts, template version tracking. |
-| [template-version-namespace-fix.md](template-version-namespace-fix.md) | Completed / historical | Template content hash and namespace-aware cleanup fix plan. |
-| [flutter-rewrite-template-optimization.md](flutter-rewrite-template-optimization.md) | Active reference | Dogfood template optimization for behavior-lock and rescue workflows. |
-| [agent-dispatch-fix.md](agent-dispatch-fix.md) | Completed / historical | F5 agent dispatch vulnerability repair plan. |
-| [control-plane-convergence-handoff-2026-04-24.md](control-plane-convergence-handoff-2026-04-24.md) | Completed / historical | Control-plane convergence handoff and remaining follow-up context. |
-
-## By implementation area
-
-### Schema and compiler
-
-- [schema-spec.md](schema-spec.md)
-- [multi-config.md](multi-config.md)
-- [template-version-namespace-fix.md](template-version-namespace-fix.md)
-
-### Hooks and governance
-
-- [hooks-infra-harness-hardening.md](hooks-infra-harness-hardening.md)
-- [foundation-hardening.md](foundation-hardening.md)
-- [parallel-isolation.md](parallel-isolation.md)
-
-### Workflows and templates
-
-- [workflow-pipeline.md](workflow-pipeline.md)
-- [flutter-rewrite-template-optimization.md](flutter-rewrite-template-optimization.md)
-- [agent-dispatch-fix.md](agent-dispatch-fix.md)
+| --- | --- | --- |
+| [`schema-spec.md`](schema-spec.md) | Canonical | Intent DNA schema, cascade, activation, RuntimeDecisionEvent, and Constraint IR contract. |
+| [`codex-adapter-contract.md`](codex-adapter-contract.md) | Active contract | Codex CLI adapter boundary, unsupported-field handling, and provenance mapping. |
+| [`workflow-capability-ir.md`](workflow-capability-ir.md) | Active reference | AI-native workflow capability vocabulary and mapping from workflow fields to capability requirements. |
+| [`sync-target-plan.md`](sync-target-plan.md) | Active reference | Boundary between `dna sync` orchestration and harness-specific target artifact planning. |
+| `README.md` | Navigation | This retained spec index. |
 
-### Signals, observability, and handoff
+## Archived Specs
 
-- [control-plane-convergence-handoff-2026-04-24.md](control-plane-convergence-handoff-2026-04-24.md)
-- [foundation-hardening.md](foundation-hardening.md)
+Historical handoffs, completed repair plans, and deferred implementation notes moved to [`../docs/archive/2026H1/spec/`](../docs/archive/2026H1/spec/). They can provide context, but they are not current requirements unless a retained spec, ADR, or roadmap entry explicitly cites them.
 
-## Maintenance rules
+## Maintenance Rules
 
-- New specs should declare whether they are canonical, active, completed/historical, or deferred.
-- When implementation finishes, update this index and [ROADMAP.md](../ROADMAP.md) if the project status changes.
-- Do not use completed specs as current requirements without checking the current code and roadmap.
+- Add a new retained spec only when `DESIGN.md`, `ROADMAP.md`, or an ADR needs a durable technical contract.
+- Move one-time plans, repair notes, and handoffs directly to archive.
+- Keep links from retained specs pointed at current contracts or explicit archive paths.

package/spec/codex-adapter-contract.md

@@ -0,0 +1,176 @@
+# Codex Adapter Contract Draft
+
+Status: draft for v1.8.0 contract freeze  
+Last updated: 2026-05-28
+
+## Scope
+
+This contract covers only the Codex CLI adapter. Cursor, Cline, Gemini, AgentScope, PromptAdapter, and other adapters are out of scope unless `ROADMAP.md` changes.
+
+The contract freezes the adapter boundary before implementation. It does not add a runtime skeleton, state subsystem, log subsystem, MCP subsystem, or dashboard feature.
+
+The nearest implementation reference is OMX / `oh-my-codex@0.18.6`. OMX is not a dependency for Intent DNA; it is source/runtime evidence for how a Codex-native orchestration layer handles plugin-scoped hooks, fallback `.codex/hooks.json`, setup refresh, and hook trust state.
+
+## Baseline assumptions
+
+- Target runtime: Codex CLI `>= 0.134.0` for the first hook-like dogfood path.
+- Reference implementation: OMX / `oh-my-codex@0.18.6`.
+- Local probe requirement: adapter dogfood must record the actual `codex` executable path and version. If unavailable, set runtime version evidence to `unknown` and classify events as diagnostic until verified.
+- Source-level completion and runtime-verified enforcement are separate claims. Fixtures may prove artifact generation, trust downgrade, and RuntimeDecisionEvent writing without local Codex; only a trusted real Codex hook execution may prove runtime enforcement.
+- Enforcement posture: prompt files are soft guidance; permissions/rules/hooks are stronger guardrails; Codex hooks are not a complete enforcement boundary.
+- Plugin posture: plugin-bundled hooks are supported by current docs and used by OMX, but they are non-managed hooks and must be reviewed/trusted before execution.
+- Fallback posture: adapter-managed `.codex/hooks.json` entries can be made idempotent and trust-aware, following OMX's owned-wrapper and `hooks.state` trusted-hash pattern.
+- Evidence posture: `.dna/compiled/codex-adapter-evidence.json` is adapter/config/probe evidence only. Primary RuntimeDecisionEvent evidence must be appended through `appendRuntimeDecisionEvent()` into `.dna/state/runtime-decisions/` and session-local runtime decision JSONL files.
+
+## Inputs
+
+The adapter consumes:
+
+| Input | Required | Description |
+|---|---:|---|
+| `constraint_ir` | yes | Compiled Intent DNA Constraint IR. |
+| `provenance_manifest` | yes | Policy bundle id/version, cascade layer fingerprints, compiled IR hash, and source fingerprints. |
+| `project_root` | yes | Repository root for Codex project artifacts. |
+| `codex_home` | optional | Codex home override for user/global config probes. |
+| `role_context` | optional | Active Intent DNA role, workflow step, and scope. Missing values become `unknown`. |
+| `adapter_mode` | yes | `interactive`, `exec`, or `dogfood_probe`. |
+| `hook_install_mode` | yes | `plugin_scoped`, `project_fallback`, `managed`, or `none`. |
+| `managed_policy` | optional | Whether the deployment can write/administer managed hooks or only project/plugin artifacts. |
+
+## Outputs
+
+The adapter may produce these artifacts once implementation starts:
+
+| Artifact | Purpose | Support posture |
+|---|---|---|
+| Codex instruction artifact | Carries `prompt_directives` into Codex instruction loading. | Partial. Use an owned generated block/file; do not overwrite user-authored `AGENTS.md` content without a block protocol. |
+| Codex permission/rule artifact | Narrows filesystem, network, and command execution behavior. | Partial. Maps strongest to Codex permissions/rules, with explicit unsupported gaps. |
+| Plugin-scoped hook artifact | Packages hooks through Codex plugin metadata, matching OMX's `plugins/oh-my-codex/.codex-plugin/plugin.json` + `hooks/hooks.json` pattern. | Distribution surface. Must not be considered active enforcement until trust is verified. |
+| Project/fallback hook artifact | Writes owned `.codex/hooks.json` entries and associated trust-state metadata when appropriate. | Stronger dogfood surface when generated entries are trusted and ownership is tracked. Preserve user hooks. |
+| Codex exec probe command | Runs `codex exec --json` and optional `--output-schema` for dogfood validation. | Partial. Useful for automation and evidence, not enough for interactive parity alone. |
+| Adapter evidence artifact | Writes `.dna/compiled/codex-adapter-evidence.json` with adapter/config/probe fingerprints, install-mode semantics, support status, and unsupported capabilities. | Diagnostic/config evidence only; never primary runtime evidence. |
+| RuntimeDecisionEvent evidence | Emits Intent DNA-compatible runtime decisions through existing state writers. | Adapter-generated; not native Codex/OMX output. Enterprise classification requires trusted hook execution and complete provenance. |
+
+## Install modes
+
+| Mode | Writes | Trust rule | Evidence classification |
+|---|---|---|---|
+| `plugin_scoped` | Plugin manifest + plugin hooks + adapter evidence. | Plugin hook identity must be reviewed/trusted and backed by runtime execution evidence before enforcement can be claimed. | Diagnostic until verified. |
+| `project_fallback` | Plugin artifacts, adapter evidence, owned `.codex/hooks.json`, and owned `.codex/config.toml` trust-state block. | Generated wrapper identity, `hooks.state` hash, runtime probe, runtime execution evidence, and provenance must all match. | May become enterprise evidence only when all trust inputs are complete. |
+| `managed` | Same source-level files as fallback until a managed root/pointer is implemented. | Managed root, runner hash, project pointer, runtime probe, execution evidence, and provenance must all match; this source-level slice does not yet collect managed proof. | Diagnostic-only until managed proof fields exist and pass. |
+| `none` | Adapter evidence only. | No runtime trust exists. | Unsupported/diagnostic only. |
+
+## Hook architecture contract
+
+The first implementation should copy the OMX split, not merely emit plugin hooks:
+
+```text
+Codex plugin install path
+  .codex-plugin/plugin.json -> hooks: ./hooks/hooks.json
+  hooks/hooks.json -> one dispatcher command
+  dispatcher -> Intent DNA Codex hook runner
+
+Fallback/project path
+  .codex/hooks.json -> owned generated wrapper entries
+  .codex/config.toml -> hook trust state when safe and supported
+  preserve user hook entries and user trust state
+```
+
+Required hook ownership rules:
+
+1. Generated hook entries must be recognizable as Intent DNA-owned wrappers.
+2. Refresh must strip/rewrite only Intent DNA-owned wrappers.
+3. Refresh must preserve user hook entries.
+4. Uninstall must remove only Intent DNA-owned wrappers and keep hook files if user hooks remain.
+5. Trust-state writes must be tied to the generated hook identity and recorded as evidence.
+6. Plugin-scoped hooks and fallback/project hooks must be recorded separately in evidence.
+
+## Constraint IR mapping contract
+
+| Constraint IR channel | Adapter behavior |
+|---|---|
+| `prompt_directives` | Render to Codex instruction context. Mark as soft guidance. Preserve source/provenance comments or metadata outside the user-visible instruction body where possible. |
+| `tool_filters` | Map filesystem/network/tool-command restrictions to permissions and `.rules` first; add hook checks for supported `PreToolUse` paths. Mark all uncovered paths `unsupported`. |
+| `pre_execution_gates` | Prefer managed hooks when available. Otherwise use project/fallback hooks with verified trust state. Plugin hooks may carry the same gate logic but cannot be treated as active until trust is confirmed. |
+| `post_execution_validators` | Map to `PostToolUse`, `Stop`, `codex exec --output-schema`, and adapter-side report checks. Do not claim rollback. |
+| `context_injections` | Map static context to instruction files and event-limited dynamic context to hook output where supported. Unsupported dynamic contexts remain explicit. |
+
+## RuntimeDecisionEvent mapping draft
+
+Codex adapter events must satisfy the existing `RuntimeDecisionEvent` schema. Required fields may use `unknown` or `unsupported`, but such events remain diagnostic rather than enterprise-authoritative until provenance is complete.
+
+The mapping table describes the logical source before persistence. Disk writes through `appendRuntimeDecisionEvent()` project untrusted identity, project, session, run, resource, source-ref, evidence-ref, tool, and reason fields with stable domain-separated SHA-256 labels. Controlled policy, gene, decision, and hook-action identifiers remain readable; same-call UUID/SHA evidence ids remain intact for C4/C5/trace binding. HookOutput may keep actionable user-facing text; persisted C4/C5 JSONL must not contain raw commands, local paths, session ids, identity/correlation ids, or arbitrary secret-shaped strings.
+
+| RuntimeDecisionEvent field | Codex / adapter source |
+|---|---|
+| `schema_version` | `intentdna.runtime_decision_event.v1.7.1`. |
+| `event_id` | Adapter-generated stable id per decision. |
+| `timestamp` | Adapter timestamp at decision emission. |
+| `org_id`, `team_id`, `user_id`, `project_id` | Intent DNA config/provenance; projected on disk; `unknown` if not configured. |
+| `agent_id` | Codex hook/session/subagent identity where available in `>=0.134.0`; projected on disk; otherwise adapter-generated or `unknown`. |
+| `agent_role` | Active Intent DNA role; projected on disk; `unknown` if no role context exists. |
+| `agent_type` | `codex_cli` or `codex_subagent` when known; projected on disk. |
+| `session_agent` | Codex session/subagent identity when provided; projected on disk; otherwise `unknown`. |
+| `harness_adapter` | `codex_cli`. |
+| `runtime` | `codex_cli@<version>` when probed; `codex_cli@unknown` when unavailable. |
+| `policy_bundle_id`, `policy_bundle_version` | Provenance manifest. |
+| `cascade_layers` | Provenance manifest layer fingerprints; unavailable layers must be explicit `unknown` / `unsupported`. |
+| `winning_constraint` | Adapter-selected constraint that produced the decision. |
+| `compiled_ir_hash` | Provenance manifest compiled IR hash. |
+| `decision` | Adapter decision: `allow`, `warn`, `block`, `escalate`, or `validate`. |
+| `decision_reason` | Human-readable reason derived from matching constraint and Codex event context; projected on disk. |
+| `enforcement_point` | `hook`, `plugin_runtime`, `ci`, or `unsupported` depending on source. Use `hook` for trusted project/fallback/managed hooks; use `plugin_runtime` only for trusted plugin hook execution. |
+| `harness_runtime_context` | Mirror agent/runtime fields above. |
+| `session_id` | Codex session id from hook/JSONL if available; projected on disk; otherwise adapter-generated run id or `unknown`. |
+| `run_id` | Adapter run id, preferably tied to a `codex exec --json` capture or interactive session capture; projected on disk. |
+| `step_id` | Workflow step id when running under Intent DNA workflow; otherwise `unknown`. |
+| `tool_name` | Hook input tool name, command kind, MCP server/tool name, or `unknown`; projected on disk. |
+| `action_kind` | Controlled hook event/action class such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `rule_check`, or `exec_final_schema`; retained on disk for decision audit. |
+| `resource_ref` | Command, file path, MCP resource, plugin hook id, fallback hook path, or `unknown`; projected on disk. |
+| `evidence_refs` | References to hook payload artifacts, JSONL exec events, generated config fingerprints, hook trust-state fingerprints, reports, or `unsupported` entries; projected on disk unless a C5 fact must preserve its C4 `runtime_decision_event` id binding. |
+
+## Trust and classification rules
+
+1. Never omit a required `RuntimeDecisionEvent` field.
+2. Use `unknown` for unavailable-but-conceptually-mappable values.
+3. Use `unsupported` for values Codex cannot provide or surfaces the adapter cannot intercept.
+4. Do not classify plugin-hook decisions as active enforcement until the hook definition has been reviewed/trusted or is delivered through managed policy.
+5. Project/fallback hook decisions may be classified as active only when the adapter proves all of: generated wrapper identity, matching `hooks.state` hash, Codex runtime probe, hook execution evidence, and complete RuntimeDecisionEvent provenance.
+6. Any required provenance field left `unknown` / `unsupported` keeps the event diagnostic-only under the existing RuntimeDecisionEvent validation semantics.
+7. `CodexAdapterSupportStatus` remains `supported | partial | unknown | unsupported`; diagnostic-only is a RuntimeDecisionEvent/evidence classification, not a support enum value.
+8. `PermissionRequest`, `SubagentStart`, and `SubagentStop` remain explicitly unsupported until hook I/O fixtures are frozen and tested.
+
+## Minimal dogfood path
+
+The first implementation milestone after this contract should:
+
+1. Probe `codex` availability and version.
+2. Generate a Codex instruction artifact for one narrow role/workflow.
+3. Generate a narrow permissions/rules artifact for the same role scope.
+4. Generate plugin-scoped hook metadata for distribution.
+5. Generate an owned project/fallback hook entry for one pre-execution gate, preserving user hooks.
+6. Record generated hook identity and trust-state evidence where supported.
+7. Run one `codex exec --json` workflow.
+8. Emit at least one RuntimeDecisionEvent-compatible artifact with complete provenance where possible and explicit placeholders otherwise.
+
+## Non-goals
+
+- No implementation of other adapters.
+- No new Intent DNA runtime/state/log/MCP infrastructure.
+- No hard dependency on OMX unless explicitly approved later.
+- No claim of full Claude Code hook parity.
+- No claim that plugin-bundled hooks are guaranteed before trust review.
+- No enterprise compliance statistics from diagnostic-only Codex events.
+
+## Sources
+
+- RuntimeDecisionEvent schema: `src/governance/runtime-decision-event.ts`
+- Enterprise provenance contract: `spec/schema-spec.md#enterprise-provenance-contract-v171`
+- Codex runtime notes: `docs/archive/2026H1/references/codex-cli-runtime-notes.md`
+- Codex capability matrix: `docs/archive/2026H1/references/codex-adapter-capability-matrix.md`
+- OMX package: `oh-my-codex@0.18.6`
+- OMX reference implementation files inspected from npm package:
+  - `plugins/oh-my-codex/.codex-plugin/plugin.json`
+  - `plugins/oh-my-codex/hooks/hooks.json`
+  - `dist/config/codex-hooks.js`
+  - `dist/scripts/codex-native-hook.js`