harness-everything 0.2.2 → 0.4.0

package/self-evolve/scripts/register-dynamic-skill.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+let getWorkspaceRoot;
+try {
+  ({ getWorkspaceRoot } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getWorkspaceRoot = () => null;
+}
+
+const workspaceRoot = getWorkspaceRoot();
+if (!workspaceRoot) {
+  console.error('[self-evolve] Cannot register a dynamic skill without a resolved git workspace.');
+  process.exit(1);
+}
+
+function loadManifestHelper() {
+  const candidates = [
+    path.join(__dirname, '../../scripts/lib/manifest'),
+    path.join(__dirname, '../scripts/lib/manifest'),
+    path.join(__dirname, '../../../scripts/lib/manifest'),
+    path.join(workspaceRoot, 'scripts/lib/manifest'),
+    path.join(workspaceRoot, 'harness-everything/scripts/lib/manifest'),
+  ];
+  for (const cand of candidates) {
+    try {
+      if (fs.existsSync(cand + '.js') || fs.existsSync(cand)) {
+        return require(cand);
+      }
+    } catch (e) {}
+  }
+  throw new Error('[register-dynamic-skill] Failed to locate manifest helper module (scripts/lib/manifest)');
+}
+
+const { getManifestPath, readManifest, writeManifest, recordGeneratedSkill } = loadManifestHelper();
+
+// Find user home folder
+const userHome = process.env.HOME || process.env.USERPROFILE || '';
+
+// List of all possible manifest.json home paths
+const manifestHomes = [
+  path.join(workspaceRoot, '.claude'),
+  path.join(workspaceRoot, '.cursor'),
+  path.join(workspaceRoot, '.github'),
+  path.join(workspaceRoot, '.codex'),
+  path.join(workspaceRoot, '.continue'),
+  path.join(userHome, '.agents'),
+  path.join(userHome, '.claude')
+];
+
+// Helper to parse simple YAML frontmatter without external dependencies
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  const fm = {};
+  let inFM = false;
+  const fmLines = [];
+  
+  for (const line of lines) {
+    if (line.trim() === '---') {
+      if (!inFM) {
+        inFM = true;
+        continue;
+      } else {
+        break;
+      }
+    }
+    if (inFM) {
+      fmLines.push(line);
+    }
+  }
+
+  let currentKey = null;
+  for (const line of fmLines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Check if indent level is substantial (nested list or object)
+    const indent = line.search(/\S/);
+    
+    if (indent === 0) {
+      const match = line.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.*)$/);
+      if (match) {
+        const key = match[1];
+        const val = match[2].trim();
+        
+        let cleanVal = val;
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          cleanVal = val.slice(1, -1);
+        }
+        
+        if (val.startsWith('[') && val.endsWith(']')) {
+          cleanVal = val.slice(1, -1).split(',').map(s => s.trim().replace(/^['"]|['"]$/g, ''));
+        }
+        
+        fm[key] = cleanVal;
+        currentKey = key;
+      }
+    } else if (indent > 0 && currentKey) {
+      // Handle nested properties or array items
+      if (trimmed.startsWith('- ')) {
+        if (!Array.isArray(fm[currentKey])) {
+          fm[currentKey] = [];
+        }
+        fm[currentKey].push(trimmed.slice(2).trim().replace(/^['"]|['"]$/g, ''));
+      } else {
+        const childMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.*)$/);
+        if (childMatch) {
+          if (typeof fm[currentKey] !== 'object' || Array.isArray(fm[currentKey])) {
+            fm[currentKey] = {};
+          }
+          const childKey = childMatch[1];
+          const childVal = childMatch[2].trim().replace(/^['"]|['"]$/g, '');
+          fm[currentKey][childKey] = childVal;
+        }
+      }
+    }
+  }
+  return fm;
+}
+
+function processSkillDir(skillDirPath) {
+  const skillFile = path.join(skillDirPath, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const fm = parseFrontmatter(content);
+  
+  const skillId = fm.name || path.basename(skillDirPath);
+  const description = fm.description || 'No description provided';
+  
+  // Extract custom triggers/tags if defined, or infer them from keywords
+  let triggers = [];
+  if (fm.triggers) {
+    triggers = Array.isArray(fm.triggers) ? fm.triggers : [fm.triggers];
+  } else if (fm.metadata && fm.metadata.triggers) {
+    triggers = Array.isArray(fm.metadata.triggers) ? fm.metadata.triggers : [fm.metadata.triggers];
+  } else {
+    // Fallback only - explicit `triggers:` frontmatter (mandated by
+    // skill-creator/SKILL.md §4) should make this branch rare. Kept
+    // deliberately conservative: only the skill name plus the description's
+    // first sentence (not the whole prose block), a longer stopword list,
+    // and a length-5+ floor, so a generic skill description doesn't spam
+    // tier-router.js with broad words that fire on unrelated prompts.
+    const firstSentence = description.split(/[.!?]/)[0];
+    const STOPWORDS = new Set([
+      'with', 'from', 'this', 'that', 'your', 'about', 'some', 'than', 'then',
+      'prevent', 'resolved', 'skill', 'agent', 'using', 'which', 'these',
+      'those', 'their', 'there', 'where', 'when', 'while', 'after', 'before',
+      'again', 'other', 'every', 'being', 'would', 'could', 'should', 'still',
+      'first', 'never', 'always', 'ensure', 'provide', 'provided'
+    ]);
+    const words = (skillId + ' ' + firstSentence)
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, ' ')
+      .split(/\s+/)
+      .filter(w => w.length >= 5 && !STOPWORDS.has(w));
+    triggers = [...new Set(words)].slice(0, 8);
+  }
+
+  return {
+    id: skillId,
+    dirPath: skillDirPath,
+    description,
+    triggers,
+    metadata: fm.metadata || {}
+  };
+}
+
+function register() {
+  const arg = process.argv[2];
+
+  if (arg === '--help' || arg === '-h') {
+    console.log(`Register self-evolve dynamic skills into every detected platform manifest.json.
+
+Usage:
+  node register-dynamic-skill.js              Scan .claude/harness-everything/skills/generated/ and register every skill found there.
+  node register-dynamic-skill.js <name>        Register only the skill folder named <name> under skills/generated/.
+  node register-dynamic-skill.js <path>        Register the skill folder at this literal path instead.
+
+Each skill folder needs a SKILL.md with 'name' and 'description' frontmatter (plus
+'triggers' - if omitted, triggers are inferred from the name and description, which
+is a conservative fallback, not a substitute for setting them explicitly). Writes to
+every already-bootstrapped platform's manifest.json (.claude/, .cursor/, .github/,
+.codex/, .continue/, plus the user-home ~/.agents and ~/.claude homes).`);
+    process.exit(0);
+  }
+
+  const generatedBaseDir = path.join(workspaceRoot, '.claude', 'harness-everything', 'skills', 'generated');
+  
+  let skillsToRegister = [];
+
+  if (arg) {
+    // Scenario A: Register specific skill ID or path
+    let skillPath = arg;
+    if (!fs.existsSync(skillPath)) {
+      skillPath = path.join(generatedBaseDir, arg);
+    }
+    if (fs.existsSync(skillPath)) {
+      const info = processSkillDir(skillPath);
+      if (info) skillsToRegister.push(info);
+    } else {
+      console.error(`[Error] Dynamic skill folder not found: ${arg}`);
+      process.exit(1);
+    }
+  } else {
+    // Scenario B: Scan whole generated folder
+    if (fs.existsSync(generatedBaseDir)) {
+      const subdirs = fs.readdirSync(generatedBaseDir, { withFileTypes: true });
+      for (const entry of subdirs) {
+        if (entry.isDirectory()) {
+          const dirPath = path.join(generatedBaseDir, entry.name);
+          const info = processSkillDir(dirPath);
+          if (info) skillsToRegister.push(info);
+        }
+      }
+    }
+  }
+
+  if (skillsToRegister.length === 0) {
+    console.log('[Info] No self-evolved dynamic skills found to register.');
+    return;
+  }
+
+  // Write to all detected manifests (auto-creating target directories if in workspace)
+  let count = 0;
+  for (const home of manifestHomes) {
+    const manifestPath = getManifestPath(home);
+    const parentDir = path.dirname(manifestPath);
+    const isRepoHome = home.startsWith(workspaceRoot);
+    if (fs.existsSync(parentDir) || isRepoHome) {
+      fs.mkdirSync(parentDir, { recursive: true });
+      for (const skill of skillsToRegister) {
+        recordGeneratedSkill(manifestPath, skill.id, skill.dirPath, skill.description, skill.triggers);
+      }
+      console.log(`[Success] Registered ${skillsToRegister.length} skill(s) to ${manifestPath}`);
+      count++;
+    }
+  }
+
+  if (count === 0) {
+    // Fallback: If no manifest path's directory existed, write to at least the standard home path
+    const fallbackHome = path.join(userHome, '.agents');
+    const manifestPath = getManifestPath(fallbackHome);
+    for (const skill of skillsToRegister) {
+      recordGeneratedSkill(manifestPath, skill.id, skill.dirPath, skill.description, skill.triggers);
+    }
+    console.log(`[Success] Registered ${skillsToRegister.length} skill(s) to fallback manifest ${manifestPath}`);
+  }
+}
+
+register();

package/self-evolve/scripts/self-regression.js

@@ -1,113 +1,125 @@
-#!/usr/bin/env node
-/**
- * Harness Self-Regression Test Suite
- * Compiles and validates all Javascript files and runs routing verification framework
- * before dynamic evolution / dynamic skills are officially persisted.
- */
-
-const { spawnSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-const projectRoot = path.resolve(__dirname, '..', '..');
-
-console.log("=================================================");
-console.log("     Harness OS - Self-Regression Test Suite     ");
-console.log("=================================================");
-
-let hasErrors = false;
-
-// 1. Walk and syntax check all Javascript files
-console.log("\n[Phase 1] Static Syntax Check...");
-const foldersToScan = ['harness-everything', 'hooks', 'environment-detection', 'self-evolve', 'eval-framework', 'eval-harness', 'scripts', 'bin'];
-const jsFiles = [];
-
-function walkDir(dir) {
-  if (!fs.existsSync(dir)) return;
-  const list = fs.readdirSync(dir);
-  list.forEach(file => {
-    const filePath = path.join(dir, file);
-    const stat = fs.statSync(filePath);
-    if (stat && stat.isDirectory()) {
-      walkDir(filePath);
-    } else if (filePath.endsWith('.js')) {
-      jsFiles.push(filePath);
-    }
-  });
-}
-
-foldersToScan.forEach(folder => {
-  walkDir(path.join(projectRoot, folder));
-});
-
-jsFiles.forEach(file => {
-  const relativePath = path.relative(projectRoot, file);
-  // node --check checks syntax without execution
-  const check = spawnSync('node', ['--check', file]);
-  if (check.status !== 0) {
-    console.error(`  ❌ Syntax Error in ${relativePath}`);
-    console.error(check.stderr.toString().trim());
-    hasErrors = true;
-  } else {
-    console.log(`  ✅ ${relativePath.padEnd(50)} [Valid Syntax]`);
-  }
-});
-
-// 2. Run Tier Verification Framework
-console.log("\n[Phase 2] Routing Verification Check...");
-const runnerPath = path.join(projectRoot, 'eval-framework', 'runner.js');
-if (fs.existsSync(runnerPath)) {
-  const runnerCheck = spawnSync('node', [runnerPath], { stdio: 'inherit' });
-  if (runnerCheck.status !== 0) {
-    console.error("\n  ❌ Routing verification framework failed!");
-    hasErrors = true;
-  } else {
-    console.log("\n  ✅ Routing verification framework 100% Passed!");
-  }
-} else {
-  console.warn("  ⚠️  eval-framework/runner.js not found. Skipping Phase 2.");
-}
-
-// 3. Run Behavioral Test Suite (E2E state-machine transitions, not just syntax)
-console.log("\n[Phase 3] Behavioral Test Suite...");
-const behavioralTestPath = path.join(projectRoot, 'eval-framework', 'behavioral-test.js');
-if (fs.existsSync(behavioralTestPath)) {
-  const behavioralCheck = spawnSync('node', [behavioralTestPath], { stdio: 'inherit', cwd: projectRoot });
-  if (behavioralCheck.status !== 0) {
-    console.error("\n  ❌ Behavioral test suite failed!");
-    hasErrors = true;
-  } else {
-    console.log("\n  ✅ Behavioral test suite 100% Passed!");
-  }
-} else {
-  console.warn("  ⚠️  eval-framework/behavioral-test.js not found. Skipping Phase 3.");
-}
-
-// 4. Run Mechanism Test Suite (VERIFICATION.md §2 hook contract, automated)
-console.log("\n[Phase 4] Mechanism Test Suite (Claude Code hooks)...");
-const mechanismTestPath = path.join(projectRoot, 'eval-framework', 'mechanism-test.js');
-if (fs.existsSync(mechanismTestPath)) {
-  const mechanismCheck = spawnSync('node', [mechanismTestPath], { stdio: 'inherit', cwd: projectRoot });
-  if (mechanismCheck.status !== 0) {
-    console.error("\n  ❌ Mechanism test suite failed!");
-    hasErrors = true;
-  } else {
-    console.log("\n  ✅ Mechanism test suite 100% Passed!");
-  }
-} else {
-  console.warn("  ⚠️  eval-framework/mechanism-test.js not found. Skipping Phase 4.");
-}
-
-// 5. Final verdict
-console.log("\n=================================================");
-if (hasErrors) {
-  console.error(" ❌ REGRESSION DETECTED! Self-evolution rejected.");
-  console.error(" Please fix the errors listed above before persisting changes.");
-  console.log("=================================================");
-  process.exit(1);
-} else {
-  console.log(" 🎉 SUCCESS! All self-regression checks passed 100%.");
-  console.log(" Dynamic skills and memories are safe to be committed.");
-  console.log("=================================================");
-  process.exit(0);
-}
+#!/usr/bin/env node
+/**
+ * Harness Self-Regression Test Suite.
+ *
+ * This is the free, deterministic gate. Model sessions remain on-demand;
+ * their results must not be confused with a local tracker simulation.
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const projectRoot = path.resolve(__dirname, '..', '..');
+let hasErrors = false;
+
+let pkgName = null;
+try {
+  pkgName = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')).name;
+} catch (e) {}
+if (pkgName !== 'harness-everything') {
+  console.log('self-regression.js validates the Harness-everything repo\'s own CI; this workspace is not that repo, so there is nothing to check here. Skipping.');
+  process.exit(0);
+}
+
+console.log('=================================================');
+console.log('     Harness OS - Self-Regression Test Suite     ');
+console.log('=================================================');
+
+function runNode(label, script, args = [], options = {}) {
+  const result = spawnSync('node', [script, ...args], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    ...options,
+  });
+  if (result.status !== 0) {
+    console.error(`  FAIL ${label}`);
+    hasErrors = true;
+  } else {
+    console.log(`  PASS ${label}`);
+  }
+  return result;
+}
+
+console.log('\n[Phase 1] Static Syntax Check...');
+const foldersToScan = ['harness-everything', 'hooks', 'environment-detection', 'self-evolve', 'ci', 'eval-harness', 'scripts', 'bin', 'to-spec', 'to-tickets', 'find-skills', 'fable-mode', 'multi-agent-workspace'];
+const jsFiles = [];
+function walkDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const file of fs.readdirSync(dir)) {
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isDirectory()) walkDir(filePath);
+    else if (filePath.endsWith('.js')) jsFiles.push(filePath);
+  }
+}
+for (const folder of foldersToScan) walkDir(path.join(projectRoot, folder));
+for (const file of jsFiles) {
+  const check = spawnSync('node', ['--check', file]);
+  if (check.status !== 0) {
+    console.error(`  FAIL syntax: ${path.relative(projectRoot, file)}`);
+    console.error(check.stderr.toString().trim());
+    hasErrors = true;
+  }
+}
+console.log(`  PASS syntax: ${jsFiles.length} JavaScript file(s)`);
+
+console.log('\n[Phase 1b] CLI Command Smoke Test...');
+const cliPath = path.join(projectRoot, 'bin', 'cli.js');
+const nextCheck = spawnSync('node', [cliPath, 'next', 'add a new login endpoint with tests'], { cwd: projectRoot });
+if (nextCheck.status !== 0 || !nextCheck.stdout.toString().includes('RECOMMENDED TIER')) {
+  console.error('  FAIL `harness next` did not produce a routing recommendation.');
+  hasErrors = true;
+} else if (!nextCheck.stdout.toString().includes('REQUIRED HARNESS INVARIANTS')) {
+  console.error('  FAIL `harness next` did not establish the invariant-first kernel contract.');
+  hasErrors = true;
+} else console.log('  PASS `harness next` produced routing + invariant contract.');
+const verifyCheck = spawnSync('node', [cliPath, 'verify'], {
+  cwd: projectRoot,
+  env: { ...process.env, HARNESS_SKIP_PROJECT_CHECKS: '1' },
+});
+if (verifyCheck.status !== 0) {
+  console.error('  FAIL `harness verify` exited non-zero on a skipped check.');
+  hasErrors = true;
+} else console.log('  PASS `harness verify` exited 0 on a skipped check.');
+
+console.log('\n[Phase 2] Routing Verification Check...');
+runNode('routing matrix', path.join(projectRoot, 'ci', 'runner.js'));
+runNode('skill route coverage', path.join(projectRoot, 'ci', 'skill-routing-check.js'));
+runNode('invariant-first routing contract', path.join(projectRoot, 'ci', 'invariant-routing.test.js'));
+runNode('workflow-plan structured contract', path.join(projectRoot, 'ci', 'router-workflow-plan.test.js'));
+runNode('explicit parallel safety contract', path.join(projectRoot, 'ci', 'router-phase2-safety.test.js'));
+runNode('workflow-plan consumers', path.join(projectRoot, 'ci', 'workflow-plan-consumers.test.js'));
+runNode('workflow-plan consumer edge contracts', path.join(projectRoot, 'ci', 'workflow-plan-consumers-edge.test.js'));
+runNode('phase 4 ensemble/memory evidence', path.join(projectRoot, 'ci', 'phase4-ensemble-memory.test.js'));
+runNode('phase 5 pre-action gate', path.join(projectRoot, 'ci', 'action-gate.test.js'));
+runNode('phase 5 platform evidence boundary', path.join(projectRoot, 'ci', 'action-gate-platform-doc.test.js'));
+runNode('issue #99 runtime correctness', path.join(projectRoot, 'ci', 'issue99-runtime.test.js'));
+
+console.log('\n[Phase 3] Skill Reference and Behavioral Case Checks...');
+runNode('skill reference check', path.join(projectRoot, 'ci', 'reference-check.js'));
+runNode('behavioral case validation', path.join(projectRoot, 'behavioral-evals', 'run.js'), ['validate']);
+console.log('\n[Phase 3b] Fable Model Mode Contract Tests...');
+const fableModeTestPath = path.join(projectRoot, 'ci', 'fable-mode-test.js');
+if (fs.existsSync(fableModeTestPath)) {
+  const fableModeCheck = spawnSync('node', [fableModeTestPath], { stdio: 'inherit', cwd: projectRoot });
+  if (fableModeCheck.status !== 0) {
+    console.error("\n  ❌ Fable model mode contract suite failed!");
+    hasErrors = true;
+  } else {
+    console.log("\n  ✅ Fable model mode contract suite 100% Passed!");
+  }
+} else {
+  console.warn("  ⚠️  ci/fable-mode-test.js not found. Skipping Phase 3.");
+}
+
+console.log('\n[Phase 4] Mechanism Test Suite (Claude Code hooks)...');
+runNode('mechanism suite', path.join(projectRoot, 'ci', 'mechanism-test.js'));
+
+console.log('\n=================================================');
+if (hasErrors) {
+  console.error(' FAIL: self-regression found one or more problems.');
+  console.log('=================================================');
+  process.exit(1);
+}
+console.log(' PASS: all deterministic self-regression checks passed.');
+console.log('=================================================');

package/skill-creator/SKILL.md

@@ -1,91 +1,47 @@
 ---
 name: skill-creator
-description: Author, audit, and refactor SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research. Use when creating a new skill from scratch, reviewing or refactoring an existing SKILL.md, checking whether two skills overlap, or when self-evolve needs to package a session's learning into a durable dynamic skill.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Author, audit, and refactor SKILL.md files against one quality bar — the Skill Contract format. Use when creating a new skill, refactoring a SKILL.md, checking overlap, or packaging an insight as a dynamic skill.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
-# Skill Creator (Skill Authoring, Audit & Evolution Workflow)
+# Skill Creator
 
-## 📋 Skill Contract
+## USE FOR:
+- Create a skill from scratch
+- Audit/refactor a SKILL.md; check overlap between skills
+- Packaging a session insight as a dynamic skill
 
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Creating a new skill from scratch; auditing/refactoring an existing `SKILL.md`; `self-evolve`'s Step 3 packaging a session's insight into a durable dynamic skill. Input: a task description, an existing SKILL.md, or a root-cause insight from self-evolve. |
-| **Expected Output** | A `SKILL.md` that passes the Quality Checklist (§3) — static skills at `<skill-name>/SKILL.md` with a `harness-everything` registry row, dynamic skills at `.harness/skills/generated/<skill-name>/SKILL.md` with lifecycle metadata (§4). |
-| **State Mutations** | Writes/edits `<skill>/SKILL.md` (+ optional `guides/`/`references/`); for new static skills, adds one row to `harness-everything/SKILL.md` §5 and, if keyword-routable, one line to `tier-router.js`'s `recommendedGuides`. |
-| **Enforcement Gate** | A new or edited `SKILL.md` **MUST NOT** be registered or persisted until every item in the Quality Checklist (§3) is checked off — for dynamic skills this is self-evolve's actual persistence gate, not optional polish. |
-
-`skill-style/SKILL.md` defines *the shape* a SKILL.md must take (the Skill Contract table, the imperative tone) but not *how to get there well* — how to size a skill, when to push detail into a reference file, how to tell a real enforcement gate from a restated default, or where a rule belongs before it starts drifting across three files. Those questions come from two sources studied for this skill: [`writing-great-skills`](../mattpocock-skills/skills/productivity/writing-great-skills/SKILL.md) and Anthropic's own `skill-creator`. Neither is followed blindly — §1 says where Harness's own conventions override them, and why.
-
-## 1. Two philosophies, reconciled
-
-Harness gets predictability from a **physical** mechanism: the Skill Contract table's Enforcement Gate row, backed by a script that exits non-zero. External skill-writing research gets predictability from a **cognitive** mechanism: minimal context load, leading words, explaining *why* instead of just forbidding. Both are real and both are validated — see the 2026-07-22 skill quality audit for the evidence — and they don't actually conflict where it counts:
-
-- **Keep** the Skill Contract table and `MUST`/`PROHIBITED` for anything with a real Enforcement Gate: an irreversible action, a script that can exit non-zero, a state mutation another skill depends on. That's a hard guardrail; state it as one.
-- **Don't** reach for `MUST`/`PROHIBITED` as the default tone for style preferences with no gate behind them — "don't write long paragraphs" doesn't need to be a `MUST NOT`; say what good output looks like instead. Every imperative not backed by an actual gate is a candidate for rewriting positively.
-- **Always** apply the parts with no philosophical conflict at all: don't duplicate a meaning across files, don't restate what the model already does by default, push detail behind a pointer once a skill grows past what every reader needs inline, and reuse this repo's own leading words (`Tier 1/2/3`, `circuit breaker`/`zoom out`, `Rule of 3`, `Red/Green/Refactor`) instead of coining new ones for the same concept.
-
-Full glossary and worked examples from both sources: `references/quality-principles.md`.
-
-## 2. Authoring workflow
+## DO NOT USE FOR:
+- Non-skill project docs — use `repo-docs`/`to-spec`
+- Third-party skill installs (find-skills)
+- Code style outside SKILL.md files
 
-### Step 1 — Capture intent (before writing a word of SKILL.md)
-Answer these, pulling from the conversation first if it already has the answers:
-1. What should this skill make the agent do that it wouldn't do by default?
-2. What's the *one* canonical sentence describing when it fires? This sentence becomes the frontmatter `description` — and nothing else. Don't let the registry row or `tier-router.js` invent independent wording later: the audit report §1.2 found the same skill carrying two different one-line descriptions inside `tier-router.js` itself, because nobody treated the frontmatter line as the source of truth.
-3. Which Tier does it belong to, or is it an always-on discipline / meta skill outside the tier system?
-4. Does an existing skill already own this ground? Grep `harness-everything/SKILL.md` §5 first — a near-duplicate skill is worse than a slightly-too-broad existing one.
+## Skill Contract
 
-### Step 2 — Draft
-Write the Skill Contract table first — it forces you to know the Enforcement Gate before you write a paragraph. Then the body, sized by the information hierarchy:
-- **Steps** (ordered, each ending on a checkable completion criterion) for anything the agent *does*, in order.
-- **Flat reference** (a rule table, a decision list) for anything the agent *consults*. A skill can be all steps, all reference, or both — a flat rule table is a legitimate shape, not a smell.
-- Past ~100-150 lines of body, or once a piece of detail is only needed on some branches rather than every invocation, push it to `guides/` or `references/` with a pointer sentence that says *when* to open it, not a bare link. Past 300 lines in a reference file, add a table of contents. `git-commit`, `tdd`, `repo-docs`, and `improve-codebase-architecture` already do this well — copy their shape.
-
-### Step 3 — Test against real prompts
-Don't ship on vibes alone. Write 2-3 prompts a real user would actually type — not "test the skill," the kind of message that should trigger it. Using this repo's own `create-agent-launcher`, spawn one subagent *with* the draft skill loaded and one *without* (baseline), same prompt, and compare. This is the same with/without comparison Anthropic's `skill-creator` runs through a Python eval-viewer — Harness doesn't need a second toolchain for it; `create-agent-launcher` already does resource-isolated subagent spawning. Read both transcripts, not just final outputs — repeated dead-end exploration in the with-skill transcript is a sign the skill under-specifies something, not that the model is weak.
-
-Full adapted testing loop — when to bother, what to look for in transcripts, how a router-based system checks trigger phrasing without a native autonomous picker: `references/testing-workflow.md`.
-
-### Step 4 — Prune, then register
-Run the Quality Checklist (§3). Then:
-- **Static skill**: add one row to `harness-everything/SKILL.md` §5 (Layer + "Activated when," quoting the frontmatter description rather than rewriting it), and if the trigger is keyword-detectable, one line to the matching keyword block in `harness-everything/scripts/tier-router.js`.
-- **Dynamic skill** (from `self-evolve`): follow §4 instead — different location, different lifecycle, same checklist.
-
-## 3. Quality Checklist (the actual gate)
-
-A skill isn't done until every line here is true. This is deliberately a flat checklist, not steps — check them in any order, but check all of them.
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | New skill; SKILL.md audit; self-evolve packaging. |
+| **Expected Output** | SKILL.md passing the Quality Checklist. |
+| **State Mutations** | Writes `<skill>/SKILL.md`; updates registry/generated folder. |
+| **Enforcement Gate** | Quality Checklist before registering, incl. USE FOR/DO NOT USE FOR (`<skills-repo-root>/ci/consistency-check.js`). |
 
-- [ ] **Skill Contract table present and accurate** — all four rows; Enforcement Gate names a real script/exit-code or an explicit "None" if the skill is pure reference.
-- [ ] **Single source of truth**: the frontmatter `description` is the *only* place this skill's purpose is originally written. The registry row and any `tier-router.js` line quote or tightly paraphrase it — they don't independently re-describe the skill.
-- [ ] **No block over ~5 lines duplicated verbatim elsewhere** — in this file or in another always/near-always-loaded skill. (`install-cognitive-os` vs. `harness-everything`'s 33-line ADHD-output block, flagged in the audit report, is the canonical counter-example — don't add a second one.)
-- [ ] **Every `MUST`/`MUST NOT`/`PROHIBITED` has a real gate behind it**, or is rewritten as a positive statement of the target behavior. A prohibition with no gate and no "why" sentence next to it is a smell, not a strength.
-- [ ] **No no-op lines** — for each imperative sentence, ask whether it changes behavior versus what the model already does by default. ("Be thorough" reads as a no-op; a concrete completion criterion or a stronger leading word doesn't.)
-- [ ] **Body fits the information hierarchy** — steps for ordered action, flat reference for rules, detail past what every branch needs pushed to `guides/`/`references/` with a "when to open this" pointer.
-- [ ] **Reuses existing leading words** (`Tier 1/2/3`, `circuit breaker`/`zoom out`, `Rule of 3`, `Red/Green/Refactor`, `Discover > Think > Try > Summarize > Record`) instead of naming a new concept for something this repo already has a word for.
-- [ ] **Completion criteria are checkable** — tied to an exit code, a file's existence, a grep result, or explicit human confirmation, not "when it feels done."
-- [ ] **Description reads as a human-facing sentence**, not just a trigger-phrase list — `scripts/installer.js`'s interactive picker prints it next to a checkbox for a person deciding whether to install this skill; that's its real first reader in this architecture (audit report §2.1).
+## Authoring Workflow
 
-## 4. Dynamic Skill Generation Contract (for `self-evolve`)
+1. Grep the registry for near-duplicates; the when-to-fire sentence becomes the description.
+2. Draft the Contract table first (forces the Enforcement Gate), then `## USE FOR:`/`## DO NOT USE FOR:`, then steps/flat reference; push branch-only detail to references/.
+3. A/B-test via `multi-agent-workspace` subagents; read both transcripts.
+4. Run the Quality Checklist; register (static quotes the description; dynamic below).
 
-`self-evolve`'s Step 3 packages a hard-won session insight into a new, standalone skill. That new skill **MUST** go through this skill, not be hand-written inline:
+## Dynamic Skill Generation Contract
 
-- **Location**: `.claude/harness-everything/skills/generated/<kebab-case-name>/SKILL.md` — not the repo root. `.claude/harness-everything/skills` is already a scope the installer recognizes (`scripts/lib/skills.js`'s `getInstalledSkills`), which keeps dynamically-generated skills discoverable without mixing them into the reviewed, static skill set at the repo root. `generated/` is deliberately excluded from the installer's manifest-tracked, bulk-removable skill set — these are the user's own accumulated learning, not package content, so "uninstall skills" must never sweep them.
-- **Required frontmatter**, in addition to `name`/`description`:
-  ```yaml
-  metadata:
-    type: dynamic
-    generated: <YYYY-MM-DD>
-    source: <one-line pointer to the session/root-cause that produced it, e.g. "zoom-out recovery, 2026-07-22, ORM connection-pool exhaustion">
-    status: draft
-  ```
-- **Gate**: run the Quality Checklist (§3) before the skill file is written. A dynamic skill skips human PR review by design, so this checklist is the only review it gets — don't skip it because the insight "feels obviously right" in the moment; that's exactly the state self-evolve is triggered from.
-- **Lifecycle**: `status: draft` at birth. Promote to `status: active` once it fires successfully in a *different* task than the one that produced it — a skill that has only proven itself on the bug that spawned it hasn't proven generality yet. If a dynamic skill goes unused or stops matching reality, mark `status: deprecated` rather than deleting it silently — deleting is fine once something else supersedes it, but a silent disappearance is harder to debug later than a stale-but-labeled file.
-- **Promotion to static**: once a dynamic skill has proven itself general — used successfully across genuinely unrelated tasks, not repeated instances of the same bug — promote it: move it to the repo root, drop the `metadata.type: dynamic` block, and register it in `harness-everything/SKILL.md` §5 like any other skill. At that point it's subject to the same review/PR discipline as everything else here.
+Only generalizable procedures/enforcement contracts qualify; simple constraints go to `<workspace>/memories/repo/RULES.md`.
 
-## 5. Related skills
+- Location: `<workspace>/.claude/harness-everything/skills/generated/<kebab-case-name>/SKILL.md`
+- Frontmatter: triggers (3-6 keywords), metadata type/generated/source/status: draft.
+- Gate: Quality Checklist first.
+- Lifecycle: draft → active after firing elsewhere; deprecate, don't delete; promote once proven general.
 
-- `skill-style/SKILL.md` — the terse Skill Contract format spec this skill builds on. Read it if you just need the table shape, not the full workflow.
-- `create-agent-launcher/SKILL.md` — used in §2 Step 3 to spawn with/without-skill test subagents.
-- `self-evolve/SKILL.md` — the caller for §4; it loads this skill rather than duplicating the Dynamic Skill Generation Contract inline.
+Deep dive: <this-skill-dir>/references/quality-checklist.md