harness-everything 0.2.1 → 0.3.6

package/hooks/scripts/state-persist.js

@@ -1,99 +1,99 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-// Commands that count as "verification ran" for the Stop gate
-// (hooks/scripts/stop-gate.js). Recall over precision: under-blocking the
-// gate is the correct failure direction, so a broad net is fine.
-const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
-
-let inputData = '';
-const timeout = setTimeout(() => {
-  processState(null);
-}, 200);
-
-process.stdin.on('data', chunk => {
-  inputData += chunk;
-});
-
-process.stdin.on('end', () => {
-  clearTimeout(timeout);
-  try {
-    const payload = JSON.parse(inputData.trim());
-    processState(payload);
-  } catch (err) {
-    processState(null);
-  }
-});
-
-function processState(payload) {
-  try {
-    const sessionId = payload && payload.session_id;
-    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), sessionId), 'handoff-state.json');
-
-    // Merge into the existing state rather than replacing it, so the
-    // failure/idle status and the Stop-gate milestones can coexist.
-    let state = { status: 'idle', timestamp: new Date().toISOString() };
-    if (fs.existsSync(stateFile)) {
-      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (e) { /* keep default */ }
-    }
-
-    if (payload) {
-      // Claude Code nests tool output under tool_response, not at the top
-      // level, and uses tool_name rather than tool. A numeric exit code
-      // also isn't guaranteed to be present at all - only trust it when
-      // it's actually a number; fall back to a stderr signal otherwise.
-      const toolResponse = payload.tool_response || {};
-      const stdout = toolResponse.stdout ?? payload.stdout ?? '';
-      const stderr = toolResponse.stderr ?? payload.stderr ?? '';
-      const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
-      const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
-      const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
-      const isFailed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
-      const toolName = payload.tool_name || payload.tool || 'command';
-
-      if (isFailed) {
-        // Truncate output to avoid state bloat
-        let output = (stderrSignal ? stderr : stdout) || payload.output || '';
-        if (output.length > 500) {
-          output = '...' + output.slice(-500);
-        }
-
-        state.status = 'failed';
-        state.timestamp = new Date().toISOString();
-        state.tool = toolName;
-        state.exitCode = exitCode;
-        state.errorSummary = output.trim();
-      } else if (exitCode === 0 && state.status === 'failed') {
-        // Clear failed state or mark as idle/resolved
-        state.lastResolved = { tool: state.tool, timestamp: state.timestamp };
-        state.status = 'idle';
-        state.timestamp = new Date().toISOString();
-        delete state.exitCode;
-        delete state.errorSummary;
-      }
-
-      // Milestones for the Stop gate: when did the last mutation happen, and
-      // has any verification-ish command succeeded since.
-      if (toolName === 'Edit' || toolName === 'Write') {
-        state.lastEditAt = Date.now();
-      } else if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
-        const command = (payload.tool_input && payload.tool_input.command) || '';
-        if (VERIFY_COMMAND_RE.test(command)) {
-          state.lastVerifyAt = Date.now();
-        }
-      }
-
-      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
-    } else {
-      // No standard input payload, or invalid JSON. Just maintain a heartbeat timestamp
-      if (!fs.existsSync(stateFile)) {
-        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
-      }
-    }
-  } catch (err) {
-    // Fail silently in hooks
-  }
-  process.exit(0);
-}
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+// Commands that count as "verification ran" for the Stop gate
+// (hooks/scripts/stop-gate.js). Recall over precision: under-blocking the
+// gate is the correct failure direction, so a broad net is fine.
+const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  processState(null);
+}, 200);
+
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  try {
+    const payload = JSON.parse(inputData.trim());
+    processState(payload);
+  } catch (err) {
+    processState(null);
+  }
+});
+
+function processState(payload) {
+  try {
+    const sessionId = payload && payload.session_id;
+    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), sessionId), 'handoff-state.json');
+
+    // Merge into the existing state rather than replacing it, so the
+    // failure/idle status and the Stop-gate milestones can coexist.
+    let state = { status: 'idle', timestamp: new Date().toISOString() };
+    if (fs.existsSync(stateFile)) {
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (e) { /* keep default */ }
+    }
+
+    if (payload) {
+      // Claude Code nests tool output under tool_response, not at the top
+      // level, and uses tool_name rather than tool. A numeric exit code
+      // also isn't guaranteed to be present at all - only trust it when
+      // it's actually a number; fall back to a stderr signal otherwise.
+      const toolResponse = payload.tool_response || {};
+      const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+      const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+      const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
+      const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+      const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+      const isFailed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
+      const toolName = payload.tool_name || payload.tool || 'command';
+
+      if (isFailed) {
+        // Truncate output to avoid state bloat
+        let output = (stderrSignal ? stderr : stdout) || payload.output || '';
+        if (output.length > 500) {
+          output = '...' + output.slice(-500);
+        }
+
+        state.status = 'failed';
+        state.timestamp = new Date().toISOString();
+        state.tool = toolName;
+        state.exitCode = exitCode;
+        state.errorSummary = output.trim();
+      } else if (exitCode === 0 && state.status === 'failed') {
+        // Clear failed state or mark as idle/resolved
+        state.lastResolved = { tool: state.tool, timestamp: state.timestamp };
+        state.status = 'idle';
+        state.timestamp = new Date().toISOString();
+        delete state.exitCode;
+        delete state.errorSummary;
+      }
+
+      // Milestones for the Stop gate: when did the last mutation happen, and
+      // has any verification-ish command succeeded since.
+      if (toolName === 'Edit' || toolName === 'Write') {
+        state.lastEditAt = Date.now();
+      } else if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
+        const command = (payload.tool_input && payload.tool_input.command) || '';
+        if (VERIFY_COMMAND_RE.test(command)) {
+          state.lastVerifyAt = Date.now();
+        }
+      }
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    } else {
+      // No standard input payload, or invalid JSON. Just maintain a heartbeat timestamp
+      if (!fs.existsSync(stateFile)) {
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+  } catch (err) {
+    // Fail silently in hooks
+  }
+  process.exit(0);
+}

package/hooks/scripts/stop-gate.js

@@ -1,80 +1,80 @@
-#!/usr/bin/env node
-/**
- * Stop Gate (Stop hook - Claude Code only)
- * The pre-delivery gate (verification-loop) was prose-only, and prose decays
- * as context grows. This makes the one check that matters mechanical: ending
- * the turn with edits that were never followed by a successful
- * verification-ish command (test/build/lint - tracked by state-persist.js)
- * while uncommitted changes sit in the tree gets bounced back ONCE per edit
- * batch. Objective facts only; fails open on any error.
- */
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-function decide(payload) {
-  try {
-    // Loop guard: if this stop already resulted from a Stop-hook block,
-    // always let it through - one bounce is the contract, never a cage.
-    if (payload && payload.stop_hook_active) {
-      process.exit(0);
-    }
-
-    const root = getWorkspaceRoot();
-    const sessionDir = getSessionDir(root, payload && payload.session_id);
-    const handoffFile = path.join(sessionDir, 'handoff-state.json');
-    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
-
-    if (!fs.existsSync(handoffFile)) process.exit(0);
-    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
-    const lastEditAt = handoff.lastEditAt || 0;
-    const lastVerifyAt = handoff.lastVerifyAt || 0;
-
-    // No edits this session, or verification already ran after the last edit.
-    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
-
-    // One bounce per edit batch: if we already blocked for this exact edit
-    // timestamp, the model either verified (which moves lastVerifyAt) or
-    // explicitly chose not to - don't nag twice for the same batch.
-    let gate = {};
-    if (fs.existsSync(gateFile)) {
-      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
-    }
-    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
-
-    // Only relevant when unverified work is actually sitting in the tree.
-    const dirty = execSync('git status --porcelain', {
-      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
-    }).trim();
-    if (!dirty) process.exit(0);
-
-    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
-
-    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
-    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
-    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
-    console.error(`This gate bounces at most once per edit batch.`);
-    process.exit(2);
-  } catch (err) {
-    // Fail open - a broken gate must never trap the session.
-    process.exit(0);
-  }
-}
-
-let inputData = '';
-const timeout = setTimeout(() => {
-  decide(null);
-}, 200);
-
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  clearTimeout(timeout);
-  let payload = null;
-  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
-  decide(payload);
-});
-process.stdin.on('error', () => {
-  clearTimeout(timeout);
-  decide(null);
-});
+#!/usr/bin/env node
+/**
+ * Stop Gate (Stop hook - Claude Code only)
+ * The pre-delivery gate (verification-loop) was prose-only, and prose decays
+ * as context grows. This makes the one check that matters mechanical: ending
+ * the turn with edits that were never followed by a successful
+ * verification-ish command (test/build/lint - tracked by state-persist.js)
+ * while uncommitted changes sit in the tree gets bounced back ONCE per edit
+ * batch. Objective facts only; fails open on any error.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function decide(payload) {
+  try {
+    // Loop guard: if this stop already resulted from a Stop-hook block,
+    // always let it through - one bounce is the contract, never a cage.
+    if (payload && payload.stop_hook_active) {
+      process.exit(0);
+    }
+
+    const root = getWorkspaceRoot();
+    const sessionDir = getSessionDir(root, payload && payload.session_id);
+    const handoffFile = path.join(sessionDir, 'handoff-state.json');
+    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
+
+    if (!fs.existsSync(handoffFile)) process.exit(0);
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    const lastEditAt = handoff.lastEditAt || 0;
+    const lastVerifyAt = handoff.lastVerifyAt || 0;
+
+    // No edits this session, or verification already ran after the last edit.
+    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
+
+    // One bounce per edit batch: if we already blocked for this exact edit
+    // timestamp, the model either verified (which moves lastVerifyAt) or
+    // explicitly chose not to - don't nag twice for the same batch.
+    let gate = {};
+    if (fs.existsSync(gateFile)) {
+      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
+    }
+    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
+
+    // Only relevant when unverified work is actually sitting in the tree.
+    const dirty = execSync('git status --porcelain', {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (!dirty) process.exit(0);
+
+    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
+
+    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
+    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
+    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
+    console.error(`This gate bounces at most once per edit batch.`);
+    process.exit(2);
+  } catch (err) {
+    // Fail open - a broken gate must never trap the session.
+    process.exit(0);
+  }
+}
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  decide(null);
+}, 200);
+
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  decide(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  decide(null);
+});

package/hooks/scripts/subagent-scope-guard.js

@@ -1,88 +1,88 @@
-#!/usr/bin/env node
-/**
- * Subagent Scope Guard (PreToolUse + PostToolUse: Task)
- * Grounded in a real incident: a subagent briefed as "read-only, verify and
- * report a verdict" still had full tool access by default and made
- * substantial unrequested edits (a GitBook restructure, ~115 deleted lines)
- * in a large parallel fan-out. It was only caught because someone happened
- * to run `git status` on the whole repo afterward.
- *
- * This hook makes that check automatic instead of relying on remembering to
- * do it: PreToolUse snapshots `git status --porcelain` the first time a Task
- * spawn starts (shared baseline across any parallel/nested Task calls in the
- * same burst), PostToolUse diffs the current status against that baseline
- * and surfaces every changed file - not just the ones the task was expected
- * to touch, since "expected" can't be reliably inferred from a natural-
- * language task brief. It cannot block (the subagent already ran), only
- * makes the diff impossible to miss.
- * Fails open on any error - this is visibility, not a hard gate.
- */
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-function gitStatus(root) {
-  try {
-    return execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch (err) {
-    return null;
-  }
-}
-
-let inputData = '';
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(inputData);
-    if (payload.tool_name !== 'Task') process.exit(0);
-
-    const root = getWorkspaceRoot();
-    const stateFile = path.join(getSessionDir(root, payload.session_id), 'subagent-scope-state.json');
-
-    if (payload.hook_event_name === 'PreToolUse') {
-      // Only set the baseline if one isn't already pending - parallel/nested
-      // Task calls in the same burst share it, so the eventual diff covers
-      // everything the whole burst touched, not just the last one.
-      if (!fs.existsSync(stateFile)) {
-        const status = gitStatus(root);
-        if (status !== null) {
-          fs.writeFileSync(stateFile, JSON.stringify({ baseline: status }, null, 2), 'utf8');
-        }
-      }
-      process.exit(0);
-    }
-
-    if (payload.hook_event_name === 'PostToolUse') {
-      if (!fs.existsSync(stateFile)) process.exit(0);
-
-      const { baseline } = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-      const current = gitStatus(root);
-      if (current === null) process.exit(0);
-
-      const baselineLines = new Set(baseline.split('\n').filter(Boolean));
-      const currentLines = current.split('\n').filter(Boolean);
-      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
-
-      if (newlyChanged.length > 0) {
-        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed since this Task burst started:`);
-        newlyChanged.forEach(line => console.error(`  ${line}`));
-        console.error(`Confirm every one of these was actually in scope before trusting or committing this output.`);
-        console.error(`Do not "git add -A" - stage files explicitly by path so anything unexpected here stays visible.`);
-      }
-
-      // Roll the baseline forward so the next Task burst only reports what's
-      // new since this report, not the same files over and over.
-      fs.writeFileSync(stateFile, JSON.stringify({ baseline: current }, null, 2), 'utf8');
-
-      if (newlyChanged.length > 0) {
-        process.exit(2);
-      }
-      process.exit(0);
-    }
-
-    process.exit(0);
-  } catch (err) {
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+/**
+ * Subagent Scope Guard (PreToolUse + PostToolUse: Task)
+ * Grounded in a real incident: a subagent briefed as "read-only, verify and
+ * report a verdict" still had full tool access by default and made
+ * substantial unrequested edits (a GitBook restructure, ~115 deleted lines)
+ * in a large parallel fan-out. It was only caught because someone happened
+ * to run `git status` on the whole repo afterward.
+ *
+ * This hook makes that check automatic instead of relying on remembering to
+ * do it: PreToolUse snapshots `git status --porcelain` the first time a Task
+ * spawn starts (shared baseline across any parallel/nested Task calls in the
+ * same burst), PostToolUse diffs the current status against that baseline
+ * and surfaces every changed file - not just the ones the task was expected
+ * to touch, since "expected" can't be reliably inferred from a natural-
+ * language task brief. It cannot block (the subagent already ran), only
+ * makes the diff impossible to miss.
+ * Fails open on any error - this is visibility, not a hard gate.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function gitStatus(root) {
+  try {
+    return execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (err) {
+    return null;
+  }
+}
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Task') process.exit(0);
+
+    const root = getWorkspaceRoot();
+    const stateFile = path.join(getSessionDir(root, payload.session_id), 'subagent-scope-state.json');
+
+    if (payload.hook_event_name === 'PreToolUse') {
+      // Only set the baseline if one isn't already pending - parallel/nested
+      // Task calls in the same burst share it, so the eventual diff covers
+      // everything the whole burst touched, not just the last one.
+      if (!fs.existsSync(stateFile)) {
+        const status = gitStatus(root);
+        if (status !== null) {
+          fs.writeFileSync(stateFile, JSON.stringify({ baseline: status }, null, 2), 'utf8');
+        }
+      }
+      process.exit(0);
+    }
+
+    if (payload.hook_event_name === 'PostToolUse') {
+      if (!fs.existsSync(stateFile)) process.exit(0);
+
+      const { baseline } = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      const current = gitStatus(root);
+      if (current === null) process.exit(0);
+
+      const baselineLines = new Set(baseline.split('\n').filter(Boolean));
+      const currentLines = current.split('\n').filter(Boolean);
+      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
+
+      if (newlyChanged.length > 0) {
+        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed since this Task burst started:`);
+        newlyChanged.forEach(line => console.error(`  ${line}`));
+        console.error(`Confirm every one of these was actually in scope before trusting or committing this output.`);
+        console.error(`Do not "git add -A" - stage files explicitly by path so anything unexpected here stays visible.`);
+      }
+
+      // Roll the baseline forward so the next Task burst only reports what's
+      // new since this report, not the same files over and over.
+      fs.writeFileSync(stateFile, JSON.stringify({ baseline: current }, null, 2), 'utf8');
+
+      if (newlyChanged.length > 0) {
+        process.exit(2);
+      }
+      process.exit(0);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});

package/improve-codebase-architecture/SKILL.md

@@ -1,44 +1,40 @@
----
-name: improve-codebase-architecture
-description: Discovers and transforms shallow modules into deep ones to improve testability and AI navigability.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
----
-
-# Improve Codebase Architecture (Deep Architectural Optimization)
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Project shows tech debt, overly coupled modules, or the user requests to "refactor / improve architecture quality". |
-| **Expected Output** | A "Deepening Opportunities" report naming shallow modules and improperly coupled seams, followed (after human approval) by `tdd`-guarded refactoring. |
-| **State Mutations** | Refactors module boundaries/interfaces; may add Characterization Tests before touching legacy code that has no existing coverage. |
-| **Enforcement Gate** | Blind refactoring is **PROHIBITED** — must scan `CONTEXT.md`/ADRs/interfaces first. Refactoring code with no test safety net **MUST** start with Characterization Tests. More than 3 cascading compile errors **MUST** trigger `zoom-out` and rollback, not continued patching. |
-
-Triggered when a project is full of "Tech Debt", modules are overly coupled, or the user requests to "refactor / improve architecture quality". This skill aims to transform "Shallow" modules into "Deep" modules to enhance testability and AI navigability.
-
-## 1. Architectural Exploration & Discovery `[Discover]`
-- **Blind Refactoring Prohibited**: Before proposing any modification suggestions, you MUST first scan `CONTEXT.md`, `docs/adr/`, and core interface definitions (Interfaces/Types).
-- Identify "Shallow Modules" (interfaces that are complex but have very little internal implementation).
-- Identify improperly coupled boundaries (Seams).
-
-## 2. Analysis & Proposal `[Think]`
-Use consistent domain terminology (Module, Interface, Implementation, Depth, Seam, Adapter) to communicate with the human.
-- Submit a "Deepening Opportunities" report to the user.
-- Explicitly point out which modules should be encapsulated and which boundaries (Seams) should be extracted into Adapters.
-
-## 3. Implementation Refactoring `[Try]`
-- After gaining human approval, launch `tdd` mode.
-- **Iron Rule of Refactoring**: MUST be done under the safety net of test coverage. If there are no tests, the first step MUST be to "write Characterization Tests for the legacy code" before modifying the architecture.
-
-## 4. Circuit Breaker & Evolution `[Summarize] & [Self-Evolve]`
-- If refactoring triggers more than 3 cascading compilation errors that cannot be fixed immediately, trigger the `zoom-out` circuit breaker and Rollback.
-- Write the discovered coupling traps into `self-evolve` memory, ensuring future newly generated code does not repeat the same mistakes.
-
-## Deep Reference Guides
-For precise architectural paradigms and deep module analysis, refer to:
-- `improve-codebase-architecture/guides/DEEPENING.md` — Deepening opportunities & modular depth rules
-- `improve-codebase-architecture/guides/INTERFACE-DESIGN.md` — Principles of interface design and seams
-- `improve-codebase-architecture/guides/LANGUAGE.md` — Language-specific refactoring and pattern guidelines
-- `improve-codebase-architecture/guides/HTML-REPORT.md` — Creating visual reports with Mermaid diagrams
+---
+name: improve-codebase-architecture
+description: Discovers and transforms shallow or bloated modules into deep, SRP-compliant ones by splitting oversized objects/functions, extracting seams, and decoupling interfaces.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.6
+---
+
+# Improve Codebase Architecture (Deep & SRP Refactoring)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | "refactor architecture", "split object/class", "apply SRP", tech debt |
+| **Expected Output** | SRP proposal, Characterization Test safety net, TDD-guided extraction. |
+| **State Mutations** | Extracts classes/functions/objects; adds characterization tests. |
+| **Enforcement Gate** | Scan docs first; Characterization Tests before refactoring untested code; >3 cascading errors → rollback + `zoom-out`. |
+
+## Workflow
+
+1. `[Discover]`: no blind refactoring — scan `CONTEXT.md`, `docs/adr/`, core interfaces first. Targets: SRP violations (>300 lines / >10 complexity), shallow modules, coupled seams.
+2. `[Think]`: present the Deepening & SRP proposal (object splitting + seam abstraction) until approved.
+3. `[Try]`: launch `tdd`; Characterization Tests first if legacy code lacks tests; extract incrementally, verifying tests after each change.
+4. `[Summarize]`/`[Self-Evolve]`: >3 cascading errors → rollback + `zoom-out`; record traps in `self-evolve`.
+
+Guides: `improve-codebase-architecture/guides/DEEPENING.md`, `improve-codebase-architecture/guides/INTERFACE-DESIGN.md`, `improve-codebase-architecture/guides/LANGUAGE.md`, `improve-codebase-architecture/guides/HTML-REPORT.md`.
+
+## USE FOR:
+- "refactor this architecture"
+- "split this oversized class"
+- "apply SRP here"
+- "decouple these modules"
+
+## DO NOT USE FOR:
+- Features or bugfixes (use `tdd`)
+- Style-only cleanups with no structure change
+
+Deep dive: guides/refactoring-workflow.md