clckernel 1.2.19 → 2.0.1

package/src/adapters/agent-os.js

@@ -1,77 +1,126 @@
 /**
  * CLC Kernel — Agent-OS & Domain Workflows Stack Adapter
- * Supports AI Agent Operating Systems (Marketing OS, Content Ops, Research OS)
- * featuring Dual-Layer Governance and Domain Integrity Safeguards.
+ * Supports agent operating systems: repositories of skills, playbooks, rules,
+ * prompts, templates and data that AI agents run to carry out tasks.
+ * The kernel holds no business-domain rules: the guards below hold for any
+ * Agent-OS, and domain checks live in the project (tools/guards/), which the
+ * pre-commit hook and the audit run like the kernel's own guards.
  */
 
 const fs = require('fs');
 const path = require('path');
 const BaseAdapter = require('./base');
+const { currentIO, registeredPaths } = require('../io');
+const { FIRST_SESSION_SECTION } = require('../onboarding');
+
+/** Skills the harness installs itself: never a detection signal. */
+const HARNESS_SKILLS = new Set(['clckernel_cli', 'clc_forge_cli']);
+const SKILL_ROOTS = ['skills', '.agents/skills', '.claude/skills'];
+const MARKDOWN_SEARCH_DEPTH = 3;
+
+/** Folders that make up an Agent-OS, described in AGENTS.md when present. */
+const LAYER_FOLDERS = [
+  { folder: 'skills', skills: true, text: 'one folder per skill with a `SKILL.md` whose frontmatter holds a unique lowercase `name` and a `description`; the agent loads a skill when its description matches the task.' },
+  { folder: '.agents/skills', skills: true, text: 'skills in the shared agent layout (same `SKILL.md` contract as above).' },
+  { folder: '.claude/skills', skills: true, text: 'skills in the Claude Code layout (same `SKILL.md` contract as above).' },
+  { folder: 'playbooks', text: 'step-by-step procedures the agent runs for an operator; each declares its human checkpoint.' },
+  { folder: 'rules', text: 'standing constraints (style, tone, policy) every run must respect.' },
+  { folder: 'prompts', text: 'reusable prompt texts the skills and playbooks reference.' },
+  { folder: 'templates', text: 'output skeletons; double-brace slots are allowed only here.' },
+];
+
+/** Paths listed in the harness registry (working copy, either format); empty when absent or malformed. */
+function managedPaths(targetDir) {
+  return new Set(registeredPaths(targetDir));
+}
+
+/** True when root/<name>/SKILL.md exists for a skill the harness did not install. */
+function hasUserSkill(targetDir, root, managed = managedPaths(targetDir)) {
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(targetDir, root), { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return entries.some(entry => {
+    if (!entry.isDirectory() || HARNESS_SKILLS.has(entry.name)) return false;
+    const rel = `${root}/${entry.name}/SKILL.md`;
+    return !managed.has(rel) && fs.existsSync(path.join(targetDir, rel));
+  });
+}
+
+/** True when dir holds a Markdown file within `depth` levels. */
+function hasMarkdown(dir, depth = MARKDOWN_SEARCH_DEPTH) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return entries.some(entry => (entry.isFile() && entry.name.endsWith('.md'))
+    || (entry.isDirectory() && depth > 1 && hasMarkdown(path.join(dir, entry.name), depth - 1)));
+}
+
+/** Layer folders present in targetDir, in LAYER_FOLDERS order. */
+function presentLayers(targetDir) {
+  const managed = managedPaths(targetDir);
+  return LAYER_FOLDERS.filter(layer => (layer.skills
+    ? hasUserSkill(targetDir, layer.folder, managed)
+    : fs.existsSync(path.join(targetDir, layer.folder))));
+}
 
 class AgentOSAdapter extends BaseAdapter {
   constructor() {
     super('Agent-OS (Domain & AI Workflows)', 'agent-os', 'Playbook / Contract Test');
   }
 
+  /**
+   * An agent operating system: a SKILL.md in skills/<name>/, .agents/skills/<name>/
+   * or .claude/skills/<name>/ (skills the harness installs excluded), a
+   * playbooks/ or rules/ folder with Markdown, or a generic package.json
+   * signal (`agent-os` in the name, description or keywords, or the
+   * `ai-agents` keyword). A code stack that also matches wins (see detector).
+   */
   detect(targetDir) {
-    // 1. package.json check
     const pkgPath = path.join(targetDir, 'package.json');
     if (fs.existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
         const name = (pkg.name || '').toLowerCase();
         const desc = (pkg.description || '').toLowerCase();
-        const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.map(k => k.toLowerCase()) : [];
+        const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.map(k => String(k).toLowerCase()) : [];
         if (
-          name.includes('agent-os') || name.includes('marketing-os') || name.includes('laila-mos') ||
-          desc.includes('agent-os') || desc.includes('marketing operating system') ||
-          keywords.includes('agent-os') || keywords.includes('marketing-os') || keywords.includes('ai-agents')
+          name.includes('agent-os') || desc.includes('agent-os') ||
+          keywords.includes('agent-os') || keywords.includes('ai-agents')
         ) {
           return true;
         }
       } catch {}
     }
 
-    // 2. skills/ or .agents/skills/ directory check
-    const skillsDir = path.join(targetDir, 'skills');
-    const agentSkillsDir = path.join(targetDir, '.agents', 'skills');
-    if (fs.existsSync(skillsDir) || fs.existsSync(agentSkillsDir)) {
-      const dirToCheck = fs.existsSync(skillsDir) ? skillsDir : agentSkillsDir;
-      try {
-        const files = fs.readdirSync(dirToCheck);
-        if (files.some(f => f.endsWith('.md'))) {
-          return true;
-        }
-      } catch {}
-    }
-
-    // 3. brand/ or templates/ check alongside README referencing agents/workflows
-    const brandPath = path.join(targetDir, 'brand');
-    const templatesPath = path.join(targetDir, 'templates');
-    const readmePath = path.join(targetDir, 'README.md');
-    if ((fs.existsSync(brandPath) || fs.existsSync(templatesPath)) && fs.existsSync(readmePath)) {
-      try {
-        const readme = fs.readFileSync(readmePath, 'utf-8').toLowerCase();
-        if (readme.includes('subagent') || readme.includes('operating system') || readme.includes('agent')) {
-          return true;
-        }
-      } catch {}
-    }
-
-    return false;
+    const managed = managedPaths(targetDir);
+    if (SKILL_ROOTS.some(root => hasUserSkill(targetDir, root, managed))) return true;
+    return ['playbooks', 'rules'].some(folder => hasMarkdown(path.join(targetDir, folder)));
   }
 
   getSafeguards() {
     return [
       'Dual-Layer Architecture: Layer 1 (Engineering) & Layer 2 (Domain Runtime)',
-      'Mandatory Human-in-the-Loop (HITL) Checkpoints',
-      'Symlink Interoperability (.cursorrules, CLAUDE.md, GEMINI.md, .windsurfrules)',
-      'Domain Data Integrity & Clean Creation State (No Hallucinated Metrics)',
-      'Single Source of Truth (SSOT) Memory Primacy',
-      'Local-only Spec Driven Development (sdds/)'
+      'Human-in-the-Loop (HITL) checkpoints: every changed skill and playbook declares a `HITL:` line or a `## Human checkpoint` section (check_hitl)',
+      'Skill frontmatter: unique lowercase `name` and a `description` of at most 1024 characters in every changed SKILL.md (check_skills)',
+      'Relative Markdown links resolve to files in the commit (check_links)',
+      'No forgotten draft placeholders in changed Markdown, YAML and JSON (check_placeholders)',
+      'Changed JSON data files parse (check_data_files)',
+      'Rule mirrors (CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules) point to AGENTS.md (check_symlinks)',
+      'Project rules from .clckernel.yaml (check_custom)',
+      'Secret Leak Guard (scan_secrets)',
+      'Single Source of Truth (SSOT) memory protocol (agent-enforced; not checked by a guard)',
+      'Local-only Spec Driven Development (sdds/)',
+      'Red→Green TDD Verifier (runs changed tests with vitest / jest / node:test)'
     ];
   }
 
+  /** Guards for any Agent-OS; domain checks belong in the project's tools/guards/. */
   getTools() {
     return [
       {
@@ -79,28 +128,42 @@ class AgentOSAdapter extends BaseAdapter {
         language: 'js',
         path: 'check_symlinks.js',
         command: 'node tools/check_symlinks.js',
-        description: 'AI IDE symlinks and rule mirror verification'
+        description: 'AI IDE rule mirrors point to AGENTS.md (symlink or identical copy)'
       },
       {
         name: 'check_hitl',
         language: 'js',
         path: 'check_hitl.js',
         command: 'node tools/check_hitl.js',
-        description: 'Human-in-the-Loop review checkpoint validator'
+        description: 'Explicit Human-in-the-Loop checkpoint marker in changed skills and playbooks'
+      },
+      {
+        name: 'check_skills',
+        language: 'js',
+        path: 'check_skills.js',
+        command: 'node tools/check_skills.js',
+        description: 'SKILL.md frontmatter: name and description present, well-formed and unique'
+      },
+      {
+        name: 'check_links',
+        language: 'js',
+        path: 'check_links.js',
+        command: 'node tools/check_links.js',
+        description: 'Relative links in changed Markdown point to files in the commit'
       },
       {
-        name: 'check_domain_data',
+        name: 'check_placeholders',
         language: 'js',
-        path: 'check_domain_data.js',
-        command: 'node tools/check_domain_data.js',
-        description: 'Domain deliverables schema and clean state integrity'
+        path: 'check_placeholders.js',
+        command: 'node tools/check_placeholders.js',
+        description: 'Forgotten draft placeholders in changed Markdown, YAML and JSON (templates/ may keep slots)'
       },
       {
-        name: 'check_test_calendar_sync',
+        name: 'check_data_files',
         language: 'js',
-        path: 'check_test_calendar_sync.js',
-        command: 'node tools/check_test_calendar_sync.js',
-        description: 'Test calendar harness synchronization and parity check'
+        path: 'check_data_files.js',
+        command: 'node tools/check_data_files.js',
+        description: 'Every changed .json file parses (snapshot content, any folder)'
       },
       {
         name: 'scan_secrets',
@@ -108,6 +171,20 @@ class AgentOSAdapter extends BaseAdapter {
         path: 'scan_secrets.js',
         command: 'node tools/scan_secrets.js',
         description: 'Security & API key leak scanner'
+      },
+      {
+        name: 'verify_tdd',
+        language: 'js',
+        path: 'verify_tdd.js',
+        command: 'node tools/verify_tdd.js',
+        description: 'Runs changed tests (vitest / jest / node:test) against BASE (must fail) and the staged code (must pass)'
+      },
+      {
+        name: 'check_custom',
+        language: 'js',
+        path: 'check_custom.js',
+        command: 'node tools/check_custom.js',
+        description: 'Project rules from .clckernel.yaml (e.g. sections every playbook must have)'
       }
     ];
   }
@@ -119,7 +196,11 @@ class AgentOSAdapter extends BaseAdapter {
     // would make the guard below skip the dual-layer render entirely.
     super.provision(targetDir, { ...(config || {}), skipAgentsMd: true });
 
-    // 2. Write Dual-Layer AGENTS.md
+    // 2. Write Dual-Layer AGENTS.md, describing only the folders that exist.
+    const layers = presentLayers(targetDir);
+    const layerMap = layers.length > 0
+      ? layers.map(layer => `- \`${layer.folder}/\` — ${layer.text}`).join('\n')
+      : '- No agent folders yet. Add skills, playbooks, rules, prompts or templates folders and describe them here.';
     const dualLayerAgents = `# Standard Operating Procedure (SOP) — AGENTS
 Governed by **CLC Kernel: The Universal AI Agent Governance Engine**.
 Target System: **${this.name}**
@@ -129,7 +210,7 @@ Target System: **${this.name}**
 ## 🛠️ Layer 1: Development & Maintenance Governance (Engineering)
 All AI Agents (Antigravity, OpenCode, Claude Code, Cursor, Windsurf, Copilot) developing or maintaining this codebase MUST adhere to strict engineering standards:
 
-> 🚨 **RULE #0: MANDATORY EXECUTION OVERRIDE RULE (UNBYPASSABLE)**
+> 🚨 **RULE #0: MANDATORY EXECUTION OVERRIDE RULE (NO EXCEPTIONS)**
 > Even when the user issues a direct or urgent fix request ("fix this bug", "fix this error", "quick fix"):
 > YOU ARE STRICTLY FORBIDDEN from modifying source code or workflows directly without completing the full quality harness:
 > 1. **Research & Root Cause Analysis:** Investigate tracebacks and affected files before editing.
@@ -140,7 +221,7 @@ All AI Agents (Antigravity, OpenCode, Claude Code, Cursor, Windsurf, Copilot) de
 
 ### Engineering Rules
 1. **Conventional Commits Only**: Commits must use Conventional Commits (e.g. \`feat(...): ...\`, \`fix(...): ...\`). NEVER add \`Co-Authored-By\` or AI attribution.
-2. **Mirror Links Interoperability**: \`CLAUDE.md\`, \`GEMINI.md\`, \`.cursorrules\`, and \`.windsurfrules\` must remain valid symlinks to \`AGENTS.md\`.
+2. **Mirror Links Interoperability**: \`CLAUDE.md\`, \`GEMINI.md\`, \`.cursorrules\`, and \`.windsurfrules\` must remain symlinks to (or identical copies of) \`AGENTS.md\` (checked by \`tools/check_symlinks.js\`).
 3. **No Superficial Symptom Patches**: Always address root causes.
 
 ---
@@ -149,10 +230,14 @@ All AI Agents (Antigravity, OpenCode, Claude Code, Cursor, Windsurf, Copilot) de
 When operating as domain agents for end-users and non-technical operators:
 
 1. **Non-Technical Operator Friendly**: Interact naturally with the operator. Guide step-by-step through conversational prompts without technical jargon.
-2. **Mandatory Human-in-the-Loop (HITL) Checkpoints**: Always pause phase-by-phase during multi-step pipelines. Present draft output and WAIT for explicit user confirmation before executing irreversible steps.
-3. **SSOT Memory Primacy**: Always read from and persist to designated single-source-of-truth memory files (e.g. \`brand/client-profile.md\` or \`docs/\`).
-4. **Clean Creation State (No Hallucinated Data)**: When new records, calendars, or deliverables are drafted, metric fields must initialize as \`null\` / empty. Never invent fictional stats.
-5. **Deterministic Output Standard**: Outputs must strictly follow valid Markdown, JSON schema, or domain templates.
+2. **Mandatory Human-in-the-Loop (HITL) Checkpoints**: Always pause phase-by-phase during multi-step pipelines. Present draft output and WAIT for explicit user confirmation before executing irreversible steps. Every skill and playbook declares its checkpoint with a \`HITL:\` line or a \`## Human checkpoint\` section (checked by \`tools/check_hitl.js\`).
+3. **Skill Contract**: Every \`SKILL.md\` opens with a frontmatter holding a unique lowercase \`name\` and a \`description\` that says when to use the skill (checked by \`tools/check_skills.js\`).
+4. **SSOT Memory Primacy**: Read from and persist to the files this repository designates as its single source of truth; never keep operator data only in a conversation.
+5. **Clean Creation State (No Invented Data)**: Never invent data. A field without a real value stays empty or \`null\` until real data exists.
+6. **Finished Documents**: Deliverables follow the repository's templates and formats, keep no draft placeholders and link only to files that exist (checked by \`tools/check_placeholders.js\` and \`tools/check_links.js\`).
+
+### Repository Map
+${layerMap}
 
 ---
 
@@ -161,27 +246,31 @@ When given a command matching \`clckernel <action>\` or \`/clckernel <action>\`,
 
 | Command | Lifecycle Phase | Mandatory Execution Protocol |
 |---|---|---|
-| \`clckernel feature <name>\` | New Feature | 1. Research affected layers.<br>2. Author local spec in \`sdds/{name}/spec.md\`.<br>3. Present HIT review to user and wait for approval.<br>4. Write failing test (Red Phase).<br>5. Implement clean code (Green Phase).<br>6. Run \`node tools/audit.js\` (or \`audit.py\`). |
+| \`clckernel feature <name>\` | New Feature | 1. Research affected layers.<br>2. Author local spec in \`sdds/{name}/spec.md\`.<br>3. Present HIT review to user and wait for approval.<br>4. Write failing test (Red Phase).<br>5. Implement clean code (Green Phase).<br>6. Run \`node tools/audit.js --change {name}\` (or \`audit.py --change {name}\`). |
 | \`clckernel fix <issue>\` | Bug Fix | 1. Investigate root cause (no code edits).<br>2. Reproduce with failing test (Red Phase).<br>3. Minimal surgical fix respecting Clean Arch (Green Phase).<br>4. Run audit gate without skipping. |
 | \`clckernel test\` | Verification | Run test suite and verify clean pass (exit code 0). |
-| \`clckernel audit\` | Verification | Run \`node tools/audit.js\` or \`python tools/audit.py\` and output the Educational Summary. |
-| \`clckernel doctor\` | Diagnostics | Check git pre-commit hooks, IDE symlinks, and AST engine integrity. |
+| \`clckernel audit\` | Verification | Run \`npx clckernel audit [dir] [--change <name>]\` (every installed orchestrator: \`tools/audit.js\` and/or \`tools/audit.py\`) and output the Educational Summary; only \`--change\` writes the report to \`sdds/<name>/\`. |
+| \`clckernel doctor\` | Diagnostics | Run \`npx clckernel doctor [dir]\`: checks AGENTS.md, sdds/, tools/, the pre-commit hook and that the guard scripts load. |
 | \`clckernel commit <message>\` | Version Control | Run full audit, verify tests pass, ensure no changes outside SDD scope, and commit with conventional commits (never add AI attribution). |
-| \`clckernel guard create <name>\` | Safeguards | Scaffold a new AST guard in the stack's native language in \`tools/guards/\`. |
-| \`clckernel update\` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |
-| \`clckernel start\` | Setup | Scan codebase, propose governance plan, and materialize \`.clckernel.yaml\`. |
+| \`clckernel guard create <name>\` | Safeguards | Scaffold a new guard script in the stack's native language in \`tools/guards/\`. |
+| \`clckernel update\` | Maintenance | Non-destructive update: run \`npx clckernel update [dir]\` (\`--dry-run\` previews, \`--add-guards <a,b\\|all>\` adds guards); refreshes kernel tools, hook, playbooks & symlinks (preserves SDDs, project guards, edited files & \`.clckernel.yaml\`). |
+| \`clckernel start\` | Setup | Scan codebase and propose a governance plan; if the harness is missing, install it with \`npx clckernel . --yes\`. \`.clckernel.yaml\` is optional: write it only for settings that differ from the defaults. |
 
 ---
 
 ## 🛡️ Core AI Safeguards
 ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
-`;
 
-    // Guard: never overwrite a project-customized AGENTS.md (e.g. a Laila MOS
-    // law file carrying domain invariants the template cannot know about).
+---
+
+${FIRST_SESSION_SECTION}`;
+
+    // Guard: never overwrite a project-customized AGENTS.md (e.g. a law file
+    // carrying domain invariants the template cannot know about).
+    const io = currentIO(targetDir);
     const dualAgentsPath = path.join(targetDir, 'AGENTS.md');
-    if (!fs.existsSync(dualAgentsPath)) {
-      fs.writeFileSync(dualAgentsPath, dualLayerAgents, 'utf-8');
+    if (!io.exists(dualAgentsPath)) {
+      io.writeFile(dualAgentsPath, dualLayerAgents);
     }
 
     // 3. Create AI IDE mirror symlinks
@@ -189,26 +278,14 @@ ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
     for (const mirror of mirrors) {
       const mirrorPath = path.join(targetDir, mirror);
       try {
-        if (!fs.existsSync(mirrorPath)) {
-          fs.symlinkSync('AGENTS.md', mirrorPath);
+        // An update never creates a mirror the project deleted (sdds/update-no-additions).
+        if (!io.exists(mirrorPath)) {
+          io.mirror('AGENTS.md', mirrorPath);
         }
       } catch {}
     }
-
-    // 4. Copy domain guard tools into tools/
-    const srcToolsDir = path.join(__dirname, '..', '..', 'tools');
-    const targetToolsDir = path.join(targetDir, 'tools');
-    const toolsToCopy = ['check_symlinks.js', 'check_hitl.js', 'check_domain_data.js', 'check_test_calendar_sync.js', 'scan_secrets.js', 'audit.js'];
-
-    for (const toolFile of toolsToCopy) {
-      const srcFile = path.join(srcToolsDir, toolFile);
-      const destFile = path.join(targetToolsDir, toolFile);
-      if (fs.existsSync(srcFile) && !fs.existsSync(destFile)) {
-        try {
-          fs.copyFileSync(srcFile, destFile);
-        } catch {}
-      }
-    }
+    // Guards are copied by the generator from getTools(targetDir), so the
+    // registry and the hook list exactly what is installed.
   }
 }
 

package/src/adapters/astro.js

@@ -34,9 +34,9 @@ class AstroAdapter extends BaseAdapter {
       'SEO, GEO & Web Performance Guard (metadata, OpenGraph, Core Web Vitals)',
       'Secret & API Key Leak Scanner',
       'Content Collection Schema Validation Guard',
-      'Vitest / Playwright Red-to-Green TDD Validator',
+      'Red→Green TDD Verifier (runs changed tests with vitest / jest / node:test)',
       'Educational Audit Gate (05-audit-report.md)',
-      'Memory Guard (Engram / Graphify ADR Sync)'
+      'Memory protocol (agent-enforced; Engram / Graphify optional, not checked by a guard)'
     ];
   }
 
@@ -51,11 +51,13 @@ class AstroAdapter extends BaseAdapter {
       { name: 'check_a11y',       language: 'js',       path: 'check_a11y.js',       command: 'node tools/check_a11y.js',       description: 'Validates ARIA and accessibility rules' },
       { name: 'check_responsive', language: 'js',       path: 'check_responsive.js', command: 'node tools/check_responsive.js', description: 'Audits mobile-first responsiveness and fixed-width overflows' },
       { name: 'check_seo',        language: 'js',       path: 'check_seo.js',        command: 'node tools/check_seo.js',        description: 'Validates SEO metadata, OpenGraph, GEO tags, and LCP priority' },
-      { name: 'check_custom',     language: 'js',       path: 'check_custom.js',     command: 'node tools/check_custom.js',     description: 'Runs user-defined custom rules from .clc-forge.yml' },
-      { name: 'astro_check',      language: 'external', path: '', command: 'npx astro check', description: 'Astro type checking', extCLI: 'astro' },
-      { name: 'vitest',           language: 'external', path: '', command: 'npx vitest run',  description: 'Test runner', extCLI: 'vitest' },
+      { name: 'verify_tdd',       language: 'js',       path: 'verify_tdd.js',       command: 'node tools/verify_tdd.js',       description: 'Runs changed tests (vitest / jest / node:test) against BASE (must fail) and the staged code (must pass)' },
+      { name: 'check_custom',     language: 'js',       path: 'check_custom.js',     command: 'node tools/check_custom.js',     description: 'Runs user-defined custom rules from .clckernel.yaml' },
+      { name: 'astro_check',      language: 'external', path: '', command: 'npx astro check', description: 'Astro type checking', extCLI: 'astro', availableIf: '[ -x node_modules/.bin/astro ]' },
+      // vitest fails when there are no test files yet (a fresh project): that is not a failure.
+      { name: 'vitest',           language: 'external', path: '', command: 'npx vitest run --passWithNoTests',  description: 'Test runner', extCLI: 'vitest', availableIf: '[ -x node_modules/.bin/vitest ]' },
     ];
-    return this._mergeTechTools(baseTools);
+    return baseTools;
   }
 
   provision(targetDir, config) {

package/src/adapters/base.js

@@ -4,17 +4,15 @@
  * inherit from this interface to ensure universal polyglot harness behavior.
  */
 
-const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-const { TechnologyDetector } = require('../technologies/detector');
+const { currentIO } = require('../io');
+const { FIRST_SESSION_SECTION } = require('../onboarding');
 
 class BaseAdapter {
   constructor(name, projectType, testRunner) {
     this.name = name;
     this.projectType = projectType;
     this.testRunner = testRunner;
-    this.techDetector = new TechnologyDetector();
   }
 
   detect(targetDir) {
@@ -28,50 +26,36 @@ class BaseAdapter {
   /**
    * Returns the tool manifest for this adapter.
    * Each entry describes one pre-commit tool (script or external CLI).
-   * Override in subclasses to declare stack-specific tools.
+   * Override in subclasses to declare stack-specific tools. The generator
+   * passes the project root, so an adapter may add guards whose structure is
+   * present; without it the adapter's unconditional set is returned.
+   * @param {string} [targetDir] - Project root
    * @returns {Array<{name: string, language: string, path: string, command: string, description: string, extCLI?: string}>}
    */
-  getTools() {
+  getTools(targetDir) {
     return [];
   }
 
-  /**
-   * Merges technology-specific tools into the adapter tool manifest.
-   * Tech tools are inserted before check_custom to preserve user override escape hatch.
-   * @param {Array} baseTools - The adapter's base tool manifest
-   * @returns {Array} Merged tool manifest with technology tools inserted
-   */
-  _mergeTechTools(baseTools) {
-    const techTools = this.techDetector.getToolsForTech(this.detectedTech || []);
-    if (techTools.length === 0) return baseTools;
-
-    const result = [];
-    for (const tool of baseTools) {
-      if (tool.name === 'check_custom') {
-        // Insert tech tools before check_custom
-        result.push(...techTools);
-      }
-      result.push(tool);
-    }
-    return result;
-  }
-
   provision(targetDir, config) {
     // Subclasses that render their own AGENTS.md pass { skipAgentsMd: true }
     // so this generic law file is never written alongside (or over) theirs.
     const skipAgentsMd = !!(config && config.skipAgentsMd);
 
+    // Every write goes through the active io session (sdds/safe-update).
+    const io = currentIO(targetDir);
+
     // 1. Create docs/ and sdds/
-    fs.mkdirSync(path.join(targetDir, 'docs', 'Journal'), { recursive: true });
-    fs.mkdirSync(path.join(targetDir, 'docs', 'Architecture'), { recursive: true });
-    fs.mkdirSync(path.join(targetDir, 'docs', 'Development'), { recursive: true });
-    fs.mkdirSync(path.join(targetDir, 'sdds'), { recursive: true });
-    fs.mkdirSync(path.join(targetDir, 'tools'), { recursive: true });
+    io.mkdir(path.join(targetDir, 'docs', 'Journal'));
+    io.mkdir(path.join(targetDir, 'docs', 'Architecture'));
+    io.mkdir(path.join(targetDir, 'docs', 'Development'));
+    io.mkdir(path.join(targetDir, 'sdds'));
+    io.mkdir(path.join(targetDir, 'tools'));
 
     // 2. Gitignore local SDD specs, ephemeral artifacts, and AI IDE mirrors
     const { ensureGitignoreEntries } = require('../gitignore');
     ensureGitignoreEntries(targetDir);
-    fs.writeFileSync(path.join(targetDir, 'sdds', '.gitkeep'), '', 'utf-8');
+    const gitkeep = path.join(targetDir, 'sdds', '.gitkeep');
+    if (!io.exists(gitkeep)) io.writeFile(gitkeep, '');
 
     // 3. Write AGENTS.md
     const isFront = this.projectType === 'frontend';
@@ -80,7 +64,7 @@ class BaseAdapter {
 This document is the **authoritative law** for AI agents working in this repository.
 Forged by **CLC Kernel: The AI Agent Governance Engine**.
 
-> 🚨 **RULE #0: MANDATORY EXECUTION OVERRIDE RULE (UNBYPASSABLE)**
+> 🚨 **RULE #0: MANDATORY EXECUTION OVERRIDE RULE (NO EXCEPTIONS)**
 > Even when the user issues a direct or urgent fix request ("fix this bug", "fix this error", "quick fix"):
 > YOU ARE STRICTLY FORBIDDEN from modifying source code directly without completing the full quality harness:
 > 1. **Research & Root Cause Analysis:** Investigate tracebacks and inspect affected files before editing.
@@ -94,21 +78,22 @@ Forged by **CLC Kernel: The AI Agent Governance Engine**.
 2. **Plan** — Write an SDD under \`sdds/{change-name}/\`. SDDs live 100% locally and are gitignored.
 3. **Test** (TDD) — Write failing test first (${this.testRunner}).
 4. **Implement** — Make test pass.
-5. **Verify & Audit** — Run \`node tools/audit.js\` or \`python tools/audit.py\`.
+5. **Verify & Audit** — Run \`node tools/audit.js --change {change-name}\` or \`python tools/audit.py --change {change-name}\` (report + receipt in \`sdds/{change-name}/\`; without \`--change\` nothing is written).
 6. **DoD** — Lint, typecheck, tests, coverage, docs, memory.
 7. **Commit** — Pre-commit hook runs automated guards.
 8. **PR** — Generate PR body.
 
 ## 2. Core AI Safeguards (${this.name})
 ${this.getSafeguards().map(s => `- ${s}`).join('\n')}
-`;
+
+${FIRST_SESSION_SECTION}`;
     // Guard: never overwrite a project-customized AGENTS.md.
     if (skipAgentsMd) {
       return;
     }
     const agentsPath = path.join(targetDir, 'AGENTS.md');
-    if (!fs.existsSync(agentsPath)) {
-      fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+    if (!io.exists(agentsPath)) {
+      io.writeFile(agentsPath, agentsContent);
     }
   }
 }

package/src/adapters/django.js

@@ -1,6 +1,6 @@
 /**
  * CLC Kernel — Django Stack Adapter
- * Supports Django apps, pytest-django, Ruff AST, ORM idempotency, and Scope Guard.
+ * Supports Django apps, pytest-django, Ruff, and Python AST layer checks.
  */
 
 const fs = require('fs');
@@ -32,15 +32,15 @@ class DjangoAdapter extends BaseAdapter {
 
   getSafeguards() {
     return [
-      'Flake8 / Ruff AST Python Code Quality Linter',
-      'Clean Architecture AST Guard (Domain -> Application -> Views)',
-      'Database Efficiency & N+1 Performance Guard (select_related / prefetch_related)',
-      'Django ORM Migration Idempotency & Schema Drift Guard',
-      'pytest-django Red-to-Green TDD Validator',
+      'Ruff Python Linter (external CLI)',
+      'Clean Architecture Guard (Python AST: Domain -> Application -> Views)',
+      'N+1 Heuristic (ORM-like calls inside loops, Python AST)',
+      'Django Migration Reversibility protocol (agent-enforced; no migration guard installed for this stack)',
+      'Red→Green TDD Verifier (runs changed tests with pytest)',
       'Secret & Private Key Leak Scanner',
-      'Scope Guardrail (git diff vs SDD affected files)',
+      'Scope protocol (agent-enforced; not checked by a guard)',
       'Educational Audit Gate (05-audit-report.md)',
-      'Memory Guard (Engram / Graphify ADR Sync)'
+      'Memory protocol (agent-enforced; Engram / Graphify optional, not checked by a guard)'
     ];
   }
 
@@ -53,12 +53,13 @@ class DjangoAdapter extends BaseAdapter {
     const baseTools = [
       { name: 'scan_secrets',         language: 'py',       path: 'scan_secrets.py',         command: 'python3 tools/scan_secrets.py',         description: 'Scans for leaked secrets and API keys' },
       { name: 'check_architecture',   language: 'py',       path: 'check_architecture.py',   command: 'python3 tools/check_architecture.py',   description: 'Validates Django layer boundaries' },
-      { name: 'check_db_efficiency',  language: 'py',       path: 'check_db_efficiency.py',  command: 'python3 tools/check_db_efficiency.py',  description: 'Audits database query efficiency and N+1 loop calls' },
-      { name: 'check_custom',          language: 'python',   path: 'check_custom.py',         command: 'python3 tools/check_custom.py',       description: 'Runs user-defined custom rules from .clc-forge.yml' },
-      { name: 'ruff',                 language: 'external', path: '', command: 'python3 -m ruff check .', description: 'Python AST linter', extCLI: 'ruff' },
-      { name: 'manage',               language: 'external', path: '', command: 'python3 manage.py test',  description: 'Django test runner', extCLI: 'manage.py' },
+      { name: 'check_db_efficiency',  language: 'py',       path: 'check_db_efficiency.py',  command: 'python3 tools/check_db_efficiency.py',  description: 'Flags ORM-like calls inside loops (N+1 heuristic)' },
+      { name: 'verify_tdd',           language: 'py',       path: 'verify_tdd.py',           command: 'python3 tools/verify_tdd.py',           description: 'Runs changed tests against HEAD (must fail) and staged code (must pass)' },
+      { name: 'check_custom',          language: 'python',   path: 'check_custom.py',         command: 'python3 tools/check_custom.py',       description: 'Runs user-defined custom rules from .clckernel.yaml' },
+      { name: 'ruff',                 language: 'external', path: '', command: 'python3 -m ruff check .', description: 'Python linter', extCLI: 'ruff', availableIf: 'python3 -m ruff --version', excludeManaged: { flag: '--extend-exclude', extensions: ['.py'] } },
+      { name: 'manage',               language: 'external', path: '', command: 'python3 manage.py test',  description: 'Django test runner', extCLI: 'manage.py', availableIf: '[ -f manage.py ]' },
     ];
-    return this._mergeTechTools(baseTools);
+    return baseTools;
   }
 
   provision(targetDir, config) {

package/src/adapters/fastapi.js

@@ -1,6 +1,6 @@
 /**
  * CLC Kernel — FastAPI Stack Adapter
- * Supports FastAPI apps, pytest, Pydantic V2, Alembic idempotency, and AST Clean Architecture.
+ * Supports FastAPI apps, pytest, Alembic migration reversibility, and Python AST layer checks.
  */
 
 const fs = require('fs');
@@ -29,16 +29,15 @@ class FastApiAdapter extends BaseAdapter {
 
   getSafeguards() {
     return [
-      'Ruff / Flake8 Python AST Code Quality Linter',
-      'Clean Architecture AST Guard (Domain -> Application -> Routes)',
-      'Database Efficiency & N+1 Performance Guard (bulk queries & eager loading)',
-      'Alembic Migration Idempotency & Schema Drift Guard',
-      'Pytest Red-to-Green TDD Validator',
-      'Pydantic V2 Response Schema Validation Guard',
+      'Ruff Python Linter (external CLI)',
+      'Clean Architecture Guard (Python AST: Domain -> Application -> Routes)',
+      'N+1 Heuristic (ORM-like calls inside loops, Python AST)',
+      'Alembic Migration Reversibility Guard (upgrade/downgrade, destructive operations)',
+      'Red→Green TDD Verifier (runs changed tests with pytest)',
       'Secret & Private Key Leak Scanner',
-      'Scope Guardrail (git diff vs SDD affected files)',
+      'Scope protocol (agent-enforced; not checked by a guard)',
       'Educational Audit Gate (05-audit-report.md)',
-      'Memory Guard (Engram / Graphify ADR Sync)'
+      'Memory protocol (agent-enforced; Engram / Graphify optional, not checked by a guard)'
     ];
   }
 
@@ -51,13 +50,15 @@ class FastApiAdapter extends BaseAdapter {
     const baseTools = [
       { name: 'scan_secrets',         language: 'py',       path: 'scan_secrets.py',         command: 'python3 tools/scan_secrets.py',         description: 'Scans for leaked secrets and API keys' },
       { name: 'check_architecture',   language: 'py',       path: 'check_architecture.py',   command: 'python3 tools/check_architecture.py',   description: 'Validates Clean Architecture layer boundaries' },
-      { name: 'check_db_efficiency',  language: 'py',       path: 'check_db_efficiency.py',  command: 'python3 tools/check_db_efficiency.py',  description: 'Audits database query efficiency and N+1 loop calls' },
-      { name: 'check_migrations',     language: 'py',       path: 'check_migrations.py',     command: 'python3 tools/check_migrations.py',     description: 'Checks Alembic migration idempotency' },
-      { name: 'check_custom',          language: 'python',   path: 'check_custom.py',         command: 'python3 tools/check_custom.py',       description: 'Runs user-defined custom rules from .clc-forge.yml' },
-      { name: 'ruff',                 language: 'external', path: '', command: 'python3 -m ruff check .', description: 'Python AST linter', extCLI: 'ruff' },
-      { name: 'pytest',               language: 'external', path: '', command: 'pytest',                   description: 'Test runner', extCLI: 'pytest' },
+      { name: 'check_db_efficiency',  language: 'py',       path: 'check_db_efficiency.py',  command: 'python3 tools/check_db_efficiency.py',  description: 'Flags ORM-like calls inside loops (N+1 heuristic)' },
+      { name: 'check_migrations',     language: 'py',       path: 'check_migrations.py',     command: 'python3 tools/check_migrations.py',     description: 'Checks Alembic migration reversibility (upgrade/downgrade, destructive operations)' },
+      { name: 'verify_tdd',           language: 'py',       path: 'verify_tdd.py',           command: 'python3 tools/verify_tdd.py',           description: 'Runs changed tests against HEAD (must fail) and staged code (must pass)' },
+      { name: 'check_custom',          language: 'python',   path: 'check_custom.py',         command: 'python3 tools/check_custom.py',       description: 'Runs user-defined custom rules from .clckernel.yaml' },
+      { name: 'ruff',                 language: 'external', path: '', command: 'python3 -m ruff check .', description: 'Python linter', extCLI: 'ruff', availableIf: 'python3 -m ruff --version', excludeManaged: { flag: '--extend-exclude', extensions: ['.py'] } },
+      // pytest exits 5 when it collects no tests (a fresh project): that is not a failure.
+      { name: 'pytest',               language: 'external', path: '', command: 'python3 -m pytest || [ $? -eq 5 ]',        description: 'Test runner', extCLI: 'pytest', availableIf: 'python3 -m pytest --version' },
     ];
-    return this._mergeTechTools(baseTools);
+    return baseTools;
   }
 
   provision(targetDir, config) {