harness-everything 0.3.6 → 0.4.1

package/self-evolve/scripts/persist-memory.js

@@ -1,139 +1,272 @@
 #!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+let getWorkspaceRoot;
+try {
+  ({ getWorkspaceRoot } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getWorkspaceRoot = () => null;
+}
 
-const args = process.argv.slice(2);
-const memoryText = args[0];
+// NOTE: this script ships standalone - it is copied whole into every install
+// target. When the canonical workspace resolver is not present, persistence
+// fails closed rather than guessing a project root (issue #42).
 
-if (memoryText === '--help' || memoryText === '-h') {
-  console.log(`Append a short defensive rule to memories/repo/RULES.md.
+const SECRET_PATTERNS = [
+  ['github-token', /\bgh[pousr]_[A-Za-z0-9]{20,}\b/],
+  ['openai-key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/],
+  ['aws-access-key', /\bAKIA[0-9A-Z]{16}\b/],
+  ['private-key', /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/],
+  ['credential-assignment', /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|password|passwd|secret)\s*[:=]\s*["']?[A-Za-z0-9_./+=:-]{8,}/i],
+];
 
-Usage: node persist-memory.js "<insight to remember>"
+const INJECTION_PATTERNS = [
+  ['ignore-prior-instructions', /\bignore\s+(?:all\s+)?(?:previous|prior|above)\s+(?:instructions|messages|rules)\b/i],
+  ['replace-instructions', /\b(?:follow|obey)\s+(?:these|the following)\s+instructions\s+instead\b/i],
+  ['role-override', /\byou\s+are\s+now\b/i],
+  ['instruction-override', /\boverride\s+(?:the\s+)?(?:system|developer|safety|previous|prior)\s+(?:instructions|message|prompt|rules)\b/i],
+  ['system-prompt-exfiltration', /\b(?:reveal|print|show|expose)\s+(?:the\s+)?(?:system|developer)\s+prompt\b/i],
+  ['role-token', /<\|(?:system|developer|assistant)\|>/i],
+  ['jailbreak-marker', /\b(?:jailbreak|prompt[- ]injection)\b/i],
+];
 
-One positional argument - the extracted root cause / rule, written as a universal,
-high-level statement (not a specific file, line number, or variable name). Wrap it
-in quotes if it contains spaces. Appended under a dated heading; never overwrites
-earlier entries.
+function parseArgs(argv) {
+  let memoryText = null;
+  let source = 'manual-unspecified';
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === '--help' || token === '-h') return { help: true, memoryText: null, source };
+    if (token === '--source') {
+      if (index + 1 >= argv.length) throw new Error('--source requires a value');
+      source = argv[++index];
+      continue;
+    }
+    if (token.startsWith('--source=')) {
+      source = token.slice('--source='.length);
+      continue;
+    }
+    if (token.startsWith('-')) throw new Error(`unknown option: ${token}`);
+    if (memoryText !== null) throw new Error('exactly one memory rule positional argument is allowed');
+    memoryText = token;
+  }
+  return { help: false, memoryText, source };
+}
 
-Quality gates:
-- Minimum score of 5/10 required for persistence
-- Deduplication check against existing rules
-- Specificity and actionability scoring`);
-  process.exit(0);
+function normalizeSource(value) {
+  const source = String(value || 'manual-unspecified').trim();
+  if (!source) return 'manual-unspecified';
+  if (/[\r\n\0]/.test(source)) throw new Error('source provenance must be one line');
+  if (source.length > 240) throw new Error('source provenance exceeds 240 characters');
+  const secretReasons = detectReasonCodes(source, SECRET_PATTERNS);
+  if (secretReasons.length > 0) throw new Error(`source provenance rejected by secret screening: ${secretReasons.join(', ')}`);
+  return source;
 }
 
-if (!memoryText) {
-  console.error("Usage: node persist-memory.js \"<insight to remember>\"");
-  process.exit(1);
+function detectReasonCodes(text, patterns) {
+  const reasons = [];
+  for (const [reasonCode, pattern] of patterns) {
+    if (pattern.test(text)) reasons.push(reasonCode);
+  }
+  return reasons;
 }
 
-// Rule quality scoring system
-function scoreRuleQuality(ruleText, existingRules = []) {
-  let score = 0;
-  
-  // Specificity: mentions specific files, errors, or patterns
-  if (/\.\w{2,4}/.test(ruleText)) score += 2; // File extensions
-  if (/Error|Exception|Warning|錯誤|異常|警告/.test(ruleText)) score += 2; // Error patterns
-  if (/\b(test|lint|build|verify|check|測試|檢查)\b/i.test(ruleText)) score += 1; // Verification terms
-  
-  // Actionability: starts with verb, has clear instruction
-  if (/^(Always|Never|Check|Verify|Prefer|Avoid|Use|不要|總是|檢查|驗證|避免|使用)/i.test(ruleText)) score += 3;
-  if (/^(should|must|will|needs? to|ought|應該|必須|需要)/i.test(ruleText)) score += 2;
-  
-  // Uniqueness: not already in RULES.md
-  const isDuplicate = existingRules.some(existing => {
-    const similarity = calculateSimilarity(ruleText, existing);
-    return similarity > 0.7; // 70% similarity threshold
-  });
-  if (!isDuplicate) score += 3;
-  
-  // Length appropriateness (not too short, not too long)
-  if (ruleText.length > 20 && ruleText.length < 200) score += 1;
-  
-  return Math.min(score, 10); // Cap at 10
+function screenMemoryForPersistence(text) {
+  const value = String(text || '');
+  const secretReasonCodes = detectReasonCodes(value, SECRET_PATTERNS);
+  const injectionReasonCodes = detectReasonCodes(value, INJECTION_PATTERNS);
+  return {
+    allowed: secretReasonCodes.length === 0 && injectionReasonCodes.length === 0,
+    secretReasonCodes,
+    injectionReasonCodes,
+  };
 }
 
-// Simple text similarity calculation
 function calculateSimilarity(text1, text2) {
   const words1 = text1.toLowerCase().split(/\s+/);
   const words2 = text2.toLowerCase().split(/\s+/);
-  
   const set1 = new Set(words1);
   const set2 = new Set(words2);
-  
   let intersection = 0;
   for (const word of set1) {
     if (set2.has(word)) intersection++;
   }
-  
   const union = set1.size + set2.size - intersection;
   return union === 0 ? 0 : intersection / union;
 }
 
-// Extract existing rules from RULES.md
+function scoreRuleQuality(ruleText, existingRules = []) {
+  let score = 0;
+  if (/\.\w{2,4}/.test(ruleText)) score += 2;
+  if (/Error|Exception|Warning|錯誤|異常|警告/.test(ruleText)) score += 2;
+  if (/\b(test|lint|build|verify|check|測試|檢查)\b/i.test(ruleText)) score += 1;
+  if (/^(Always|Never|Check|Verify|Prefer|Avoid|Use|不要|總是|檢查|驗證|避免|使用)/i.test(ruleText)) score += 3;
+  if (/^(should|must|will|needs? to|ought|應該|必須|需要)/i.test(ruleText)) score += 2;
+  const isDuplicate = existingRules.some(existing => calculateSimilarity(ruleText, existing) > 0.7);
+  if (!isDuplicate) score += 3;
+  if (ruleText.length > 20 && ruleText.length < 200) score += 1;
+  return Math.min(score, 10);
+}
+
 function extractExistingRules(rulesFile) {
   if (!fs.existsSync(rulesFile)) return [];
-  
   try {
     const content = fs.readFileSync(rulesFile, 'utf8');
     const ruleMatches = content.match(/^- .+$/gm) || [];
-    return ruleMatches.map(rule => rule.substring(2)); // Remove "- " prefix
+    return ruleMatches.map(rule => rule.substring(2));
   } catch (err) {
     return [];
   }
 }
 
-function getWorkspaceRoot() {
-  let dir = path.resolve(process.cwd());
-  while (dir !== path.parse(dir).root) {
-    if (fs.existsSync(path.join(dir, '.git'))) return dir;
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
+function contentHash(text) {
+  return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
 }
 
-// Ensure the memory is written to the project root's memories/repo/ directory
-const currentDir = getWorkspaceRoot();
-const memoryDir = path.join(currentDir, 'memories', 'repo');
-const rulesFile = path.join(memoryDir, 'RULES.md');
+function persistMemory({ memoryText, source = 'manual-unspecified' }) {
+  const ruleText = String(memoryText || '').trim();
+  if (!ruleText) return { ok: false, exitCode: 1, message: 'memory rule is required' };
 
-try {
-  if (!fs.existsSync(memoryDir)) {
-    fs.mkdirSync(memoryDir, { recursive: true });
+  const screening = screenMemoryForPersistence(ruleText);
+  if (!screening.allowed) {
+    const reasons = [...screening.secretReasonCodes, ...screening.injectionReasonCodes];
+    return {
+      ok: false,
+      exitCode: 2,
+      screening,
+      message: `memory rejected by persistence screening: ${reasons.join(', ')}`,
+    };
   }
 
-  // Extract existing rules for deduplication check
+  let provenance;
+  try {
+    provenance = normalizeSource(source);
+  } catch (err) {
+    return { ok: false, exitCode: 2, screening, message: err.message };
+  }
+
+  const currentDir = getWorkspaceRoot();
+  if (!currentDir) {
+    return {
+      ok: false,
+      exitCode: 1,
+      screening,
+      message: 'Cannot persist project memory without a resolved git workspace.',
+    };
+  }
+
+  const memoryDir = path.join(currentDir, 'memories', 'repo');
+  const rulesFile = path.join(memoryDir, 'RULES.md');
   const existingRules = extractExistingRules(rulesFile);
-  
-  // Score the rule quality
-  const qualityScore = scoreRuleQuality(memoryText, existingRules);
-  
+  const qualityScore = scoreRuleQuality(ruleText, existingRules);
   if (qualityScore < 5) {
-    console.error(`[Quality Gate] Rule rejected - score ${qualityScore}/10 (minimum 5 required)`);
-    console.error(`Suggestions to improve:`);
-    console.error(`- Be more specific (mention file types, error patterns)`);
-    console.error(`- Start with action verbs (Always, Never, Check, Verify)`);
-    console.error(`- Ensure the rule is actionable and not already captured`);
-    process.exit(1);
+    return {
+      ok: false,
+      exitCode: 1,
+      screening,
+      qualityScore,
+      message: `Rule rejected - score ${qualityScore}/10 (minimum 5 required)`,
+    };
   }
-  
-  // Check for duplicates
-  const isDuplicate = existingRules.some(existing => {
-    const similarity = calculateSimilarity(memoryText, existing);
-    return similarity > 0.7;
-  });
-  
+
+  const isDuplicate = existingRules.some(existing => calculateSimilarity(ruleText, existing) > 0.7);
   if (isDuplicate) {
-    console.error(`[Quality Gate] Rule rejected - similar rule already exists`);
-    process.exit(1);
+    return {
+      ok: false,
+      exitCode: 1,
+      screening,
+      qualityScore,
+      message: 'Rule rejected - similar rule already exists',
+    };
   }
 
+  fs.mkdirSync(memoryDir, { recursive: true });
   const timestamp = new Date().toISOString().split('T')[0];
-  const formattedMemory = `\n## [${timestamp}] Self-Evolution Insight (Quality: ${qualityScore}/10)\n- ${memoryText}\n`;
-
+  const hash = contentHash(ruleText);
+  const formattedMemory = [
+    '',
+    `## [${timestamp}] Self-Evolution Insight (Quality: ${qualityScore}/10)`,
+    `Source: ${provenance}`,
+    `Content-SHA256: ${hash}`,
+    'Screening: secret=clear; prompt-injection=clear',
+    `- ${ruleText}`,
+    '',
+  ].join('\n');
   fs.appendFileSync(rulesFile, formattedMemory, 'utf8');
-  console.log(`[Success] Memory persisted to ${rulesFile} (Quality: ${qualityScore}/10)`);
-} catch (err) {
-  console.error(`[Error] Failed to write memory: ${err.message}`);
-  process.exit(1);
+  return {
+    ok: true,
+    exitCode: 0,
+    rulesFile,
+    qualityScore,
+    source: provenance,
+    contentSha256: hash,
+    screening,
+  };
+}
+
+function printHelp() {
+  console.log(`Append a short defensive rule to memories/repo/RULES.md.
+
+Usage: node persist-memory.js "<insight to remember>" [--source <provenance>]
+
+The rule must be universal and actionable. --source records where the lesson came
+from (for example issue-85, verifier-stage-3, or manual-review); when omitted the
+source is recorded as manual-unspecified.
+
+Persistence gates:
+- secret-like tokens and credential material are rejected before any write
+- prompt-injection-shaped instructions are rejected before any write
+- source provenance is recorded with a SHA-256 content fingerprint
+- minimum quality score of 5/10 and similarity deduplication still apply`);
+}
+
+if (require.main === module) {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    console.error(`[self-evolve] ${err.message}`);
+    process.exit(1);
+  }
+
+  if (parsed.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (!parsed.memoryText) {
+    console.error('Usage: node persist-memory.js "<insight to remember>" [--source <provenance>]');
+    process.exit(1);
+  }
+
+  try {
+    const result = persistMemory(parsed);
+    if (!result.ok) {
+      const prefix = result.exitCode === 2 ? '[Persistence Screening]' : '[Quality Gate]';
+      console.error(`${prefix} ${result.message}`);
+      if (result.qualityScore !== undefined && result.qualityScore < 5) {
+        console.error('Suggestions to improve:');
+        console.error('- Be more specific (mention file types, error patterns)');
+        console.error('- Start with action verbs (Always, Never, Check, Verify)');
+        console.error('- Ensure the rule is actionable and not already captured');
+      }
+      process.exit(result.exitCode);
+    }
+    console.log(`[Success] Memory persisted to ${result.rulesFile} (Quality: ${result.qualityScore}/10, Source: ${result.source})`);
+  } catch (err) {
+    console.error(`[Error] Failed to write memory: ${err.message}`);
+    process.exit(1);
+  }
 }
+
+module.exports = {
+  calculateSimilarity,
+  contentHash,
+  extractExistingRules,
+  parseArgs,
+  persistMemory,
+  scoreRuleQuality,
+  screenMemoryForPersistence,
+};

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

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
+let getWorkspaceRoot;
+try {
+  ({ getWorkspaceRoot } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getWorkspaceRoot = () => null;
+}
 
-function getWorkspaceRoot() {
-  let dir = path.resolve(process.cwd());
-  while (dir !== path.parse(dir).root) {
-    if (fs.existsSync(path.join(dir, '.git'))) return dir;
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
+const workspaceRoot = getWorkspaceRoot();
+if (!workspaceRoot) {
+  console.error('[self-evolve] Cannot register a dynamic skill without a resolved git workspace.');
+  process.exit(1);
 }
 
 function loadManifestHelper() {
@@ -16,8 +19,8 @@ function loadManifestHelper() {
     path.join(__dirname, '../../scripts/lib/manifest'),
     path.join(__dirname, '../scripts/lib/manifest'),
     path.join(__dirname, '../../../scripts/lib/manifest'),
-    path.join(getWorkspaceRoot(), 'scripts/lib/manifest'),
-    path.join(getWorkspaceRoot(), 'harness-everything/scripts/lib/manifest'),
+    path.join(workspaceRoot, 'scripts/lib/manifest'),
+    path.join(workspaceRoot, 'harness-everything/scripts/lib/manifest'),
   ];
   for (const cand of candidates) {
     try {
@@ -33,7 +36,6 @@ const { getManifestPath, readManifest, writeManifest, recordGeneratedSkill } = l
 
 // Find user home folder
 const userHome = process.env.HOME || process.env.USERPROFILE || '';
-const workspaceRoot = getWorkspaceRoot();
 
 // List of all possible manifest.json home paths
 const manifestHomes = [

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

@@ -13,6 +13,15 @@ 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('=================================================');
@@ -32,9 +41,8 @@ function runNode(label, script, args = [], options = {}) {
   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 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;
@@ -55,14 +63,16 @@ for (const file of jsFiles) {
 }
 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.');
+} 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' },
@@ -72,16 +82,22 @@ if (verifyCheck.status !== 0) {
   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'));
+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'));
 
-// 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)) {
@@ -96,7 +112,6 @@ if (fs.existsSync(fableModeTestPath)) {
   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'));
 

package/skill-creator/SKILL.md

@@ -4,20 +4,18 @@ description: Author, audit, and refactor SKILL.md files against one quality bar
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.6
+  version: 0.4.0
 ---
 
 # 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)
+- Packaging a session insight as a dynamic skill
 
 ## DO NOT USE FOR:
-- Project docs that are not skills — instead use `repo-docs` / `to-spec`
+- Non-skill project docs — use `repo-docs`/`to-spec`
 - Third-party skill installs (find-skills)
 - Code style outside SKILL.md files
 
@@ -28,22 +26,22 @@ SKILL.md authoring and audit.
 | **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. |
+| **Enforcement Gate** | Quality Checklist before registering, incl. USE FOR/DO NOT USE FOR (`<skills-repo-root>/ci/consistency-check.js`). |
 
 ## 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/.
+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 row quotes the description; dynamic below).
+4. Run the Quality Checklist; register (static 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`.
+Only generalizable procedures/enforcement contracts qualify; simple constraints go to `<workspace>/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.
+- 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 on a different task; deprecate rather than silently delete; promote once proven general.
+- Lifecycle: draft → active after firing elsewhere; deprecate, don't delete; promote once proven general.
 
-Deep dive: references/{authoring-workflow,dynamic-generation-contract,quality-checklist}.md
+Deep dive: <this-skill-dir>/references/quality-checklist.md

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

@@ -5,6 +5,7 @@
 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.
+- [ ] **`## USE FOR:` and `## DO NOT USE FOR:` sections present**, each a flat bullet list starting on its own line (`^## USE FOR:` / `^## DO NOT USE FOR:`). Required by `<skills-repo-root>/ci/consistency-check.js` (`npm run test:consistency`) — missing either fails the repo's own consistency gate, not just this checklist.
 - [ ] **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.

package/skill-style/SKILL.md

@@ -4,7 +4,7 @@ description: Apply Harness style guidelines when writing or refactoring SKILL.md
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.6
+  version: 0.4.0
 ---
 
 # Skill Style
@@ -27,7 +27,7 @@ Apply the Harness writing standard when creating or refactoring `SKILL.md` files
 - Checking whether a skill overlaps an existing OS/domain skill
 
 ## DO NOT USE FOR:
-- Interviewing intent, drafting, or testing a skill against real prompts (load `skill-creator/SKILL.md`)
+- Interviewing intent, drafting, or testing a skill against real prompts (load `<skills-repo-root>/skill-creator/SKILL.md`)
 - Routing rules for dynamically generated mid-session skills owned by `self-evolve`
 - Non-Harness skill formats outside `harness-everything`
 
@@ -37,6 +37,6 @@ Apply the Harness writing standard when creating or refactoring `SKILL.md` files
 2. MUST include, in order: title, introduction, Skill Contract, usage, and actionable rules.
 3. MUST use imperative language and name the enforcing command or gate.
 4. MUST avoid overlap with OS-layer routing or domain expertise.
-5. For intent interviews, drafting, and prompt tests, load `skill-creator/SKILL.md`.
+5. For intent interviews, drafting, and prompt tests, load `<skills-repo-root>/skill-creator/SKILL.md`.
 
-Deep dive: `references/style-guide.md`
+Deep dive: `<this-skill-dir>/references/style-guide.md`

package/skill-style/references/style-guide.md

@@ -27,10 +27,36 @@ Every SKILL.md MUST include this table exactly:
 ## 2. Tone & Voice
 - **Anti-Linear / Anti-Prose**: Do not write long paragraphs. Map actions to specific `run_in_terminal` commands.
 - **Absolute Imperatives**: Use "MUST", "MUST NOT", "ALWAYS". Do not use "suggest".
-- **Script-Driven Enforcement**: Do not write "You should check your code". Write "You MUST run `node harness-everything/scripts/verify-gate.js`. If Exit Code 1, you MUST reflect and retry."
+- **Script-Driven Enforcement**: Do not write "You should check your code". Write "You MUST run `node <skills-repo-root>/harness-everything/scripts/verify-gate.js`. If Exit Code 1, you MUST reflect and retry."
 
-## 3. Avoid Functional Overlap
+## 3. Path Notation
+Every path a `SKILL.md` names is checked by `node <skills-repo-root>/ci/reference-check.js`. Every checked path MUST name its base explicitly: use `<this-skill-dir>/` for the skill that names it, `<skills-repo-root>/` for this package, and `<workspace>/` for the user's project.
+
+| Form | Base | Checked? |
+| :--- | :--- | :--- |
+| `<this-skill-dir>/references/x.md`, `<this-skill-dir>/../x.md` | this skill's own directory | yes |
+| `<skills-repo-root>/skill-creator/SKILL.md` | another skill in this package | yes |
+| `<skills-repo-root>/hooks/x.js` | the root of this package | yes |
+| `<workspace>/anywhere/x.md` | a path in the USER's project | no - recorded as intentional |
+
+- **MUST** use one of the three markers. Bare `references/x.md`, `../x.md`, or `ci/x.js` is a hard failure, not a guess.
+- **MUST NOT** invent a new placeholder. An unrecognised one is a hard failure, not a skip - a typo like `<this_folder>/` would otherwise make every path in the file invisible to the gate. Register a genuinely new one in `<skills-repo-root>/ci/reference-check.js`.
+- Use `<workspace>/` for every user-project path. It always wins over any package rule.
+- Markers cost words, but explicit bases prevent a top-level directory from silently changing a path's meaning. Keep the top-level body short and put explanation in the workflow or references rung.
+- A bare filename with no directory (`CONTEXT.md`, `package.json`) is prose and stays unchecked. Give it a directory when you mean a specific file.
+
+## 4. Progressive Disclosure
+
+Keep each skill in three clear rungs:
+
+1. `SKILL.md` contains the trigger, contract, short imperative workflow, `USE FOR`/`DO NOT USE FOR`, and one valid `Deep dive:` entry point. Keep its body at or below 330 words, the local proxy for waza's 500-token limit.
+2. `docs/workflows/<skill>.md` explains the same workflow in plain language. It must contain at least one meaningful Mermaid diagram showing a real sequence, state change, or decision. Complex workflows need separate diagrams for distinct branches; repeated decorative graphs do not count.
+3. `references/` or `guides/` holds detailed procedures, examples, and checklists. Load these files only when the task reaches that detail.
+
+Do not put Mermaid source in `SKILL.md`, copy a full guide into the top-level file, or change a `description:` during a content-only rewrite. The description is a routing API and must remain byte-identical unless a routing change is intentional.
+
+## 5. Avoid Functional Overlap
 - **OS Skills vs. Domain Skills**: Distinguish between the OS layer (which routes and constrains behavior) and the Domain layer (which provides deep technical expertise).
 
-## 4. For the fuller authoring & quality workflow, see `skill-creator`
+## 6. For the fuller authoring & quality workflow, see `skill-creator`
 This document is the terse format spec — the Skill Contract table shape and the tone rules. For interviewing intent, drafting, testing a skill against real prompts, pruning duplication/no-op/sprawl, and the rules for skills `self-evolve` generates dynamically mid-session, load `skill-creator/SKILL.md` instead. It builds on this spec rather than replacing it.