intentdna 1.5.16 → 1.5.17

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
-      "version": "1.5.16",
+      "version": "1.5.17",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.5.16"
+  "version": "1.5.17"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.16",
+  "version": "1.5.17",
   "description": "Declarative policy layer for AI agent behavior",
   "author": {
     "name": "Samuel"

package/README.md

@@ -1,133 +1,105 @@
 # Intent DNA
 
-**AI Agent Guardrails in 30 seconds.**
+**Declarative control plane for AI agent behavior.**
 
-```bash
-npm install -g intentdna
-cd your-project
-dna guard
-```
-
-That's it. Your AI agent (Claude Code, Cursor, Cline) now has safety boundaries — no more accidental `rm -rf`, force-push to main, or production deletes.
+Intent DNA turns intent, policy, and accumulated experience into enforceable agent constraints. Instead of relying on prompts alone, it compiles DNA into the native control surfaces of Claude Code and related harnesses. It governs how agents operate across existing tools and systems; it does not replace your business systems or act as a domain-specific automation runtime.
 
 ---
 
-## Why?
+## What It Is
+
+Intent DNA is a compiler and runtime toolkit for managing agent behavior across three layers:
+
+- **Behavioral guidance** via generated prompt/context files
+- **Deterministic enforcement** via hooks and runtime checks
+- **Feedback loops** via trace, audit, and epigenetic evolution
 
-AI agents are powerful, but **one wrong move can be expensive**:
+It governs the agents operating on your systems rather than re-implementing the systems themselves.
 
-- Deletes production database
-- Force-pushes over main branch
-- Exposes secrets in logs
-- Runs up $500 API bills overnight
+The core model is:
+
+```text
+DNA config → compiler pipeline → Constraint IR → harness-specific outputs
+```
 
-**Intent DNA** gives agents clear rules about what they can and cannot do — enforced at the harness level, not just in prompts.
+For the architectural model and long-term design, see [DESIGN.md](DESIGN.md).  
+For the current stage and upcoming work, see [ROADMAP.md](ROADMAP.md).  
+For the schema contract, see [spec/schema-spec.md](spec/schema-spec.md).
+
+## Design Principles
+
+- Govern agents rather than re-implementing business systems.
+- Declare intent and boundaries first, then compile them into native control surfaces.
+- Combine guidance, enforcement, validation, and feedback into one governance loop.
+- Treat runtime state, validators, and signals as first-class governance assets.
+- Keep adapters and signal ingestion pluggable so the control plane outlives any single tool.
 
 ---
 
 ## Quick Start
 
-### Option 1: Zero-Config Guardrails (Recommended)
+### Option 1: Zero-config guardrails
 
 ```bash
 npm install -g intentdna
 cd your-project
-dna guard                    # Auto-detects Claude Code/Cursor/Cline
-```
-
-**What it does:**
-- Detects your AI coding environment
-- Injects safety rules (no production deletes, no force-push, etc.)
-- Generates enforcement hooks (hard blocks, not suggestions)
-- Creates audit logs at `~/.intentdna/audit/`
-
-**Levels:**
-```bash
-dna guard --level standard   # Safety baseline (default)
-dna guard --level yolo       # Max autonomy + safety net
-dna guard --level strict     # Enterprise-grade
-```
-
-**Audit:**
-```bash
-dna guard --audit            # Show last 7 days of violations
-dna guard --remove           # Remove all guardrails
+dna guard
 ```
 
----
-
-### Option 2: Custom DNA (Advanced)
-
-Start from a template:
+### Option 2: Template-based DNA
 
 ```bash
 dna init --template secure-dev
-dna sync .dna.yaml --inject CLAUDE.md --hooks .claude/hooks
+dna sync
 ```
 
-Or import your existing config:
+List templates:
 
 ```bash
-dna import .                 # Reads CLAUDE.md, hooks → generates .dna.yaml
-# Edit .dna.yaml to customize
-dna sync .dna.yaml --inject CLAUDE.md --hooks .claude/hooks
+dna init --template list
 ```
 
----
+Upgrade an existing template-backed config:
 
-## 20 Built-in Templates
-
-**Workflows (Superpowers-inspired):**
-- `brainstorming-first` — Socratic design before coding
-- `subagent-parallel` — Multi-agent with two-phase review
-- `verification-loop` — Confirm fix before marking done
-- `branch-finishing` — Merge/PR/cleanup decisions
-- `pr-submitter` — Pre-review checklist
-
-**Quality & Safety:**
-- `secure-dev` — Security + quality baseline
-- `tdd-strict` — Strict test-driven development
-- `safe-refactoring` — Step-by-step refactoring
-- `systematic-debugging` — Structured debugging
-- `code-review-pipeline` — Review workflow with retry
-
-**Domain-Specific:**
-- `frontend-quality` — React/accessibility/performance
-- `api-backend` — API security + database safety
-- `mobile-dev` — Flutter/React Native standards
-- `devops-cicd` — CI/CD agent guardrails
-- `monorepo-governance` — Multi-package isolation
-
-**Collaboration:**
-- `multi-perspective-review` — Bull/Bear debate review
-- `documentation-writer` — Technical docs
-- `enterprise-baseline` — Organization security
-- `yolo-with-guardrails` — Full autonomy + limits
-- `full-pipeline` — Complete plan→implement→test→review
-
-List all:
 ```bash
-dna init --template list
+dna init --upgrade <template-name>
 ```
 
 ---
 
 ## How It Works
 
-DNA compiles to your AI tool's native format:
+Intent DNA compiles to your tool's native control surfaces:
 
-```
-.dna.yaml → dna sync → CLAUDE.md + hooks + agents + skills + settings
+```text
+DNA → Constraint IR → CLAUDE.md / settings / agents / skills / runtime state
 ```
 
+Typical outputs include:
+
 | Output | Purpose |
 |--------|---------|
-| `CLAUDE.md` | Behavioral guidelines (soft) |
-| `.claude/hooks/*.sh` | Hard constraints (exit 2 = block) |
+| `CLAUDE.md` | Behavioral guidance |
+| `.dna/compiled/ir.json` | Runtime-readable compiled constraints |
 | `.claude/agents/*.md` | Role definitions |
-| `.cursorrules` | Cursor integration |
+| `.claude/skills/*/SKILL.md` | Workflow entrypoints |
+| `.claude/settings.json` or plugin runtime | Hook wiring |
 
-**Key insight:** Prompts can be ignored. Hooks cannot. DNA generates both.
+**Key idea:** prompts can drift, but runtime constraints and feedback loops make behavior governable.
+
+---
+
+## Supported Workflows
+
+Intent DNA currently focuses on:
+
+- Claude Code / Claude-style harnesses
+- Role-based agent workflows
+- Template-driven project bootstrap and upgrades
+- Deterministic guardrails and stateful enforcement
+- Dogfood-driven template iteration
+
+Adapter and ecosystem direction are tracked in [ROADMAP.md](ROADMAP.md), not duplicated here.
 
 ---
 
@@ -197,10 +169,8 @@ workflows:
 ## Supported Environments
 
 - ✅ **Claude Code** (CLAUDE.md + hooks + agents + skills + settings)
-- ✅ **Cursor** (.cursorrules)
-- ✅ **Cline** (.clinerules)
+- 🚧 **Prompt-style adapters and markdown outputs** (.cursorrules, .clinerules, GEMINI.md)
 - 🚧 **AgentScope** (coming soon)
-- 🚧 **Gemini CLI** (GEMINI.md)
 
 ---
 
@@ -223,13 +193,23 @@ dna evolve <dna-id>          # Generate epigenetic markers from outcomes
 
 - **Genes** encode behavioral traits
 - **Codons** are the atomic instructions
-- **Cascade** mimics genetic inheritance
-- **Epigenetics** learns from experience without changing genes
+- **Cascade** mimics inheritance and override rules
+- **Epigenetics** learns from experience without mutating source intent
 
 Read more: [DESIGN.md](DESIGN.md)
 
 ---
 
+## Documentation Map
+
+- [DESIGN.md](DESIGN.md) — long-term architecture and design
+- [ROADMAP.md](ROADMAP.md) — current stage, next plan, deferred work
+- [spec/schema-spec.md](spec/schema-spec.md) — schema contract
+- [docs/references/](docs/references/) — distilled research and implementation references
+- [docs/insights/](docs/insights/) — strategic and product-thinking documents
+
+---
+
 ## License
 
 Apache-2.0
@@ -248,4 +228,4 @@ Issues and PRs welcome. See [ROADMAP.md](ROADMAP.md) for planned features.
 - [Cline KanBan](https://github.com/cline/cline-kanban) — Multi-agent task orchestration
 - [AgentScope](https://github.com/modelscope/agentscope) — Multi-agent framework from Alibaba
 
-Intent DNA compiles to these frameworks' native formats.
+Intent DNA is designed to compile into the native control surfaces those frameworks expose, with current maturity varying by adapter.

package/dist/audit/index.d.ts

@@ -37,9 +37,17 @@ export interface PolicyViolationEvent extends AuditEvent {
 /** Completion check event */
 export interface CompletionCheckEvent extends AuditEvent {
     event_type: "completion_check";
-    check_type: "file_exists" | "file_not_empty" | "file_contains" | "command_success";
+    check_type: "file_exists" | "file_not_empty" | "file_contains" | "command_success" | "checkpoint_assert";
     target: string;
     result: "pass" | "fail";
+    verifier_id?: string;
+    verifier_when?: string;
+    verifier_severity?: string;
+    verifier_kind?: string;
+    evidence?: string;
+    exit_code?: number;
+    artifact?: string;
+    message?: string;
 }
 /** Session event */
 export interface SessionEvent extends AuditEvent {
@@ -56,6 +64,7 @@ export interface ConfigDriftEvent extends AuditEvent {
     expected_checksum: string;
     actual_checksum: string;
 }
+export type AnyAuditEvent = AuditEvent | ToolCallEvent | PolicyViolationEvent | CompletionCheckEvent | SessionEvent | ConfigDriftEvent;
 export interface AuditConfig {
     enabled: boolean;
     storage: string;
@@ -67,7 +76,7 @@ export type AuditTrackOption = "tool_calls" | "policy_violations" | "completion_
  * Write an audit event to the log.
  * Events are stored as JSONL (one JSON per line) in daily files.
  */
-export declare function writeAuditEvent(event: AuditEvent, config: AuditConfig): Promise<void>;
+export declare function writeAuditEvent(event: AnyAuditEvent, config: AuditConfig): Promise<void>;
 /**
  * Read audit events for a date range.
  */
@@ -75,7 +84,7 @@ export declare function readAuditEvents(logDir: string, options?: {
     from?: string;
     to?: string;
     event_type?: AuditEventType;
-}): Promise<AuditEvent[]>;
+}): Promise<AnyAuditEvent[]>;
 export interface AuditSummary {
     period: {
         from: string;

package/dist/cli/commands/feedback.d.ts

@@ -18,6 +18,9 @@ export interface FeedbackReport {
     blocks: number;
     warns: number;
     allows: number;
+    verifier_results: number;
+    verifier_passes: number;
+    verifier_failures: number;
     top_blocked_tools: Array<{
         tool: string;
         count: number;

package/dist/cli/commands/feedback.js

@@ -7,8 +7,8 @@
  * Reads: .dna/state/trace/trace-*.jsonl
  * Outputs: human-readable report (or JSON with --json)
  */
-import { readTraces } from "../../hooks/state.js";
-import { traceToOutcomes, summarizeConversion } from "../../evolution/trace-bridge.js";
+import { readTraces, readVerifierResults } from "../../hooks/state.js";
+import { mergeOutcomes, summarizeConversion } from "../../evolution/trace-bridge.js";
 import { describeMarkerChanges } from "../../evolution/marker-gen.js";
 import { EvolutionStore } from "../../evolution/store.js";
 function aggregate(traces) {
@@ -50,10 +50,15 @@ function aggregate(traces) {
         top_block_reasons: sorted(reasonCounts, 5, "reason"),
     };
 }
-function generateSuggestions(report) {
+function generateSuggestions(report, verifierResults = 0) {
     const suggestions = [];
     if (report.blocks === 0 && report.warns === 0) {
-        suggestions.push("No blocks or warnings — DNA constraints are not firing. Consider tightening rules or verifying hooks are active.");
+        if (verifierResults > 0) {
+            suggestions.push("No trace blocks or warnings in this window. Verifier activity is present, so review verifier pass/fail results alongside trace data.");
+        }
+        else {
+            suggestions.push("No blocks or warnings — DNA constraints are not firing. Consider tightening rules or verifying hooks are active.");
+        }
         return suggestions;
     }
     const blockRate = report.total_events > 0 ? report.blocks / report.total_events : 0;
@@ -93,6 +98,12 @@ function formatReport(report) {
     lines.push(`  Blocked: ${report.blocks}`);
     lines.push(`  Warned:  ${report.warns}`);
     lines.push("");
+    if (report.verifier_results > 0) {
+        lines.push(`Verifier results: ${report.verifier_results}`);
+        lines.push(`  Passed: ${report.verifier_passes}`);
+        lines.push(`  Failed: ${report.verifier_failures}`);
+        lines.push("");
+    }
     if (report.top_blocked_tools.length > 0) {
         lines.push("Top blocked tools:");
         for (const t of report.top_blocked_tools) {
@@ -126,23 +137,34 @@ function formatReport(report) {
 export async function runFeedback(opts) {
     const projectDir = process.cwd();
     const traces = await readTraces(projectDir, opts.days);
-    if (traces.length === 0) {
-        process.stderr.write(`No trace data found for the last ${opts.days} day(s).\n`);
-        process.stderr.write("Traces are generated by dna-hook during Claude Code sessions.\n");
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - opts.days);
+    const verifierResults = (await readVerifierResults(projectDir)).filter((result) => {
+        const timestamp = Date.parse(result.timestamp);
+        return Number.isNaN(timestamp) || timestamp >= cutoff.getTime();
+    });
+    if (traces.length === 0 && verifierResults.length === 0) {
+        process.stderr.write(`No trace or verifier data found for the last ${opts.days} day(s).\n`);
+        process.stderr.write("Signals are generated by dna-hook during Claude Code sessions.\n");
         return 0;
     }
     const stats = aggregate(traces);
-    const suggestions = generateSuggestions(stats);
-    const report = { ...stats, period_days: opts.days, suggestions };
+    const verifierStats = {
+        verifier_results: verifierResults.length,
+        verifier_passes: verifierResults.filter((result) => result.status === "pass").length,
+        verifier_failures: verifierResults.filter((result) => result.status === "fail").length,
+    };
+    const suggestions = generateSuggestions(stats, verifierStats.verifier_results);
+    const report = { ...stats, ...verifierStats, period_days: opts.days, suggestions };
     if (opts.json && !opts.evolve) {
         process.stdout.write(JSON.stringify(report, null, 2) + "\n");
     }
     else if (!opts.evolve) {
         process.stderr.write(formatReport(report));
     }
-    // --evolve: convert traces → epigenetic markers
+    // --evolve: convert normalized local signals → epigenetic markers
     if (opts.evolve) {
-        const outcomes = traceToOutcomes(traces);
+        const outcomes = mergeOutcomes(traces, verifierResults);
         if (outcomes.length === 0) {
             process.stderr.write(formatReport(report));
             process.stderr.write("\nNo actionable gene feedback found in traces — nothing to evolve.\n");

package/dist/cli/commands/run.js

@@ -270,7 +270,7 @@ export async function runRun(opts) {
             process.stderr.write(`Error: Workflow '${opts.workflowName}' not found. Available: ${Object.keys(cascaded.workflows).join(", ") || "(none)"}\n`);
             return 1;
         }
-        const wfResult = compileWorkflow(wfDef);
+        const wfResult = compileWorkflow(wfDef, { workflow_key: opts.workflowName });
         if (!wfResult.ok) {
             process.stderr.write(`Error: Workflow compilation failed:\n`);
             for (const err of wfResult.errors) {

package/dist/cli/commands/sync.js

@@ -21,7 +21,7 @@ import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
 import { compileWorkflowToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
-import { compilePluginSettings, detectEnabledEvents, mergeSettingsFile } from "../../runtime/settings-adapter.js";
+import { compilePluginSettings, detectEnabledEvents, mergeSettingsFile, recommendHookTimeouts } from "../../runtime/settings-adapter.js";
 import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
 import { cascadeDNA } from "../../compiler/cascade.js";
 import { EvolutionEngine } from "../../evolution/index.js";
@@ -569,7 +569,7 @@ export async function runSync(opts) {
         if (!opts.plugin && opts.settingsPath) {
             const enabledEvents = detectEnabledEvents(ir);
             if (enabledEvents.length > 0) {
-                const pluginSettings = compilePluginSettings(enabledEvents);
+                const pluginSettings = compilePluginSettings(enabledEvents, 10, recommendHookTimeouts(ir));
                 await mergeSettingsFile(pluginSettings, opts.settingsPath);
                 process.stderr.write(`Bin mode: registered ${enabledEvents.length} hook event(s) in ${opts.settingsPath}\n`);
                 trackedOutputs.push(resolve(opts.settingsPath));
@@ -627,7 +627,7 @@ export async function runSync(opts) {
                         process.stderr.write(`Workflow '${name}' not found\n`);
                         continue;
                     }
-                    const result = compileWorkflow(wfDef);
+                    const result = compileWorkflow(wfDef, { workflow_key: name });
                     if (!result.ok) {
                         process.stderr.write(`Workflow '${name}' compilation failed:\n`);
                         for (const err of result.errors) {
@@ -682,8 +682,8 @@ export async function runSync(opts) {
             else {
                 const { compileWorkflow } = await import("../../compiler/workflow.js");
                 const skillResults = [];
-                for (const [, wfDef] of Object.entries(workflows)) {
-                    const result = compileWorkflow(wfDef);
+                for (const [name, wfDef] of Object.entries(workflows)) {
+                    const result = compileWorkflow(wfDef, { workflow_key: name });
                     if (result.ok) {
                         skillResults.push(compileWorkflowToSkill(result.plan, roles, ir, variables));
                     }

package/dist/compiler/cascade.d.ts

@@ -10,7 +10,7 @@
  *   - attract/repel: same target accumulates, different targets independent
  *   - amplify/suppress: factors multiply (1.5x × 2.0x = 3.0x)
  */
-import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef } from "../schema/types.js";
+import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy } from "../schema/types.js";
 export interface CascadedDNA {
     genes: Record<string, Gene>;
     contexts: Record<string, ContextRegion>;
@@ -20,11 +20,13 @@ export interface CascadedDNA {
     source_ids: string[];
     /** Warnings from cascade process (e.g., cross-namespace gene collisions) */
     warnings?: string[];
+    legibility_assets?: LegibilityAssetMap;
     context_files?: {
         mandatory?: string[];
         per_role?: Record<string, string[]>;
         per_workflow?: Record<string, string[]>;
     };
+    verifier_policy?: VerifierCommandPolicy;
 }
 /**
  * Cascade multiple DNA layers into a single merged DNA.

package/dist/compiler/cascade.js

@@ -84,6 +84,80 @@ function prefixWorkflowRoles(wf, ns) {
         })),
     };
 }
+function prefixRecordKeys(record, ns) {
+    if (!record)
+        return undefined;
+    if (!ns)
+        return record;
+    return Object.fromEntries(Object.entries(record).map(([key, value]) => [`${ns}_${key}`, value]));
+}
+function prefixLegibilityAssets(map, ns) {
+    if (!map)
+        return undefined;
+    if (!ns)
+        return map;
+    return {
+        mandatory: map.mandatory,
+        per_role: prefixRecordKeys(map.per_role, ns),
+        per_workflow: prefixRecordKeys(map.per_workflow, ns),
+    };
+}
+function mergePrefixedRecords(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    return { ...base, ...incoming };
+}
+function mergeLegibilityAssets(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    return {
+        mandatory: incoming.mandatory ?? base.mandatory,
+        per_role: mergePrefixedRecords(base.per_role, incoming.per_role),
+        per_workflow: mergePrefixedRecords(base.per_workflow, incoming.per_workflow),
+    };
+}
+function prefixContextFiles(contextFiles, ns) {
+    if (!contextFiles)
+        return undefined;
+    if (!ns)
+        return contextFiles;
+    return {
+        mandatory: contextFiles.mandatory,
+        per_role: prefixRecordKeys(contextFiles.per_role, ns),
+        per_workflow: prefixRecordKeys(contextFiles.per_workflow, ns),
+    };
+}
+function mergeContextFiles(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    return {
+        mandatory: incoming.mandatory ?? base.mandatory,
+        per_role: mergePrefixedRecords(base.per_role, incoming.per_role),
+        per_workflow: mergePrefixedRecords(base.per_workflow, incoming.per_workflow),
+    };
+}
+function mergeVerifierPolicy(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    const mergeList = (a, b) => {
+        if (!a && !b)
+            return undefined;
+        return [...new Set([...(a ?? []), ...(b ?? [])])];
+    };
+    return {
+        allow_commands: mergeList(base.allow_commands, incoming.allow_commands),
+        allow_command_prefixes: mergeList(base.allow_command_prefixes, incoming.allow_command_prefixes),
+        allow_builtin_asserts: mergeList(base.allow_builtin_asserts, incoming.allow_builtin_asserts),
+    };
+}
 /**
  * Cascade multiple DNA layers into a single merged DNA.
  * Input must be sorted by priority (lowest first).
@@ -156,11 +230,19 @@ export function cascadeDNA(layers) {
             allMarkers.push(...dna.epigenetic.markers);
         }
     }
-    // context_files: highest-priority DNA wins (last in sorted layers)
+    // legibility_assets/context_files: highest-priority DNA wins (last in sorted layers)
+    let legibilityAssets;
     let contextFiles;
+    let verifierPolicy;
     for (const dna of sorted) {
+        if (dna.legibility_assets) {
+            legibilityAssets = mergeLegibilityAssets(legibilityAssets, prefixLegibilityAssets(dna.legibility_assets, dna.namespace));
+        }
         if (dna.context_files) {
-            contextFiles = dna.context_files;
+            contextFiles = mergeContextFiles(contextFiles, prefixContextFiles(dna.context_files, dna.namespace));
+        }
+        if (dna.verifier_policy) {
+            verifierPolicy = mergeVerifierPolicy(verifierPolicy, dna.verifier_policy);
         }
     }
     return {
@@ -171,6 +253,8 @@ export function cascadeDNA(layers) {
         epigenetic_markers: allMarkers,
         source_ids: sourceIds,
         warnings: warnings.length > 0 ? warnings : undefined,
+        legibility_assets: legibilityAssets,
         context_files: contextFiles,
+        verifier_policy: verifierPolicy,
     };
 }