harness-everything 0.7.0 → 0.8.1

package/plugins/harness-everything/skills/using-git-worktrees/SKILL.md

@@ -4,46 +4,44 @@ description: Use when starting feature work needing isolation or before implemen
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # Using Git Worktrees
 
-Use native tools first; git fallback.
+Use native worktree support first; raw Git is the fallback.
 
-## 📋 Skill Contract
+## Contract
 
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Isolation-needing feature work; pre-plan setup. |
-| **Expected Output** | Isolated workspace plus clean test baseline. |
-| **State Mutations** | Creates `.worktrees/<branch>`; updates `.gitignore` if needed. |
-| **Enforcement Gate** | Detect existing isolation first; seamless sandbox fallback. |
+- **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.
+- **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.
 
 ## Workflow
 
-**Step 0 — Detect existing isolation** (adapt per `environment-detection`):
+**Step 0 — Detect isolation** (adapt per `environment-detection`):
 ```bash
 git rev-parse --git-dir
 git rev-parse --git-common-dir
 git branch --show-current
 git rev-parse --show-superproject-working-tree
 ```
-Dirs differ and no superproject → already isolated; skip to Step 2; never nest. Superproject → submodule (normal repo). Else honor declared preference or ask consent; declined → in place.
+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**: native tool (`EnterWorktree`, `/worktree`, `--worktree`) first — raw git creates phantom state. Else verify ignored via `git check-ignore -q .worktrees || git check-ignore -q worktrees`; unignored → add to .gitignore and commit. Then `git worktree add "$path" -b "$BRANCH_NAME"` at declared preference, existing `.worktrees/`/`worktrees/`, or default `.worktrees/`. Sandbox denial → work in place.
+**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 2 — Setup**: npm/cargo/pip/poetry/go.
+**Step 2 — Setup**: install project dependencies as needed.
 
-**Step 3 — Baseline**: run tests (`npm test`/`cargo test`/`pytest`/`go test ./...`); failures → report, ask.
+**Step 3 — Baseline**: run the relevant tests/build in the isolated tree before implementation; existing failures must be surfaced before mutation proceeds.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md
 
 ## USE FOR:
+- Tier 3 / Fable-class mutable engineering
 - feature work needing isolation
 - pre-implementation-plan setup
-- native vs manual `git worktree add`
 
 ## DO NOT USE FOR:
 - nesting inside an existing worktree
-- branch/merge workflows
+- read-only analysis with no mutation
+- branch/merge workflows unrelated to workspace isolation

package/plugins/harness-everything/skills/using-git-worktrees/references/workflow-details.md

@@ -1,108 +1,67 @@
 # Using Git Worktrees — Full Workflow Reference
 
-## Decision Flow
+## Decide whether isolation is mandatory
 
-```mermaid
-flowchart TD
-    Start[Trigger: Need Workspace Isolation] --> CheckIso{1. Already in Worktree?}
+Tier 3 / Fable-class engineering requires Git isolation before the first source
+or artifact mutation. Read-only discovery may remain in the bound repository.
+Durable multi-agent workspace state is separate: a staged run may need no
+multi-agent workspace and still require Git isolation.
 
-    CheckIso -- Yes (GIT_DIR != GIT_COMMON) --> Setup[3. Run Project Setup & Dependencies]
-    CheckIso -- No (Normal Repo) --> CheckNative{2. Native Worktree Tool Available?}
+Ordinary feature work may honor an explicit preference to stay in place.
+Mandatory mode has no in-place fallback for a declined helper, unavailable
+native tool, sandbox denial, or creation failure; report `blocked`.
 
-    CheckNative -- Yes --> RunNative[Use Native Worktree Tool] --> Setup
-    CheckNative -- No --> RunGit[Try git worktree add .worktrees/branch]
+## Detect existing isolation
 
-    RunGit -- Success --> Setup
-    RunGit -- Fails / Denied --> WorkInPlace[Fallback: Work in Place in Current Directory] --> Setup
-
-    Setup --> RunBaseline[4. Verify Clean Test Baseline]
-    RunBaseline --> Done[Isolated Workspace Ready]
-```
-
-## Step 0 detail
-
-**Submodule guard:** `git-dir` differs from `git-common-dir` inside git submodules as well. Before concluding "already in a worktree," verify you are not in a submodule:
+Inspect absolute Git paths and the registered worktree list:
 
 ```bash
-# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --absolute-git-dir
+git rev-parse --path-format=absolute --git-common-dir
 git rev-parse --show-superproject-working-tree
+git worktree list --porcelain
 ```
 
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
-
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
-
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to project setup.
-
-## Step 1a detail — native tools
-
-The user has asked for an isolated workspace. Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to setup.
-
-Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
-
-Only use the git fallback if you have no native worktree tool available.
-
-## Step 1b detail — directory selection priority
-
-Follow this priority order. Explicit user preference always beats observed filesystem state.
-
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
-2. **Check for an existing project-local worktree directory:** Check if `.worktrees/` or `worktrees/` exists using cross-platform file system tools (`read_file` / `list_dir` or native shell test commands). If found, use it. If both exist, `.worktrees` wins.
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-### Safety verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees || git check-ignore -q worktrees
-```
-
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+Reuse a registered linked checkout of the bound repository; never nest another
+worktree inside it. A submodule or unrelated repository is not sufficient proof.
+Record the resolved directory and branch (or detached HEAD) in the handoff.
 
-**Why critical:** Prevents accidentally committing worktree contents to repository.
+## Create and enter
 
-### Create the worktree
+Honor an existing directory preference. Prefer a host-native worktree facility
+when available, then verify that it is backed by a registered Git worktree.
+Otherwise use Git:
 
 ```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
+git worktree add "<isolated-path>" -b "<task-branch>"
 ```
 
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+For mandatory mode, choose an already-ignored project-local path or an external
+sibling path. Verify the exact project-local candidate with `git check-ignore`.
+Do not edit/commit the primary tree's ignore file just to permit worktree setup.
+If the native facility fails, a permitted Git fallback is valid; if neither can
+establish isolation, stop mutable work as blocked.
 
-## Step 2 detail — project setup
+Set each subsequent tool's working-directory field to the isolated path and
+keep artifact targets inside it. Entering a worktree does not authorize an
+absolute edit, patch move, or shell target back into the primary checkout.
+Resolve symlinks/junctions when verifying target scope.
 
-Auto-detect and run appropriate setup:
+## Setup and baseline
 
-```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
+Install the detected dependencies inside the isolated checkout, then run the
+relevant baseline tests/build before implementation. Surface existing failures
+with exact output and distinguish them from regressions introduced by the task.
+Continue fixing task-relevant failures within the user's authorized scope.
 
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
+For active Fable workflows, enter the correlated run through the router's
+displayed controller before dependency installation or artifact mutation. The
+session's `workflow-stages.json` bootstrap file is runtime state; it is not an
+exception for source changes.
 
-## Step 3 detail — baseline report
+## Evidence boundary
 
-If tests fail: report failures, ask whether to proceed or investigate. If tests pass:
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
+The workflow gate checks registered Git identity, direct/patch target paths,
+known shell side effects, and explicit outside paths. It is not a filesystem
+sandbox for arbitrary script bodies or indirect side effects. Preserve the
+platform capability boundary and report unsupported hook/metadata paths.

package/scripts/lib/advisory-text.js

@@ -1,6 +1,5 @@
-// Prompt-injection-only guidance for platforms with no hook/execution
-// mechanism (Cursor, Copilot, Codex, Continue, Hermes). Single source of
-// truth for the advisory block.
+// Prompt-injection guidance for integration paths where Harness cannot prove
+// lifecycle-hook enforcement. Single source of truth for advisory blocks.
 const fs = require('fs');
 const path = require('path');
 
@@ -8,31 +7,36 @@ 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.`,
+  `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.`,
   ``,
-  `## 🚦 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:`,
+  `## 🚦 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 (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>)`,
+  `   - **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>`,
   `   \`\`\``,
   ``,
-  `## 🤖 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.`,
+  `## 🤖 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.`,
+  `- **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.`,
+  `- **Prefer editing**: prefer targeted edits and logically complete commits over broad rewrites.`,
   ``
 ].join('\n');
 
@@ -67,30 +71,27 @@ function injectAdvisoryText(targetFile, header, label) {
 function removeAdvisoryText(targetFile) {
   if (!fs.existsSync(targetFile)) return;
   try {
-    let content = fs.readFileSync(targetFile, 'utf8');
+    const 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';
+    if (markerIndex === -1) return;
+    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}`);
-      }
+    const lines = cleanContent.trim().split('\n').map(l => l.trim()).filter(Boolean);
+    if (lines.length === 0 || (lines.length === 1 && ['# Cursor Project Rules', '# AGENTS.md', '# Copilot Instructions', '# .hermes.md'].includes(lines[0]))) {
+      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 });
@@ -100,7 +101,7 @@ function installContinueRule(targetFile, label) {
     `---`,
     `name: Harness OS Guidance`,
     `alwaysApply: true`,
-    `description: "Harness OS routing, circuit-breaker awareness, and environment-discovery guidance (advisory only on Continue - no hook mechanism)"`,
+    `description: "Harness OS routing and workflow guidance (instruction-governed on Continue unless a lifecycle mechanism is independently verified)"`,
     `---`,
     advisoryInstructions.replace(/^\n/, '')
   ].join('\n');
@@ -136,26 +137,24 @@ function buildCopilotGlobalContent() {
 function buildCodexGlobalContent() {
   return [
     `---`,
-    `description: "Harness OS Guidance - Global custom agent for orchestrating multi-agent workflows"`,
+    `description: "Harness OS Guidance - Global custom agent for orchestrating software 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.`,
+    `This instruction surface cannot be assumed to provide hard lifecycle blocking.`,
     ``,
-    `- 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.`,
+    `- 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.`,
+    `- After 3 same-signature failures, stop retrying and use a fresh diagnosis / zoom-out.`,
+    `- Prefer targeted edits and logically complete commits.`,
     ``
   ].join('\n');
 }
@@ -171,4 +170,4 @@ module.exports = {
   removeContinueRule,
   buildCopilotGlobalContent,
   buildCodexGlobalContent,
-};
+};

package/using-git-worktrees/SKILL.md

@@ -4,46 +4,44 @@ description: Use when starting feature work needing isolation or before implemen
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # Using Git Worktrees
 
-Use native tools first; git fallback.
+Use native worktree support first; raw Git is the fallback.
 
-## 📋 Skill Contract
+## Contract
 
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Isolation-needing feature work; pre-plan setup. |
-| **Expected Output** | Isolated workspace plus clean test baseline. |
-| **State Mutations** | Creates `.worktrees/<branch>`; updates `.gitignore` if needed. |
-| **Enforcement Gate** | Detect existing isolation first; seamless sandbox fallback. |
+- **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.
+- **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.
 
 ## Workflow
 
-**Step 0 — Detect existing isolation** (adapt per `environment-detection`):
+**Step 0 — Detect isolation** (adapt per `environment-detection`):
 ```bash
 git rev-parse --git-dir
 git rev-parse --git-common-dir
 git branch --show-current
 git rev-parse --show-superproject-working-tree
 ```
-Dirs differ and no superproject → already isolated; skip to Step 2; never nest. Superproject → submodule (normal repo). Else honor declared preference or ask consent; declined → in place.
+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**: native tool (`EnterWorktree`, `/worktree`, `--worktree`) first — raw git creates phantom state. Else verify ignored via `git check-ignore -q .worktrees || git check-ignore -q worktrees`; unignored → add to .gitignore and commit. Then `git worktree add "$path" -b "$BRANCH_NAME"` at declared preference, existing `.worktrees/`/`worktrees/`, or default `.worktrees/`. Sandbox denial → work in place.
+**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 2 — Setup**: npm/cargo/pip/poetry/go.
+**Step 2 — Setup**: install project dependencies as needed.
 
-**Step 3 — Baseline**: run tests (`npm test`/`cargo test`/`pytest`/`go test ./...`); failures → report, ask.
+**Step 3 — Baseline**: run the relevant tests/build in the isolated tree before implementation; existing failures must be surfaced before mutation proceeds.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md
 
 ## USE FOR:
+- Tier 3 / Fable-class mutable engineering
 - feature work needing isolation
 - pre-implementation-plan setup
-- native vs manual `git worktree add`
 
 ## DO NOT USE FOR:
 - nesting inside an existing worktree
-- branch/merge workflows
+- read-only analysis with no mutation
+- branch/merge workflows unrelated to workspace isolation

package/using-git-worktrees/references/workflow-details.md

@@ -1,108 +1,67 @@
 # Using Git Worktrees — Full Workflow Reference
 
-## Decision Flow
+## Decide whether isolation is mandatory
 
-```mermaid
-flowchart TD
-    Start[Trigger: Need Workspace Isolation] --> CheckIso{1. Already in Worktree?}
+Tier 3 / Fable-class engineering requires Git isolation before the first source
+or artifact mutation. Read-only discovery may remain in the bound repository.
+Durable multi-agent workspace state is separate: a staged run may need no
+multi-agent workspace and still require Git isolation.
 
-    CheckIso -- Yes (GIT_DIR != GIT_COMMON) --> Setup[3. Run Project Setup & Dependencies]
-    CheckIso -- No (Normal Repo) --> CheckNative{2. Native Worktree Tool Available?}
+Ordinary feature work may honor an explicit preference to stay in place.
+Mandatory mode has no in-place fallback for a declined helper, unavailable
+native tool, sandbox denial, or creation failure; report `blocked`.
 
-    CheckNative -- Yes --> RunNative[Use Native Worktree Tool] --> Setup
-    CheckNative -- No --> RunGit[Try git worktree add .worktrees/branch]
+## Detect existing isolation
 
-    RunGit -- Success --> Setup
-    RunGit -- Fails / Denied --> WorkInPlace[Fallback: Work in Place in Current Directory] --> Setup
-
-    Setup --> RunBaseline[4. Verify Clean Test Baseline]
-    RunBaseline --> Done[Isolated Workspace Ready]
-```
-
-## Step 0 detail
-
-**Submodule guard:** `git-dir` differs from `git-common-dir` inside git submodules as well. Before concluding "already in a worktree," verify you are not in a submodule:
+Inspect absolute Git paths and the registered worktree list:
 
 ```bash
-# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --absolute-git-dir
+git rev-parse --path-format=absolute --git-common-dir
 git rev-parse --show-superproject-working-tree
+git worktree list --porcelain
 ```
 
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
-
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
-
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to project setup.
-
-## Step 1a detail — native tools
-
-The user has asked for an isolated workspace. Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to setup.
-
-Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
-
-Only use the git fallback if you have no native worktree tool available.
-
-## Step 1b detail — directory selection priority
-
-Follow this priority order. Explicit user preference always beats observed filesystem state.
-
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
-2. **Check for an existing project-local worktree directory:** Check if `.worktrees/` or `worktrees/` exists using cross-platform file system tools (`read_file` / `list_dir` or native shell test commands). If found, use it. If both exist, `.worktrees` wins.
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-### Safety verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees || git check-ignore -q worktrees
-```
-
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+Reuse a registered linked checkout of the bound repository; never nest another
+worktree inside it. A submodule or unrelated repository is not sufficient proof.
+Record the resolved directory and branch (or detached HEAD) in the handoff.
 
-**Why critical:** Prevents accidentally committing worktree contents to repository.
+## Create and enter
 
-### Create the worktree
+Honor an existing directory preference. Prefer a host-native worktree facility
+when available, then verify that it is backed by a registered Git worktree.
+Otherwise use Git:
 
 ```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
+git worktree add "<isolated-path>" -b "<task-branch>"
 ```
 
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+For mandatory mode, choose an already-ignored project-local path or an external
+sibling path. Verify the exact project-local candidate with `git check-ignore`.
+Do not edit/commit the primary tree's ignore file just to permit worktree setup.
+If the native facility fails, a permitted Git fallback is valid; if neither can
+establish isolation, stop mutable work as blocked.
 
-## Step 2 detail — project setup
+Set each subsequent tool's working-directory field to the isolated path and
+keep artifact targets inside it. Entering a worktree does not authorize an
+absolute edit, patch move, or shell target back into the primary checkout.
+Resolve symlinks/junctions when verifying target scope.
 
-Auto-detect and run appropriate setup:
+## Setup and baseline
 
-```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
+Install the detected dependencies inside the isolated checkout, then run the
+relevant baseline tests/build before implementation. Surface existing failures
+with exact output and distinguish them from regressions introduced by the task.
+Continue fixing task-relevant failures within the user's authorized scope.
 
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
+For active Fable workflows, enter the correlated run through the router's
+displayed controller before dependency installation or artifact mutation. The
+session's `workflow-stages.json` bootstrap file is runtime state; it is not an
+exception for source changes.
 
-## Step 3 detail — baseline report
+## Evidence boundary
 
-If tests fail: report failures, ask whether to proceed or investigate. If tests pass:
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
+The workflow gate checks registered Git identity, direct/patch target paths,
+known shell side effects, and explicit outside paths. It is not a filesystem
+sandbox for arbitrary script bodies or indirect side effects. Preserve the
+platform capability boundary and report unsupported hook/metadata paths.