harness-everything 0.3.6 → 0.4.1

package/plugins/harness-everything/hooks/scripts/subagent-scope-guard.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * Subagent Scope Guard (PreToolUse + PostToolUse: Task/Agent and
+ * SubagentStart/SubagentStop)
+ *
+ * Phase 3 snapshots both `git status --porcelain` and any active Fable stage
+ * write sets at the beginning of a subagent burst. At the end it classifies
+ * newly changed paths as declared, ambiguous, or out-of-scope. Machine-
+ * readable write sets may therefore clear expected changes without weakening
+ * the conservative legacy path: when no stage contract exists, any new
+ * change still exits 2 and requires explicit review.
+ *
+ * `writeSet: []` means read-only. Worker attribution is used when the host
+ * exposes a worker/subagent id and the stage contract records the same id;
+ * otherwise the audit remains stage-level. The hook never infers scope from
+ * a natural-language task brief.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const {
+  getSessionDir,
+  getSessionId,
+  getStateRoot,
+  getWorkspaceRoot,
+} = require('./lib/harness-state');
+const {
+  atomicWriteJson,
+  getActiveRunContracts,
+  getWorkerId,
+  stagesForChangedPath,
+} = require('./lib/fable-contracts');
+
+function gitStatus(root) {
+  try {
+    return execSync('git status --porcelain', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (_) {
+    return null;
+  }
+}
+
+function snapshotContracts(stateRoot, sessionId) {
+  return getActiveRunContracts(stateRoot, sessionId).map(({ contract }) => ({
+    planId: contract.planId,
+    runId: contract.runId,
+    stageId: contract.stageId,
+    sessionId: contract.sessionId || null,
+    workerId: contract.workerId || null,
+    writeSet: Array.isArray(contract.writeSet) ? contract.writeSet : [],
+  }));
+}
+
+function classifyChanges(newlyChanged, declaredContracts, payload) {
+  const workerId = getWorkerId(payload);
+  let scopedContracts = declaredContracts;
+  if (workerId) {
+    const attributable = declaredContracts.filter(contract => contract.workerId === workerId);
+    if (attributable.length > 0) scopedContracts = attributable;
+  }
+  const entries = scopedContracts.map(contract => ({ contract }));
+  const expected = [];
+  const ambiguous = [];
+  const outOfScope = [];
+
+  for (const statusLine of newlyChanged) {
+    const matches = stagesForChangedPath(statusLine, entries);
+    if (matches.length === 1) {
+      const contract = matches[0].contract;
+      expected.push({
+        statusLine,
+        planId: contract.planId,
+        runId: contract.runId,
+        stageId: contract.stageId,
+        workerId: contract.workerId || workerId || null,
+      });
+    } else if (matches.length > 1) {
+      ambiguous.push({
+        statusLine,
+        stages: matches.map(({ contract }) => ({
+          planId: contract.planId,
+          runId: contract.runId,
+          stageId: contract.stageId,
+          workerId: contract.workerId || null,
+        })),
+      });
+    } else {
+      outOfScope.push({ statusLine, workerId: workerId || null });
+    }
+  }
+
+  return { workerId: workerId || null, expected, ambiguous, outOfScope };
+}
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    const event = payload.hook_event_name;
+    const toolName = payload.tool_name || payload.tool;
+    const isSubagentEvent = event === 'SubagentStart' || event === 'SubagentStop';
+    if (!isSubagentEvent && toolName !== 'Task' && toolName !== 'Agent') process.exit(0);
+
+    const root = getWorkspaceRoot(payload);
+    const sessionId = getSessionId(payload);
+    const sessionDir = getSessionDir(root, sessionId, payload);
+    const stateRoot = getStateRoot(root, payload);
+    const stateFile = path.join(sessionDir, 'subagent-scope-state.json');
+
+    if (event === 'PreToolUse' || event === 'SubagentStart') {
+      if (!fs.existsSync(stateFile)) {
+        const status = gitStatus(root);
+        if (status !== null) {
+          atomicWriteJson(stateFile, {
+            startedAt: new Date().toISOString(),
+            baseline: status,
+            contracts: snapshotContracts(stateRoot, sessionId),
+          });
+        }
+      }
+      process.exit(0);
+    }
+
+    if (event === 'PostToolUse' || event === 'SubagentStop') {
+      if (!fs.existsSync(stateFile)) process.exit(0);
+
+      let state;
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (_) { process.exit(0); }
+      const current = gitStatus(root);
+      if (current === null) process.exit(0);
+
+      const baselineLines = new Set(String(state.baseline || '').split('\n').filter(Boolean));
+      const currentLines = current.split('\n').filter(Boolean);
+      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
+      const declaredContracts = Array.isArray(state.contracts) ? state.contracts : [];
+      const classified = classifyChanges(newlyChanged, declaredContracts, payload);
+      const audit = {
+        schemaVersion: 1,
+        sessionId: sessionId || null,
+        observedAt: new Date().toISOString(),
+        declaredContractCount: declaredContracts.length,
+        ...classified,
+      };
+      atomicWriteJson(path.join(sessionDir, 'subagent-scope-last.json'), audit);
+
+      if (newlyChanged.length === 0) {
+        console.log('[Subagent Scope Guard] No new changed files detected during the subagent burst.');
+      } else if (declaredContracts.length === 0) {
+        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed with no machine-readable writeSet contract:`);
+        newlyChanged.forEach(line => console.error(`  ${line}`));
+        console.error('Confirm every path was actually in scope before trusting or committing this output.');
+      } else {
+        for (const entry of classified.expected) {
+          console.log(`[Subagent Scope Guard] in-scope ${entry.statusLine} -> ${entry.planId}/${entry.runId}/${entry.stageId}${entry.workerId ? ` worker=${entry.workerId}` : ''}`);
+        }
+        for (const entry of classified.ambiguous) {
+          console.error(`[Subagent Scope Guard] ambiguous scope ${entry.statusLine}; matches ${entry.stages.map(stage => `${stage.runId}/${stage.stageId}`).join(', ')}`);
+        }
+        for (const entry of classified.outOfScope) {
+          console.error(`[Subagent Scope Guard] OUT-OF-SCOPE ${entry.statusLine}${entry.workerId ? ` worker=${entry.workerId}` : ''}`);
+        }
+      }
+
+      atomicWriteJson(stateFile, {
+        startedAt: new Date().toISOString(),
+        baseline: current,
+        contracts: snapshotContracts(stateRoot, sessionId),
+      });
+
+      const violated = declaredContracts.length === 0
+        ? newlyChanged.length > 0
+        : classified.ambiguous.length > 0 || classified.outOfScope.length > 0;
+      if (violated) {
+        console.error('Do not "git add -A"; stage files explicitly so unexpected paths stay visible.');
+        process.exit(2);
+      }
+      process.exit(0);
+    }
+
+    process.exit(0);
+  } catch (_) {
+    // This is a post-execution visibility gate. Runtime errors fail open; the
+    // actionGate in Phase 5 has a stricter fail-ask policy for side effects.
+    process.exit(0);
+  }
+});
+
+module.exports = {
+  classifyChanges,
+};

package/plugins/harness-everything/hooks/scripts/subagent-start.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+// OpenAI's SubagentStart event has no Claude Task tool name. The shared guard
+// records the baseline, while this adapter adds the subagent's scope reminder
+// through the OpenAI hook output contract.
+process.on('exit', () => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: [
+        'Harness subagent scope guard is active.',
+        'Keep this worker within the requested scope and report every changed path before handoff.'
+      ].join('\n')
+    }
+  }) + '\n');
+});
+
+require('./subagent-scope-guard');

package/plugins/harness-everything/hooks/scripts/subagent-stop.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+// The shared guard emits exit code 2 and stderr when a subagent changed files;
+// OpenAI/Codex treats that as a continuation signal for SubagentStop.
+require('./subagent-scope-guard');

package/plugins/harness-everything/hooks/session-start.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getWorkspaceRoot,
+  getSessionId,
+  getSessionDir,
+  writeCurrentSession,
+  pruneStaleSessions
+} = require('./scripts/lib/harness-state');
+
+const POLICY = [
+  'Harness Cognitive OS policy is active.',
+  'Use Discover -> Think -> Try -> Summarize -> Record as a lightweight reasoning loop.',
+  'Cross-cutting invariants:',
+  '- Route before execution: establish task scope before mutating work.',
+  '- Verify before claim: require objective evidence appropriate to the change.',
+  '- Re-plan on repetition: after 3 same-signature failures, zoom out instead of repeating the same attempt.',
+  'Domain skills are advisory. Do not enforce a universal workflow order; choose the smallest useful skill/tool set.'
+].join('\n');
+
+function readPayload() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const raw = fs.readFileSync(0, 'utf8').trim();
+    return raw ? JSON.parse(raw) : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+function removeIfPresent(file) {
+  try {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  } catch (err) {
+    // Session reset is best effort; a stale breaker must never block startup.
+  }
+}
+
+function handoffContext(sessionDir) {
+  try {
+    const handoff = JSON.parse(fs.readFileSync(path.join(sessionDir, 'handoff-state.json'), 'utf8'));
+    if (handoff.status !== 'failed') return '';
+    const detail = String(handoff.errorSummary || 'No error snippet available').trim().slice(-300);
+    return `\nPrevious session checkpoint: ${handoff.tool || 'unknown'} failed${handoff.exitCode ? ` (exit ${handoff.exitCode})` : ''}.\nReview the failure evidence before continuing.\n${detail}`;
+  } catch (err) {
+    return '';
+  }
+}
+
+function main() {
+  const payload = readPayload();
+  const root = getWorkspaceRoot(payload);
+  const sessionId = getSessionId(payload);
+  let additionalContext = POLICY;
+
+  if (root) {
+    try {
+      pruneStaleSessions(root);
+      writeCurrentSession(root, sessionId);
+      const sessionDir = getSessionDir(root, sessionId);
+      removeIfPresent(path.join(sessionDir, 'rule-of-3-state.json'));
+      removeIfPresent(path.join(sessionDir, 'zoom-out-report.md'));
+      removeIfPresent(path.join(sessionDir, 'subagent-scope-state.json'));
+      additionalContext += handoffContext(sessionDir);
+    } catch (err) {
+      // Policy injection remains useful even if runtime state is unavailable.
+    }
+  }
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext
+    }
+  }));
+}
+
+main();

package/plugins/harness-everything/plugin.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "harness-everything",
+  "version": "0.4.1",
+  "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
+  "author": {
+    "name": "Miya Daniel",
+    "url": "https://github.com/dyphn1"
+  },
+  "homepage": "https://github.com/dyphn1/Harness-everything",
+  "repository": "https://github.com/dyphn1/Harness-everything",
+  "license": "Apache-2.0",
+  "keywords": [
+    "agent-harness",
+    "orchestration",
+    "tdd",
+    "verification"
+  ],
+  "extensions": {
+    "com.openai": {
+      "hooks": "./hooks/hooks.json",
+      "interface": {
+        "displayName": "Harness Everything",
+        "shortDescription": "Route, verify, and recover coding work",
+        "longDescription": "Harness Everything adds reusable software-engineering workflows for task routing, test-driven development, verification, security review, documentation, failure recovery, and related coding-agent work. It keeps a small set of cross-cutting invariants while allowing the agent to choose, combine, reorder, or skip domain skills as appropriate.",
+        "developerName": "Miya Daniel",
+        "category": "Developer Tools",
+        "capabilities": [
+          "Interactive",
+          "Read",
+          "Write"
+        ],
+        "websiteURL": "https://github.com/dyphn1/Harness-everything",
+        "privacyPolicyURL": "https://github.com/dyphn1/Harness-everything/blob/main/PRIVACY.md",
+        "termsOfServiceURL": "https://github.com/dyphn1/Harness-everything/blob/main/TERMS.md",
+        "defaultPrompt": [
+          "Route this software task with Harness and use only the skills that help.",
+          "Review this change and verify it with objective evidence before claiming completion."
+        ]
+      }
+    }
+  }
+}

package/plugins/harness-everything/scripts/lib/advisory-text.js

@@ -0,0 +1,174 @@
+// Prompt-injection-only guidance for platforms with no hook/execution
+// mechanism (Cursor, Copilot, Codex, Continue, Hermes). Single source of
+// truth for the advisory block.
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = "Harness OS Guidance (Advisory)";
+
+const advisoryInstructions = [
+  `\n# ${MARKER}`,
+  `This file is advisory only - this platform has no hook/execution mechanism to`,
+  `enforce it mechanically (unlike Claude Code's hook-based circuit breaker). Treat`,
+  `these as strong defaults, not guarantees.`,
+  ``,
+  `## 🚦 MANDATORY ENTRY TRIAGE & ROUTING (ALWAYS RUN FIRST)`,
+  `Every time you receive a new prompt, you MUST load the \`harness-everything\` skill and immediately do the following:`,
+  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` (this prints the same routing recommendation tier-router.js produces - it works from any directory and does not depend on where a local copy of the skill was installed). If the terminal is not available yet, simulate its routing logic from the rules below instead of skipping this step.`,
+  `2. Output a clear, stylized routing checkpoint block at the VERY BEGINNING of your response to the user:`,
+  `   \`\`\`markdown`,
+  `   ## 🚦 Harness OS Routing Checkpoint`,
+  `   - **Active Tier**: Tier 1 (Trivial) | Tier 2 (Standard) | Tier 3 (Macro)`,
+  `   - **Rationale**: <1-sentence rationale from the tier router output>`,
+  `   - **Routed Skills, Guides & Actions**:`,
+  `     - \`path/to/skill/or/guide.md\` (<Brief reason why this guide/skill is loaded/used>)`,
+  `   \`\`\``,
+  ``,
+  `## 🤖 COGNITIVE COMPLIANCE (NO SILENT DEGRADES FOR NEW FEATURES)`,
+  `- **Newly Added Features / Extensions**: Copilot is highly prone to treating new feature requests as Tier 1 direct edits. If a task introduces *any* new logic, a new API endpoint, or a new file/module, you **MUST NOT** treat it as Tier 1. It **MUST** be treated as a **Tier 2 (Standard Task)** or **Tier 3 (Macro Task)**.`,
+  `- **Tier 2 Activation**: Initialize the \`todo-driven-workflow\` checklist first. Summon Domain Experts based on tech stack. Load and execute the \`tdd\` (Test-Driven Development) skill (write tests first, implement, refactor).`,
+  `- **Tier 3 Activation**: Initialize the \`todo-driven-workflow\` checklist, load \`fable-mode\` and \`fable-discipline\`, run sub-agents via \`multi-agent-workspace\`, and write global docs using \`repo-docs\`.`,
+  `- **Pre-Completion Verification Gate**: Before telling the human the task is done, run \`npx github:dyphn1/Harness-everything verify\` in the project root. If it exits non-zero, fix the failures and run it again before declaring completion. On Claude Code this same check is mechanically enforced by a stop hook; here nothing blocks you from skipping it, so treat it as a real requirement, not a suggestion.`,
+  `- **Memory Summarization (Self-Evolve)**: Upon task completion, you **MUST** run the \`self-evolve\` skill (running \`node self-evolve/scripts/self-regression.js\` or writing memories) to record key insights, lessons learned, and error boundaries so your context builds across sessions.`,
+  `- **Environment Discovery**: Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
+  `- **Rule of 3**: If the same error repeats 3 times in a row, STOP retrying. Explain what's failing and ask the human for direction instead of continuing to guess.`,
+  `- **Prefer Editing**: Prefer editing over rewriting; commit logically complete chunks rather than one giant diff.`,
+  ``
+].join('\n');
+
+function hasHarnessMarker(content) {
+  return typeof content === 'string' && content.includes(MARKER);
+}
+
+function assertHarnessOwnedOrAbsent(targetFile, label) {
+  if (!fs.existsSync(targetFile)) return;
+  const content = fs.readFileSync(targetFile, 'utf8');
+  if (!hasHarnessMarker(content)) {
+    throw new Error(`Refusing to overwrite pre-existing non-Harness ${label}: ${targetFile}`);
+  }
+}
+
+function injectAdvisoryText(targetFile, header, label) {
+  const dir = path.dirname(targetFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  if (fs.existsSync(targetFile)) {
+    const content = fs.readFileSync(targetFile, 'utf8');
+    if (!hasHarnessMarker(content)) {
+      fs.appendFileSync(targetFile, advisoryInstructions, 'utf8');
+      console.log(`  ✅ Augmented existing ${label} with Harness guidance (advisory-only)`);
+    }
+  } else {
+    fs.writeFileSync(targetFile, `${header}\n${advisoryInstructions}`, 'utf8');
+    console.log(`  ✅ Created ${label} with Harness guidance (advisory-only)`);
+  }
+}
+
+function removeAdvisoryText(targetFile) {
+  if (!fs.existsSync(targetFile)) return;
+  try {
+    let content = fs.readFileSync(targetFile, 'utf8');
+    const markerIndex = content.indexOf(MARKER);
+    if (markerIndex !== -1) {
+      let cleanContent = content;
+      const hashMarkerIndex = content.lastIndexOf('#', markerIndex);
+      if (hashMarkerIndex !== -1) cleanContent = content.substring(0, hashMarkerIndex).trim() + '\n';
+      else cleanContent = content.substring(0, markerIndex).trim() + '\n';
+
+      const lines = cleanContent.trim().split('\n').map(l => l.trim()).filter(l => l !== '');
+      if (lines.length === 0 || (lines.length === 1 && (lines[0] === '# Cursor Project Rules' || lines[0] === '# AGENTS.md' || lines[0] === '# Copilot Instructions' || lines[0] === '# .hermes.md'))) {
+        fs.unlinkSync(targetFile);
+        console.log(`  ✅ Removed empty advisory file: ${targetFile}`);
+      } else {
+        fs.writeFileSync(targetFile, cleanContent.trim() + '\n', 'utf8');
+        console.log(`  ✅ Removed Harness guidance from: ${targetFile}`);
+      }
+    }
+  } catch (e) {
+    console.warn(`  ⚠️ Error removing advisory text from ${targetFile}: ${e.message}`);
+  }
+}
+
+// Continue gets a dedicated rule file. If a user already owns that exact
+// path, do not replace it just because Harness chose the same filename.
+function installContinueRule(targetFile, label) {
+  const dir = path.dirname(targetFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  assertHarnessOwnedOrAbsent(targetFile, label);
+  if (fs.existsSync(targetFile) && hasHarnessMarker(fs.readFileSync(targetFile, 'utf8'))) return;
+  const content = [
+    `---`,
+    `name: Harness OS Guidance`,
+    `alwaysApply: true`,
+    `description: "Harness OS routing, circuit-breaker awareness, and environment-discovery guidance (advisory only on Continue - no hook mechanism)"`,
+    `---`,
+    advisoryInstructions.replace(/^\n/, '')
+  ].join('\n');
+  fs.writeFileSync(targetFile, content, 'utf8');
+  console.log(`  ✅ Installed Continue rule file with Harness guidance (advisory-only): ${label}`);
+}
+
+function removeContinueRule(targetFile) {
+  if (!fs.existsSync(targetFile)) return;
+  try {
+    const content = fs.readFileSync(targetFile, 'utf8');
+    if (hasHarnessMarker(content)) {
+      fs.unlinkSync(targetFile);
+      console.log(`  ✅ Removed Harness rule file: ${targetFile}`);
+    }
+  } catch (e) {
+    console.warn(`  ⚠️ Error removing ${targetFile}: ${e.message}`);
+  }
+}
+
+function buildCopilotGlobalContent() {
+  return [
+    `---`,
+    `description: "Harness OS Guidance (Advisory)"`,
+    `applyTo: "**"`,
+    `---`,
+    `# Copilot Instructions`,
+    ``,
+    advisoryInstructions.replace(/^\n/, '')
+  ].join('\n');
+}
+
+function buildCodexGlobalContent() {
+  return [
+    `---`,
+    `description: "Harness OS Guidance - Global custom agent for orchestrating multi-agent workflows"`,
+    `name: "Harness"`,
+    `user-invocable: true`,
+    `---`,
+    `# AGENTS.md`,
+    ``,
+    `# ${MARKER}`,
+    `This file is advisory only - this platform has no hook/execution mechanism to`,
+    `enforce it mechanically (unlike Claude Code's hook-based circuit breaker). Treat`,
+    `these as strong defaults, not guarantees.`,
+    ``,
+    `- Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
+    `- Triage tasks: run \`npx github:dyphn1/Harness-everything next "<summary>"\` for a routing recommendation`,
+    `  (trivial fixes need no plan; standard features need tests; large refactors need an explicit plan`,
+    `  reviewed with the human before implementation).`,
+    `- Before declaring a task done, run \`npx github:dyphn1/Harness-everything verify\` and fix any failures`,
+    `  it reports - nothing here blocks you from skipping this, so treat it as a real requirement.`,
+    `- If the same error repeats 3 times in a row, STOP retrying. Explain what's failing and ask the`,
+    `  human for direction instead of continuing to guess.`,
+    `- Prefer editing over rewriting; commit logically complete chunks rather than one giant diff.`,
+    ``
+  ].join('\n');
+}
+
+module.exports = {
+  MARKER,
+  advisoryInstructions,
+  hasHarnessMarker,
+  assertHarnessOwnedOrAbsent,
+  injectAdvisoryText,
+  removeAdvisoryText,
+  installContinueRule,
+  removeContinueRule,
+  buildCopilotGlobalContent,
+  buildCodexGlobalContent,
+};

package/plugins/harness-everything/skills/environment-detection/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: environment-detection
+description: Use at session start (Discover phase) to detect and align with the operating system, shell (Git Bash vs PowerShell vs CMD), package managers, and dev tools; prevents blind command execution and repetitive tool errors.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Environment Detection & Shell Alignment
+
+Think > Try > Summarize > Record: detect before executing.
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Session start or complex terminal sequences. |
+| **Expected Output** | Detected OS, shell, PATH via script or heuristics. |
+| **State Mutations** | Session context adopts path/env-var syntax. |
+| **Enforcement Gate** | Preflight; fall back to `<environment_info>` inspection and probing. |
+
+Boundary: operate solely within `process.cwd()`; ignore other workspaces, history, or temp paths surfaced by the IDE — never run commands outside the current project root.
+
+## Workflow
+
+1. Preflight from this skill's own directory; parse OS, shell, available CLIs: `node "<this-skill-dir>/scripts/preflight.js"`
+2. Self-heal harness touchpoints (idempotent): `node "<skills-repo-root>/harness-everything/scripts/self-heal.js"` — audits `<workspace>/.claude/settings.json`, `<workspace>/.cursorrules`, `<workspace>/.github/copilot-instructions.md`, `<workspace>/AGENTS.md`.
+3. Adopt syntax: Git Bash → forward `/`, `$VAR`, Unix cmds (`ls`, `rm -rf`), never `dir`/`del`/PowerShell · PowerShell → `$env:VAR`, cmdlets · CMD → `\`, `%VAR%`, `dir`/`del`/`copy`, never Unix.
+4. On failure don't blindly retry — suspect wrong-shell syntax. Three failures → trigger `zoom-out`.
+
+Deep dive: <this-skill-dir>/references/shell-syntax-rules.md
+
+## USE FOR:
+- session-start OS/shell/toolchain detection
+- per-terminal command/path/env-var alignment
+- repairing missing harness touchpoints
+
+## DO NOT USE FOR:
+- operating outside the current workspace
+- installing toolchains from scratch

package/plugins/harness-everything/skills/environment-detection/references/shell-syntax-rules.md

@@ -0,0 +1,76 @@
+# Environment Detection — Full Shell Syntax Rules
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Session Start / Discover Phase] --> CheckNode{1. Node.js Executable?}
+
+    CheckNode -- Yes --> RunPreflight[Run scripts/preflight.js]
+    RunPreflight -- Exit 0 (Success) --> ParseOutput[Parse OS, Shell & Available CLI Tools]
+    RunPreflight -- Fails --> Heuristic
+
+    CheckNode -- No --> Heuristic{2. Environment Heuristic Inspection Fallback}
+
+    Heuristic --> CheckPrompt[Inspect <environment_info> & Session Context]
+    CheckPrompt --> ProbeShell[Probe Shell via echo $SHELL / $env:OS / %COMSPEC%]
+
+    ParseOutput --> AlignSyntax[Adopt Command & Path Syntax Rules]
+    ProbeShell --> AlignSyntax
+    AlignSyntax --> SelfHeal[Run self-heal.js if Node available]
+    SelfHeal --> Done[Environment Context Established]
+```
+
+## Cognitive loop detail
+
+- **[Think]**: Before running any terminal commands, check your environment. Blind execution is the primary source of agent step waste.
+- **[Try]**: Run the automated preflight check script to determine exact platform properties.
+- **[Summarize]**: Output the detected terminal, OS, and toolchains so the session context retains these bounds.
+- **[Record]**: Adopt the corresponding command syntax rules for the rest of the conversation.
+
+## Strict Workspace Boundary detail (Current Active Workspace Only)
+
+- **Current Workspace Only**: Must detect and operate solely within the active workspace directory (i.e. the current project root, which is `process.cwd()`).
+- **Ignore Other Workspaces**: Even if VS Code context or history exposes other workspaces, temporary paths, or recently opened projects (e.g. `d:\super.h2o.sbom`, `d:\DeveloperDocs`, `c:\Users\DanielCH.Chang\Desktop\XinputDxe_V0.0.5`, etc.), you **MUST completely ignore them**. Never perform structural analysis, tool checks, or execute terminal commands in those non-current project paths.
+- **Single-Workspace Execution**: All terminal commands, tool availability checks, and path resolutions MUST be strictly restricted to the current project root directory. Operating across boundaries on adjacent or unrelated folders is strictly prohibited.
+
+## Preflight & self-heal detail
+
+Run the preflight script that lives at `scripts/preflight.js` inside this skill's own directory — resolve the path from wherever this SKILL.md was loaded (do not guess a hard-coded location). Parse the output to understand:
+
+- Operating System (Windows vs. macOS vs. Linux)
+- Active Shell (Git Bash vs. PowerShell vs. Command Prompt)
+- Available CLI Tools (node, pnpm, docker, python, etc.)
+
+Toolchain self-heal: the harness itself is part of the environment. Audit whether this workspace's integration touchpoints (`.claude/settings.json` hooks, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`) are installed, and repair any missing ones — e.g., installed via Claude Code but now opened in Copilot. The script is idempotent (it delegates to the installer, which merges hooks by id and never duplicates advisory text), so running it on an already-healthy workspace is a no-op. Skip only if the user intentionally removed a touchpoint file.
+
+## Shell syntax rules in full
+
+### 1. Git Bash on Windows (User's Preferred Terminal)
+
+- **Path Slashes**: Always use forward slashes `/` (e.g., `scripts/lib/utils.js`). Never use raw backslashes `\` because they act as escape characters in Bash.
+- **Env Variables**: Use `$VARIABLE_NAME` syntax. Do NOT use `%VARIABLE_NAME%` or `$env:VARIABLE_NAME`.
+- **Command Set**: Standard Unix commands are fully supported (`ls`, `rm -rf`, `mkdir -p`, `cp`, `mv`). Do NOT run CMD native commands like `dir`, `del`, or `copy`.
+- **No PowerShell syntax**: Do not run PowerShell-specific scripts or syntax.
+
+### 2. PowerShell on Windows
+
+- **Path Slashes**: Forward slashes `/` or backslashes `\\` are both acceptable.
+- **Env Variables**: Use `$env:VARIABLE_NAME` syntax.
+- **Command Set**: Use standard PowerShell commands or common aliases (e.g., `New-Item`, `Remove-Item`).
+
+### 3. Windows Command Prompt (CMD)
+
+- **Path Slashes**: Use backslashes `\` for file paths.
+- **Env Variables**: Use `%VARIABLE_NAME%` syntax.
+- **Command Set**: Use `dir`, `del`, `copy`, `mkdir`. Do NOT use `ls`, `rm`, `cp`, `mkdir -p`.
+
+## Red flags & common errors
+
+- ❌ **CMD commands in Git Bash**: Attempting to run `dir` or `del` when the terminal is actually running Git Bash.
+- ❌ **PowerShell commands in Bash**: Attempting to run `$env:PATH` or `.ps1` files in a Bash environment.
+- ❌ **Path escape failures**: Sending raw Windows paths like `scripts\run.js` inside a Bash terminal, which interprets `\r` as a carriage return or escapes characters.
+
+## Verification & reflection
+
+If any shell command fails, do not blindly retry the exact same command. Stop and ask yourself: "Did I use the wrong syntax for this terminal? Is this a Git Bash vs. PowerShell syntax issue?" If you fail 3 times on the same command, trigger the `zoom-out` circuit breaker.