harness-everything 0.2.1 → 0.3.6

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

@@ -1,113 +1,110 @@
-#!/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;
+
+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;
+}
+
+// 1. Syntax-check every shipped JavaScript file.
+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'];
+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)`);
+
+// 1b. Smoke-test the public CLI wrappers.
+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 console.log('  PASS `harness next` produced a routing recommendation.');
+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.');
+
+// 2. Deterministic routing matrix.
+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'));
+
+// 3. Static integrity gates; behavioral evals are validated, not executed.
+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']);
+// 3b. Run Fable model mode contract tests (selector + router separation)
+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.");
+}
+
+// 4. Hook/mechanism checks.
+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,49 @@
----
-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
----
-
-# Skill Creator (Skill Authoring, Audit & Evolution Workflow)
-
-## 📋 Skill Contract
-
-| 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
-
-### 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.
-
-### 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.
-
-- [ ] **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).
-
-## 4. Dynamic Skill Generation Contract (for `self-evolve`)
-
-`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:
-
-- **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.
-
-## 5. Related skills
-
-- `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.
+---
+name: skill-creator
+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.3.6
+---
+
+# Skill Creator
+
+SKILL.md authoring and audit.
+
+## USE FOR:
+- Create a skill from scratch
+- Audit/refactor a SKILL.md; check overlap between skills
+- Packaging a session insight as a dynamic skill (self-evolve)
+
+## DO NOT USE FOR:
+- Project docs that are not skills — instead use `repo-docs` / `to-spec`
+- Third-party skill installs (find-skills)
+- Code style outside SKILL.md files
+
+## Skill Contract
+
+| 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 complete before registering. |
+
+## Authoring Workflow
+
+1. Grep the registry for near-duplicates; the when-to-fire sentence becomes the frontmatter description.
+2. Draft the Contract table first (forces the Enforcement Gate), 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 row quotes the description; dynamic below).
+
+## Dynamic Skill Generation Contract
+
+Only generalizable multi-step procedures or enforcement contracts qualify as skills; simple constraints go to `memories/repo/RULES.md`.
+
+- Location: `.claude/harness-everything/skills/generated/<kebab-case-name>/SKILL.md`
+- Frontmatter beyond name/description: triggers (3-6 keywords), metadata type: dynamic, generated, source, status: draft.
+- Gate: Quality Checklist first.
+- Lifecycle: draft → active after firing on a different task; deprecate rather than silently delete; promote once proven general.
+
+Deep dive: references/{authoring-workflow,dynamic-generation-contract,quality-checklist}.md

package/skill-creator/references/authoring-workflow.md

@@ -0,0 +1,14 @@
+# Authoring Workflow Detail
+
+Keep the Contract table as the source of truth for input, output, state, and
+the enforcement gate. Use short ordered steps for actions and move branch-only
+detail into references or guides.
+
+Before registering a skill, check the Harness registry for overlap, define one
+human-readable frontmatter description, run realistic with/without tests using
+`multi-agent-workspace`, and complete the Quality Checklist. Static skills
+belong in the root catalog and need a routing eval; dynamic skills use the
+generated manifest flow from `self-evolve`.
+
+The canonical multi-agent entrypoint is `multi-agent-workspace`; it owns
+bounded delegation and workspace isolation.

package/skill-creator/references/dynamic-generation-contract.md

@@ -0,0 +1,21 @@
+# Dynamic Skill Generation Contract (for self-evolve)
+
+## 4. Dynamic Skill Generation Contract (for `self-evolve`)
+
+`self-evolve`'s Step 3 optionally packages a hard-won session insight into a new, standalone skill. This process **MUST** only occur if the LLM has judged that the lesson warrants an independent, complex structural skill rather than a simple memory rule:
+
+- **The Judgment Criterion**: Simple constraints or localized tips **MUST** only be written to `memories/repo/RULES.md`. Only highly generalizable, multi-step procedures or custom enforcement contracts (e.g. transaction pooling patterns) should be packaged as a dynamic skill.
+- **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
+  triggers: [<3-6 specific keywords a real prompt would contain, EN and/or 中文 — not generic words like "error" or "using">]
+  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
+  ```
+  `triggers` is what `tier-router.js` matches against to auto-surface this skill in future sessions — pick words specific enough to the actual problem domain (e.g. `connection-pool`, `transaction-batching`), not words generic enough to fire on unrelated prompts. Omitting this field falls back to `register-dynamic-skill.js`'s naive keyword inference from the name/description, which is intentionally conservative and a worse signal than a deliberate list — don't rely on it.
+- **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.

package/skill-creator/references/quality-checklist.md

@@ -0,0 +1,15 @@
+# Quality Checklist (the actual gate)
+
+## 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.
+
+- [ ] **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).