harness-everything 0.15.0 → 0.16.1

package/scripts/codex-hooks-compat.js

@@ -0,0 +1,521 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SOURCE_PLUGIN_ROOT = path.join(PACKAGE_ROOT, 'plugins', 'harness-everything');
+const PACKAGE_VERSION = require(path.join(PACKAGE_ROOT, 'package.json')).version;
+const MANIFEST_SCHEMA = 1;
+const MANIFEST_MODE = 'codex-user-hooks-compat';
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+}
+
+function stableJson(value) {
+  return JSON.stringify(stable(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function treeHash(root) {
+  if (fs.lstatSync(root).isSymbolicLink()) {
+    throw new Error('refusing linked compatibility runtime: ' + root);
+  }
+  const rows = [];
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(root, full).replace(/\\/g, '/');
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) rows.push(rel + ':' + sha256(fs.readFileSync(full)));
+      else if (entry.isSymbolicLink()) throw new Error('refusing linked compatibility runtime entry: ' + full);
+    }
+  }
+  walk(root);
+  return sha256(rows.join('\n'));
+}
+
+function entryHash(entry) {
+  return sha256(stableJson(entry));
+}
+
+function defaultCodexHome(env = process.env) {
+  return path.resolve(env.CODEX_HOME || path.join(os.homedir(), '.codex'));
+}
+
+function pathsFor(codexHome, sourceHash = null) {
+  const home = path.resolve(codexHome);
+  const ownerRoot = path.join(home, 'harness-everything', 'compat-hooks');
+  const runtimeId = sourceHash ? PACKAGE_VERSION + '-' + sourceHash.slice(0, 12) : null;
+  return {
+    codexHome: home,
+    hooksFile: path.join(home, 'hooks.json'),
+    configFile: path.join(home, 'config.toml'),
+    ownerRoot,
+    manifestFile: path.join(ownerRoot, 'manifest.json'),
+    runtimeRoot: path.join(ownerRoot, 'runtime'),
+    runtimeDir: runtimeId ? path.join(ownerRoot, 'runtime', runtimeId) : null,
+  };
+}
+
+function readJsonObject(file, fallback) {
+  if (!fs.existsSync(file)) return fallback;
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(file + ' must contain a JSON object');
+  }
+  return parsed;
+}
+
+function readHooksFile(file) {
+  const data = readJsonObject(file, { hooks: {} });
+  if (data.hooks === undefined) data.hooks = {};
+  if (!data.hooks || typeof data.hooks !== 'object' || Array.isArray(data.hooks)) {
+    throw new Error(file + ' has invalid hooks object');
+  }
+  for (const [event, entries] of Object.entries(data.hooks)) {
+    if (!Array.isArray(entries)) throw new Error(file + ' hooks.' + event + ' must be an array');
+  }
+  return data;
+}
+
+function samePath(left, right) {
+  const normalize = value => {
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  };
+  return normalize(left) === normalize(right);
+}
+
+function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative !== '' && relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}
+
+function assertOwnedPath(codexHome, target, label) {
+  const home = path.resolve(codexHome);
+  const resolvedTarget = path.resolve(target);
+  if (!samePath(home, resolvedTarget) && !isPathInside(home, resolvedTarget)) {
+    throw new Error('refusing outside Codex home ' + label + ': ' + target);
+  }
+  if (!fs.existsSync(home)) return;
+
+  const realpath = fs.realpathSync.native || fs.realpathSync;
+  const physicalHome = realpath(home);
+  const relative = path.relative(home, resolvedTarget);
+  let current = home;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error('refusing linked ' + label + ': ' + current);
+    }
+    const physical = realpath(current);
+    if (!samePath(physicalHome, physical) && !isPathInside(physicalHome, physical)) {
+      throw new Error('refusing outside Codex home ' + label + ': ' + current);
+    }
+  }
+}
+
+function assertCompatibilityPaths(paths) {
+  for (const [label, target] of [
+    ['hooks file', paths.hooksFile],
+    ['compatibility owner', paths.ownerRoot],
+    ['compatibility manifest', paths.manifestFile],
+    ['compatibility runtime root', paths.runtimeRoot],
+    ['compatibility runtime', paths.runtimeDir],
+  ]) {
+    if (target) assertOwnedPath(paths.codexHome, target, label);
+  }
+}
+
+function readManifest(file, expectedPaths = null) {
+  if (!fs.existsSync(file)) return null;
+  const data = readJsonObject(file, null);
+  if (data.schemaVersion !== MANIFEST_SCHEMA ||
+      data.package !== 'harness-everything' ||
+      data.mode !== MANIFEST_MODE ||
+      typeof data.packageVersion !== 'string' ||
+      !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.packageVersion) ||
+      typeof data.sourcePluginSha256 !== 'string' ||
+      !/^[0-9a-f]{64}$/.test(data.sourcePluginSha256) ||
+      typeof data.runtimeDir !== 'string' ||
+      typeof data.hooksFile !== 'string' ||
+      typeof data.createdHooksFile !== 'boolean' ||
+      !Array.isArray(data.entries)) {
+    throw new Error('refusing unknown/corrupt Harness compatibility manifest: ' + file);
+  }
+  if (!expectedPaths) return data;
+
+  const expectedRuntimeDir = path.join(
+    expectedPaths.runtimeRoot,
+    data.packageVersion + '-' + data.sourcePluginSha256.slice(0, 12)
+  );
+  assertOwnedPath(expectedPaths.codexHome, data.runtimeDir, 'manifest runtime');
+  if (!samePath(data.hooksFile, expectedPaths.hooksFile) ||
+      !isPathInside(expectedPaths.runtimeRoot, data.runtimeDir) ||
+      !samePath(data.runtimeDir, expectedRuntimeDir) ||
+      !fs.existsSync(data.runtimeDir) ||
+      treeHash(data.runtimeDir) !== data.sourcePluginSha256) {
+    throw new Error('refusing unknown/corrupt Harness compatibility manifest: ' + file);
+  }
+
+  const allowed = new Map();
+  for (const record of hookEntriesFrom(path.resolve(data.runtimeDir), path.resolve(data.runtimeDir))) {
+    const key = record.event + '\0' + record.hash;
+    if (!allowed.has(key)) allowed.set(key, []);
+    allowed.get(key).push(stableJson(record.entry));
+  }
+  for (const record of data.entries) {
+    if (!record || typeof record !== 'object' || Array.isArray(record) ||
+        typeof record.event !== 'string' || !record.event ||
+        typeof record.hash !== 'string' || !/^[0-9a-f]{64}$/.test(record.hash) ||
+        !record.entry || typeof record.entry !== 'object' || Array.isArray(record.entry) ||
+        entryHash(record.entry) !== record.hash) {
+      throw new Error('refusing unknown/corrupt Harness compatibility manifest: ' + file);
+    }
+    const key = record.event + '\0' + record.hash;
+    const candidates = allowed.get(key) || [];
+    const serialized = stableJson(record.entry);
+    const match = candidates.indexOf(serialized);
+    if (match === -1) {
+      throw new Error('refusing unknown/corrupt Harness compatibility manifest: ' + file);
+    }
+    candidates.splice(match, 1);
+  }
+  return data;
+}
+
+function atomicWriteFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = file + '.' + process.pid + '.tmp';
+  try {
+    fs.writeFileSync(temp, value);
+    fs.renameSync(temp, file);
+  } finally {
+    try { if (fs.existsSync(temp)) fs.rmSync(temp, { force: true }); } catch (_) {}
+  }
+}
+
+function atomicWriteJson(file, value) {
+  atomicWriteFile(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function replacePluginRoot(value, runtimeDir, windowsForm) {
+  if (typeof value !== 'string') return value;
+  const root = windowsForm
+    ? runtimeDir.replace(/\//g, '\\')
+    : runtimeDir.replace(/\\/g, '/');
+  return value
+    .replace(/\$\{PLUGIN_ROOT\}/g, root)
+    .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, root);
+}
+
+function transformEntry(entry, runtimeDir) {
+  function visit(value, key) {
+    if (Array.isArray(value)) return value.map(item => visit(item, key));
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, visit(child, childKey)]));
+    }
+    if (typeof value === 'string') return replacePluginRoot(value, runtimeDir, key === 'commandWindows');
+    return value;
+  }
+  return visit(JSON.parse(JSON.stringify(entry)), null);
+}
+
+function containsPath(entry, target) {
+  const normalized = path.resolve(target).replace(/\\/g, '/').toLowerCase();
+  const text = JSON.stringify(entry).replace(/\\\\/g, '/').replace(/\\/g, '/').toLowerCase();
+  return text.includes(normalized);
+}
+
+function removePriorEntries(config, prior) {
+  const priorByEvent = new Map();
+  for (const record of prior.entries || []) {
+    if (!priorByEvent.has(record.event)) priorByEvent.set(record.event, new Map());
+    const counts = priorByEvent.get(record.event);
+    counts.set(record.hash, (counts.get(record.hash) || 0) + 1);
+  }
+
+  const drift = [];
+  const removed = [];
+  const nextHooks = { ...config.hooks };
+  for (const [event, expectedCounts] of priorByEvent) {
+    const remaining = new Map(expectedCounts);
+    const entries = Array.isArray(nextHooks[event]) ? nextHooks[event] : [];
+    const kept = [];
+    for (const entry of entries) {
+      const hash = entryHash(entry);
+      const count = remaining.get(hash) || 0;
+      if (count > 0) {
+        removed.push({ event, hash });
+        remaining.set(hash, count - 1);
+        continue;
+      }
+      if (prior.runtimeDir && containsPath(entry, prior.runtimeDir)) {
+        drift.push({
+          event,
+          hash,
+          reason: expectedCounts.has(hash)
+            ? 'unexpected duplicate Harness compatibility hook'
+            : 'Harness compatibility hook was modified after install',
+        });
+      }
+      kept.push(entry);
+    }
+    nextHooks[event] = kept;
+  }
+  return { config: { ...config, hooks: nextHooks }, drift, removed };
+}
+
+function hookEntriesFrom(pluginRoot, runtimeDir) {
+  const sourceFile = path.join(pluginRoot, 'hooks', 'hooks.json');
+  const source = readHooksFile(sourceFile);
+  const records = [];
+  for (const [event, entries] of Object.entries(source.hooks)) {
+    for (const entry of entries) {
+      const transformed = transformEntry(entry, runtimeDir);
+      records.push({ event, hash: entryHash(transformed), entry: transformed });
+    }
+  }
+  return records;
+}
+
+function sourceHookEntries(runtimeDir) {
+  return hookEntriesFrom(SOURCE_PLUGIN_ROOT, runtimeDir);
+}
+
+function ensureRuntime(runtimeDir, sourceHash) {
+  if (fs.existsSync(runtimeDir)) {
+    if (treeHash(runtimeDir) === sourceHash) return;
+    fs.rmSync(runtimeDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(path.dirname(runtimeDir), { recursive: true });
+  const temp = runtimeDir + '.tmp-' + process.pid;
+  try {
+    fs.rmSync(temp, { recursive: true, force: true });
+    fs.cpSync(SOURCE_PLUGIN_ROOT, temp, { recursive: true });
+    if (treeHash(temp) !== sourceHash) throw new Error('copied compatibility runtime hash mismatch');
+    fs.renameSync(temp, runtimeDir);
+  } finally {
+    try { if (fs.existsSync(temp)) fs.rmSync(temp, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+function install(options = {}) {
+  const codexHome = path.resolve(options.codexHome || defaultCodexHome(options.env));
+  const sourceHash = treeHash(SOURCE_PLUGIN_ROOT);
+  const p = pathsFor(codexHome, sourceHash);
+  assertCompatibilityPaths(p);
+  const existedBefore = fs.existsSync(p.hooksFile);
+  const hooksBefore = existedBefore ? fs.readFileSync(p.hooksFile) : null;
+  const runtimeExistedBefore = fs.existsSync(p.runtimeDir);
+  const config = readHooksFile(p.hooksFile);
+  const prior = readManifest(p.manifestFile, p);
+
+  let base = config;
+  if (prior) {
+    const removal = removePriorEntries(config, prior);
+    if (removal.drift.length) {
+      throw new Error('refusing to update: installed Harness compatibility hooks were modified; restore or uninstall them manually first');
+    }
+    base = removal.config;
+  }
+
+  ensureRuntime(p.runtimeDir, sourceHash);
+  assertCompatibilityPaths(p);
+  const generated = sourceHookEntries(p.runtimeDir);
+  const ownedEntries = [];
+  const next = { ...base, hooks: { ...base.hooks } };
+  for (const record of generated) {
+    const list = Array.isArray(next.hooks[record.event]) ? [...next.hooks[record.event]] : [];
+    if (!list.some(entry => entryHash(entry) === record.hash)) {
+      list.push(record.entry);
+      ownedEntries.push(record);
+    }
+    next.hooks[record.event] = list;
+  }
+
+  const manifest = {
+    schemaVersion: MANIFEST_SCHEMA,
+    package: 'harness-everything',
+    mode: MANIFEST_MODE,
+    packageVersion: PACKAGE_VERSION,
+    sourcePluginSha256: sourceHash,
+    runtimeDir: p.runtimeDir,
+    hooksFile: p.hooksFile,
+    createdHooksFile: prior ? Boolean(prior.createdHooksFile) : !existedBefore,
+    installedAt: new Date().toISOString(),
+    entries: ownedEntries.map(({ event, hash, entry }) => ({ event, hash, entry })),
+  };
+  try {
+    assertCompatibilityPaths(p);
+    atomicWriteJson(p.hooksFile, next);
+    atomicWriteJson(p.manifestFile, manifest);
+  } catch (error) {
+    try {
+      if (hooksBefore === null) fs.rmSync(p.hooksFile, { force: true });
+      else atomicWriteFile(p.hooksFile, hooksBefore);
+    } catch (rollbackError) {
+      error.message += '; hooks.json rollback also failed: ' + rollbackError.message;
+    }
+    if (!runtimeExistedBefore) {
+      try { fs.rmSync(p.runtimeDir, { recursive: true, force: true }); } catch (_) {}
+    }
+    throw error;
+  }
+
+  if (prior && prior.runtimeDir && path.resolve(prior.runtimeDir) !== path.resolve(p.runtimeDir)) {
+    const ownedRoot = path.resolve(p.runtimeRoot) + path.sep;
+    const oldRuntime = path.resolve(prior.runtimeDir);
+    if (oldRuntime.startsWith(ownedRoot)) fs.rmSync(oldRuntime, { recursive: true, force: true });
+  }
+
+  return {
+    status: prior ? 'updated' : 'installed',
+    codexHome,
+    hooksFile: p.hooksFile,
+    runtimeDir: p.runtimeDir,
+    entries: generated.length,
+    trustChanged: false,
+  };
+}
+
+function uninstall(options = {}) {
+  const codexHome = path.resolve(options.codexHome || defaultCodexHome(options.env));
+  const p = pathsFor(codexHome);
+  assertCompatibilityPaths(p);
+  const prior = readManifest(p.manifestFile, p);
+  if (!prior) return { status: 'not-installed', codexHome, removed: 0, trustChanged: false };
+
+  const hooksFileExists = fs.existsSync(p.hooksFile);
+  const config = readHooksFile(p.hooksFile);
+  const removal = removePriorEntries(config, prior);
+  if (removal.drift.length) {
+    throw new Error('refusing to uninstall modified Harness compatibility hooks; no user config was changed');
+  }
+
+  const remainingHooks = Object.fromEntries(
+    Object.entries(removal.config.hooks)
+      .map(([event, entries]) => [event, entries])
+      .filter(([, entries]) => Array.isArray(entries) && entries.length > 0)
+  );
+  const next = { ...removal.config, hooks: remainingHooks };
+  const otherTopLevelKeys = Object.keys(next).filter(key => key !== 'hooks');
+
+  if (!hooksFileExists) {
+    // The user or host already removed the config. Uninstall must not recreate it.
+  } else if (prior.createdHooksFile && otherTopLevelKeys.length === 0 && Object.keys(remainingHooks).length === 0) {
+    fs.rmSync(p.hooksFile, { force: true });
+  } else {
+    atomicWriteJson(p.hooksFile, next);
+  }
+
+  if (prior.runtimeDir) {
+    const ownedRoot = path.resolve(p.runtimeRoot) + path.sep;
+    const runtime = path.resolve(prior.runtimeDir);
+    if (runtime.startsWith(ownedRoot)) fs.rmSync(runtime, { recursive: true, force: true });
+  }
+  fs.rmSync(p.manifestFile, { force: true });
+  try { fs.rmdirSync(p.runtimeRoot); } catch (_) {}
+  try { fs.rmdirSync(p.ownerRoot); } catch (_) {}
+  try { fs.rmdirSync(path.dirname(p.ownerRoot)); } catch (_) {}
+
+  return {
+    status: 'uninstalled',
+    codexHome,
+    removed: removal.removed.length,
+    trustChanged: false,
+  };
+}
+
+function status(options = {}) {
+  const codexHome = path.resolve(options.codexHome || defaultCodexHome(options.env));
+  const p = pathsFor(codexHome);
+  assertCompatibilityPaths(p);
+  const prior = readManifest(p.manifestFile, p);
+  if (!prior) return { installed: false, codexHome, hooksFile: p.hooksFile, trustChanged: false };
+  const config = readHooksFile(p.hooksFile);
+  const removal = removePriorEntries(config, prior);
+  const expected = prior.entries.length;
+  return {
+    installed: true,
+    codexHome,
+    hooksFile: p.hooksFile,
+    runtimeDir: prior.runtimeDir,
+    packageVersion: prior.packageVersion,
+    sourcePluginSha256: prior.sourcePluginSha256,
+    expectedEntries: expected,
+    exactEntriesPresent: removal.removed.length,
+    drift: removal.drift,
+    healthy: removal.removed.length === expected && removal.drift.length === 0 &&
+      fs.existsSync(prior.runtimeDir) && treeHash(prior.runtimeDir) === prior.sourcePluginSha256,
+    trustChanged: false,
+  };
+}
+
+function parseArgs(argv) {
+  const action = argv[0] || 'status';
+  if (!['install', 'uninstall', 'status'].includes(action)) {
+    throw new Error('Usage: harness codex-hooks <install|uninstall|status> [--codex-home <path>]');
+  }
+  let codexHome;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--codex-home') codexHome = path.resolve(argv[++i]);
+    else throw new Error('unknown argument: ' + argv[i]);
+  }
+  return { action, codexHome };
+}
+
+function main(argv = process.argv.slice(2)) {
+  let args;
+  try { args = parseArgs(argv); }
+  catch (error) {
+    console.error('[Codex Hooks Compatibility] ' + error.message);
+    return 2;
+  }
+
+  try {
+    const result = args.action === 'install'
+      ? install({ codexHome: args.codexHome })
+      : args.action === 'uninstall'
+        ? uninstall({ codexHome: args.codexHome })
+        : status({ codexHome: args.codexHome });
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    if (args.action === 'status' && result.installed && !result.healthy) return 1;
+    return 0;
+  } catch (error) {
+    console.error('[Codex Hooks Compatibility] ' + error.message);
+    return 1;
+  }
+}
+
+if (require.main === module) process.exit(main());
+
+module.exports = {
+  MANIFEST_MODE,
+  MANIFEST_SCHEMA,
+  SOURCE_PLUGIN_ROOT,
+  defaultCodexHome,
+  entryHash,
+  install,
+  main,
+  pathsFor,
+  readHooksFile,
+  removePriorEntries,
+  sourceHookEntries,
+  stableJson,
+  status,
+  transformEntry,
+  treeHash,
+  uninstall,
+};

package/scripts/lib/advisory-text.js

@@ -7,35 +7,23 @@ const MARKER = "Harness OS Guidance (Advisory)";
 
 const advisoryInstructions = [
   `\n# ${MARKER}`,
-  `This surface cannot be assumed to mechanically enforce every Harness lifecycle transition.`,
-  `Treat the workflow contract below as required agent behavior, while keeping enforcement`,
-  `claims bounded by the host's verified capabilities.`,
+  `Harness is an observer/router/reminder layer on this surface; do not treat its workflow guidance as a hard scheduler.`,
   ``,
-  `## 🚦 MANDATORY ENTRY TRIAGE & WORKFLOW ROUTING`,
-  `For every software/project prompt, load the \`harness-everything\` skill and establish the routing contract before mutation:`,
-  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\`. If terminal execution is unavailable, apply the same contract from the skill instead of skipping routing.`,
-  `2. For EVERY suggested skill, read its complete \`SKILL.md\` entry and resolve applicability from \`USE FOR\`, \`DO NOT USE FOR\`, workflow/basic flow, and hard rules. A name, description, router summary, or "routine/simple/already clear" judgement is not enough to omit it.`,
-  `3. The selected workflow topology is mandatory once applicable. Execute it to resolution; choose tools, reasoning, implementation technique, and decomposition freely inside it. Do not replace it with a direct path because you believe you can solve the task without the workflow.`,
-  `4. If the selected workflow genuinely cannot cover part of the task, record an explicit escape for the uncovered scope with evidence. Covered obligations remain mandatory. Host-capability loss must be surfaced, not silently converted into optional execution.`,
-  `5. Surface a compact checkpoint near the first progress update:`,
-  `   \`\`\`markdown`,
-  `   ## 🚦 Harness OS Routing Checkpoint`,
-  `   - **Active Tier**: Tier 1 | Tier 2 | Tier 3 | unclassified`,
-  `   - **Strategy**: <selected/deferred strategy>`,
-  `   - **Workflow State**: <active | deferred | blocked | escaped>`,
-  `   - **Required Invariants**: <router invariants>`,
-  `   - **Suggested Skills**: <deduplicated suggestions or none>`,
-  `   - **Applicability**: <use | not-applicable + reason | unresolved/unavailable>`,
-  `   - **Escape**: <none | reason + uncovered scope + evidence>`,
-  `   \`\`\``,
+  `## 🚦 ENTRY TRIAGE & WORKFLOW GUIDANCE`,
+  `For software/project work, load the \`harness-everything\` skill and establish routing context before broad mutation:`,
+  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` when terminal execution is available.`,
+  `2. For EVERY suggested skill, read its complete \`SKILL.md\` entry and evaluate applicability from \`USE FOR\`, \`DO NOT USE FOR\`, and its basic flow.`,
+  `3. Treat the selected workflow topology and numeric limits as planning guidance, not a lock. Choose, combine, reorder, or skip steps when evidence supports it.`,
+  `4. Prefer objective verification before declaring done and worktree isolation for broad/Tier-3 mutation.`,
+  `5. Surface a compact routing checkpoint with tier, strategy, suggested skills, and any relevant warnings.`,
   ``,
   `## 🤖 COGNITIVE COMPLIANCE`,
-  `- **No universal skill pipeline**: do not force every task through TODO/TDD/Fable. The router selects the smallest sufficient topology; suggested skills are resolved for applicability.`,
-  `- **Applicable skill flow**: reading a skill is not permission to discard it when its workflow actually applies.`,
-  `- **Pre-completion verification**: before declaring done, run \`npx github:dyphn1/Harness-everything verify\` in the project root and fix failures. An instruction-only host may not block you mechanically, but the requirement remains part of the contract.`,
-  `- **Rule of 3**: after 3 same-signature failures, stop micro-retrying and use a fresh diagnosis / zoom-out.`,
+  `- **No universal skill pipeline**: do not force every task through TODO/TDD/Fable.`,
+  `- **Rule of 3**: after 3 same-signature failures, stop micro-retrying and use a fresh diagnosis / zoom-out. This reflection boundary may block mutation until completed.`,
+  `- **Permission boundaries are separate**: explicit host/user approval for destructive or external actions remains authoritative.`,
+  `- **Verification is evidence, not a cage**: missing evidence should trigger a reminder, not a persistent workflow lock.`,
   `- **Environment discovery**: discover OS, shell, package manager/runtime, and host capability before relying on them.`,
-  `- **Memory / self-evolve**: persist only verified reusable lessons; use escape/replan/recovery evidence to improve workflow coverage rather than bypassing the active workflow.`,
+  `- **Memory / self-evolve**: persist only verified reusable lessons.`,
   `- **Prefer editing**: prefer targeted edits and logically complete commits over broad rewrites.`,
   ``
 ].join('\n');
@@ -149,10 +137,9 @@ function buildCodexGlobalContent() {
     `- Discover the environment and host capabilities before relying on them.`,
     `- For software/project work, run \`npx github:dyphn1/Harness-everything next "<summary>"\` before mutation and surface the routing checkpoint.`,
     `- Read every suggested skill's complete \`SKILL.md\` entry before resolving applicability; do not omit it from metadata or confidence alone.`,
-    `- Execute the selected workflow topology to resolution. The model controls HOW inside the topology, not WHETHER the selected topology exists.`,
-    `- Do not impose a universal TODO/TDD/Fable sequence; use the smallest selected topology plus applicable skills.`,
-    `- Escape only for genuinely uncovered workflow scope and record reason + scope + evidence.`,
-    `- Before declaring done, run \`npx github:dyphn1/Harness-everything verify\` and fix failures.`,
+    `- Use the selected workflow topology as planning guidance; the model may adapt or skip steps with an explicit evidence-based reason.`,
+    `- Do not impose a universal TODO/TDD/Fable sequence; use the smallest useful topology plus applicable skills.`,
+    `- Prefer objective verification before declaring done; missing verification is a reminder, not a persistent lock.`,
     `- After 3 same-signature failures, stop retrying and use a fresh diagnosis / zoom-out.`,
     `- Prefer targeted edits and logically complete commits.`,
     ``

package/using-git-worktrees/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: using-git-worktrees
-description: Use when starting feature work needing isolation or before implementation plans - ensures an isolated workspace via native tools or git worktree fallback
+description: Use when starting feature work needing isolation or before implementation plans - recommends an isolated workspace via native tools or git worktree fallback
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.8.1
+  version: 0.16.1
 ---
 
 # Using Git Worktrees
@@ -13,7 +13,7 @@ Use native worktree support first; raw Git is the fallback.
 
 ## Contract
 
-- **Major workflow mode** — Tier 3 / Fable-class engineering must be isolated before source/artifact mutation. Reuse an existing linked worktree or create one. If isolation cannot be established, stop `BLOCKED`; never fall back to the primary working tree.
+- **Major workflow guidance** — Tier 3 / Fable-class engineering is safer in a linked worktree before broad source/artifact mutation. Reuse one or create one when practical.
 - **Ordinary mode** — isolation-needing feature work may honor an explicit user preference to stay in place.
 - Never nest a worktree inside an already isolated worktree.
 
@@ -28,11 +28,11 @@ git rev-parse --show-superproject-working-tree
 ```
 Different git/common dirs and no superproject => already isolated; continue to Step 2. A submodule is a normal repo for this check.
 
-**Step 1 — Create/enter**: prefer native `EnterWorktree`, `/worktree`, or `--worktree`. Otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. For major mode, choose an already-ignored or external/sibling path so setup does not require modifying the primary tree first. Creation/entry failure => `BLOCKED`. Only ordinary mode may continue in place after an explicit decline/unsupported environment.
+**Step 1 — Create/enter**: prefer native `EnterWorktree`, `/worktree`, or `--worktree`. Otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Prefer an already-ignored or external/sibling path. If creation/entry fails, report it and continue only with explicit awareness of the isolation risk.
 
 **Step 2 — Setup**: install project dependencies as needed.
 
-**Step 3 — Baseline**: run the relevant tests/build in the isolated tree before implementation; existing failures must be surfaced before mutation proceeds.
+**Step 3 — Baseline**: run relevant tests/build before implementation when useful; surface existing failures before relying on the baseline.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md