harness-everything 0.2.2 → 0.4.0

package/docs/workflows/to-spec.md

@@ -0,0 +1,83 @@
+# Workflow: To Spec
+
+> Synthesizes an already-discussed conversation into whichever written artifact actually fits — feature spec, CLI/API reference, schema doc, or dev doc — and publishes it per this repo's own `projectDocs` entry inside `harness-everything/manifest.json`. Advisory in both Tier 2 and Tier 3 toward other skills; its own Step 0 framework check is a mechanized script gate, not advisory.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `to-spec` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start(["/to-spec invoked"]) --> OutlinePreview["Phase 1: Present 10-20 Line Outline Preview & Path to User"]
+  OutlinePreview --> UserApproved{"User Approves Outline?"}
+  UserApproved -->|No / Adjustments Needed| AdjustOutline["Refine Template Shape & Outline"] --> OutlinePreview
+  
+  UserApproved -->|Yes| CheckScript["Phase 2: node to-spec/scripts/check-project-docs.js check"]
+  CheckScript --> ExitCode{"Exit code?"}
+  ExitCode -->|0: projectDocs complete or inferred| ResolveConfig["Use Configured / Inferred docLocation"]
+  ExitCode -->|1 / Script Missing| InspectWorkspace{"Inspect Workspace Folders"}
+  
+  InspectWorkspace -->|Folder Found| ResolveWorkspace["Use docs/specs/, docs/reference/, docs/adr/, .scratch/"]
+  InspectWorkspace -->|No Folder| ResolvePlatform["Fallback to .github/harness-everything/specs/"]
+  
+  ResolveConfig --> WriteDoc["Generate & Publish Full Document"]
+  ResolveWorkspace --> WriteDoc
+  ResolvePlatform --> WriteDoc
+  
+  WriteDoc --> End(["Spec Document Published Successfully"])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `to-spec` is reached through user requests and how it chains with companion skills in the Harness OS ecosystem.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: spec / PRD / cli reference / schema doc / dev doc| Suggest["Suggests to-spec/SKILL.md - advisory only, still explicit-invoke"]
+  Suggest --> TS["to-spec / SKILL.md"]
+  TS -->|Step 0, mandatory| Gate["check-project-docs.js check - scans repo-local manifest.json homes only"]
+  Gate -->|Exit 1, first run only| Init["check-project-docs.js init writes projectDocs into manifest.json"]
+  Init --> TS
+  Manifest["harness-everything/manifest.json (also owned by scripts/lib/manifest.js + self-evolve's generated registry)"] -.->|same file, different key| Gate
+  GWD["grill-with-docs / SKILL.md"] -->|Settles decisions BEFORE, feeds feature-spec shape| TS
+  GM["grill-me / SKILL.md"] -->|Settles decisions BEFORE| TS
+  TDD["tdd / SKILL.md (Tier 2)"] -.->|Optional pre-implementation doc, never blocks Red/Green/Refactor| TS
+  TS -->|Unresolved fork found mid-synthesis| GWD
+  TS -->|Published doc becomes input for| ToTickets["to-tickets / SKILL.md (planned)"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+```mermaid
+graph TD
+  Start["Tier 2 task: add a new `harness todo export` CLI command"] --> Invoke["/to-spec invoked (optional, offered by router)"]
+  Invoke --> RunCheck["node check-project-docs.js check"]
+  RunCheck --> Exit0["Exit 0 - .claude/harness-everything/manifest.json already has projectDocs from a prior run"]
+  Exit0 --> Gather2["Gathers context: existing native or Markdown checklist conventions"]
+  Gather2 --> PickShape2["Picks cli-reference.md - not feature-spec, no user stories needed"]
+  PickShape2 --> ConfirmFlags["Confirms --format and --since flag names with user"]
+  ConfirmFlags --> Draft["Writes doc from templates/cli-reference.md, adapted headings"]
+  Draft --> ReadDocLoc["projectDocs.docLocation says docs/reference/"]
+  ReadDocLoc --> PublishLocal["docs/reference/todo-export.md - not filed as an issue"]
+  PublishLocal --> Done(["Doc published; TDD proceeds unblocked either way"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure `to-spec` is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Mechanized Gate, Not Prose**: Step 0 ran `check-project-docs.js check` and honored its exit code — it did not skip straight to inferring the framework from prose memory of past runs.
+- [ ] **Repo-Local, Not Global**: `projectDocs` was read from / written to a workspace-relative platform home only (`.claude/`, `.cursor/`, `.github/`, `.codex/`, `.continue/` under this repo) — never `~/.agents` or the global `~/.claude` manifest, which would leak this repo's tracker into unrelated projects.
+- [ ] **Pointer, Not Payload**: Every `projectDocs` field is a short pointer (≤ 200 chars, enforced by `init`) — elaborate content (a full issue template, a per-context doc map) lives in its own file, referenced by path, not inlined into `manifest.json`.
+- [ ] **No Re-Interview Violation**: Beyond the one-time Step 0 setup, the skill did not ask the user questions that a prior `grill-me`/`grill-with-docs` pass, or the conversation itself, already answered.
+- [ ] **Adaptive Shape Selection**: The template picked (feature-spec / cli-reference / schema-doc / dev-doc) actually matches the artifact being documented — not defaulted to the heaviest shape out of habit.
+- [ ] **Shape-Correct Destination**: A feature-spec was filed as an issue; a CLI-reference/schema-doc/dev-doc was written under `docLocation` instead, unless the user explicitly confirmed it should also be an issue.
+- [ ] **Non-Blocking Toward Other Skills**: The Step 3 confirmation happened before publishing, and to-spec's own execution never delayed or gated `tdd`/`verification-loop` in a Tier 2 flow.

package/docs/workflows/to-tickets.md

@@ -0,0 +1,80 @@
+# Workflow: To Tickets
+
+> Breaks a `to-spec` feature spec, a plan, or the current conversation into tracer-bullet tickets with declared blocking edges, published through the same `projectDocs` entry `to-spec` already established. Reuses `to-spec`'s own project-docs gate — never a second setup interview.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `to-tickets` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start(["/to-tickets invoked"]) --> CheckScript["Step 0: node to-spec/scripts/check-project-docs.js check"]
+  CheckScript --> ExitCode{"Exit code?"}
+  ExitCode -->|0: projectDocs configured/inferred| PathConfig["Use Configured / Inferred Tracker"]
+  ExitCode -->|1 / Script Missing| InspectRepo{"Inspect Workspace Directories"}
+  
+  InspectRepo -->|Folder Found| PathRepo["Use docs/roadmaps/, docs/tickets/, tasks/tickets/, .scratch/issues/"]
+  InspectRepo -->|No Folder| PathPlatform["Fallback to .github/harness-everything/tickets/"]
+  
+  PathConfig --> Gather["Step 1: Gather context from spec, plan, or conversation"]
+  PathRepo --> Gather
+  PathPlatform --> Gather
+  
+  Gather --> Explore["Step 2: Explore codebase & identify prefactor opportunities"]
+  Explore --> Draft["Step 3: Draft vertical slices with tracer bullets & blocking edges"]
+  Draft --> Quiz["Step 4: Quiz user on granularity, blocking edges, and merges"]
+  
+  Quiz --> Approved{"User approves breakdown?"}
+  Approved -->|No| Draft
+  Approved -->|Yes| Publish["Step 5: Publish ticket files at resolved storage path"]
+  Publish --> End(["Tickets published, frontier = unblocked tickets"])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `to-tickets` is reached through user requests and how it chains with companion skills in the Harness OS ecosystem.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: break into tickets / vertical slice / tracer bullet / blocking edges| Suggest["Suggests to-tickets/SKILL.md - advisory only, still explicit-invoke"]
+  Suggest --> TT["to-tickets / SKILL.md"]
+  TT -->|Step 0, mandatory, SAME script as to-spec| Gate["check-project-docs.js check"]
+  Gate -->|Exit 1| RedirectToSpec["Stop - point user to /to-spec's Step 0 interview, not a duplicate here"]
+  TS["to-spec / SKILL.md"] -->|Published feature-spec is the preferred input| TT
+  TS -.->|Same projectDocs entry, read not written| Gate
+  TT -->|No spec exists yet, still works from| Convo["Current conversation / plan"]
+  TT -->|Publishes tickets that unblock| TDD["tdd / SKILL.md (Tier 2, per ticket)"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+```mermaid
+graph TD
+  Start["A to-spec feature-spec for 'notification retry limits' was published earlier"] --> Invoke["/to-tickets invoked with the spec's issue number"]
+  Invoke --> RunCheck["node check-project-docs.js check - Exit 0, projectDocs already set from the to-spec run"]
+  RunCheck --> FetchSpec["Fetches full spec body via gh issue view"]
+  FetchSpec --> ExploreCode["Explores retry-policy module, finds a shared RetryConfig prefactor opportunity"]
+  ExploreCode --> DraftSlices["Drafts 3 tracer-bullet tickets: 01 prefactor RetryConfig, 02 per-tenant override (blocked by 01), 03 UI toggle (blocked by 02)"]
+  DraftSlices --> QuizUser["Presents numbered breakdown, user merges 02+03"]
+  QuizUser --> Publish2["Publishes 2 GitHub issues in dependency order, Status: ready-for-agent"]
+  Publish2 --> Done(["Frontier = ticket 01, unblocked, ready to claim"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure `to-tickets` is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Shared Gate, No Duplicate Interview**: Step 0 called `to-spec`'s own `check-project-docs.js check` — it did not run a second, parallel setup interview for tracker/doc-location/issue-definition.
+- [ ] **Vertical, Not Horizontal**: Every non-wide-refactor ticket cuts a complete path through all layers it touches — no ticket is "just the schema" or "just the UI" for the same feature.
+- [ ] **Blocking Edges Are Real**: Each ticket's "Blocked by" lists only tickets that genuinely gate it, not every ticket that merely precedes it in reading order.
+- [ ] **Wide-Refactor Exception Applied Correctly**: A mechanical, huge-blast-radius change was sequenced as expand → migrate batches → contract, not forced into a single tracer-bullet ticket that can't land green.
+- [ ] **User Approval Before Publish**: The numbered breakdown was shown and approved (or iterated on) before Step 5 published anything.
+- [ ] **No Forced Decomposition**: A `cli-reference`/`schema-doc`/`dev-doc` shaped `to-spec` doc that was already a single unit of work was not artificially split into multiple tickets.

package/docs/workflows/todo-driven-workflow.md

@@ -1,36 +1,67 @@
-# Workflow: Todo-Driven Workflow
-
-> The fundamental execution loop. Driven entirely by terminal state machines (`todo-cli.js`).
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes the rigid state constraints. Transitioning state is blocked unless verification gates pass.
-
-```mermaid
-graph TD
-  Start([Initialize Checklist]) --> Plan["Define 3-7 Verifiable Sub-tasks"]
-  Plan --> SaveTodo["Try: node todo-cli.js init ..."]
-  
-  SaveTodo --> ChooseTask["Choose ONE pending task"]
-  ChooseTask --> MarkInProgress["Try: node todo-cli.js start <id>"]
-  
-  MarkInProgress --> CheckStart{Gate: Exit Code?}
-  CheckStart -->|Exit 1: Multitasking Blocked| ReflectStart["Reflect: Must complete previous task first"]
-  ReflectStart --> Execute
-  
-  CheckStart -->|Exit 0| Execute["Execute code changes"]
-  
-  Execute --> GatherEvidence["Try: node verify-gate.js"]
-  GatherEvidence --> VerifySuccess{Gate: Exit Code?}
-  
-  VerifySuccess -->|Exit 1: Code is broken| ReflectCode["Reflect: Read Error Log & Fix"]
-  ReflectCode --> Execute
-  
-  VerifySuccess -->|Exit 0: Code works| MarkCompleted["Try: node todo-cli.js complete <id>"]
-  
-  MarkCompleted --> CheckRemaining{All tasks completed?}
-  CheckRemaining -->|No| ChooseTask
-  CheckRemaining -->|Yes| Finish([Signal Task Completion])
-```
+# Workflow: Todo-Driven Workflow
+
+> The fundamental execution loop for Tier 2/3 work. Prefer the host's native
+> TODO tracker; use a Markdown checklist when no native tracker is available.
+
+```mermaid
+graph TD
+  Start[Initialize checklist] --> Plan[Define 3-7 verifiable milestones]
+  Plan --> Native{Native TODO tracker available?}
+  Native -->|Yes| Host[Use host tracker]
+  Native -->|No| Markdown[Create tasks/todo.md]
+  Host --> One[Keep one item in-progress]
+  Markdown --> One
+  One --> Execute[Execute bounded scope]
+  Execute --> Verify[Run named verification command]
+  Verify -->|pass| Complete[Record evidence and complete item]
+  Verify -->|fail| Reflect[Inspect failure and update plan]
+  Reflect --> Execute
+  Complete --> More{More milestones?}
+  More -->|Yes| One
+  More -->|No| Done[Finish]
+```
+
+## Operating rules
+
+1. Define 3-7 milestones before editing.
+2. Give each milestone an output, pass condition, and verification command.
+3. Keep exactly one milestone `in-progress`.
+4. Mark a milestone complete only after its check passes.
+5. Use `using-git-worktrees` when parallel agents would otherwise share a write scope.
+6. Leave a blocker visible in the checklist and escalate instead of inventing progress.
+
+The repository has no TODO CLI state machine. This keeps progress portable,
+host-native, and transparent across sessions.
+
+## Blocker loop
+
+One milestone owns the active work. A failed check updates that milestone and
+returns to execution; it does not silently advance the rest of the list.
+
+```mermaid
+flowchart LR
+  Active[One milestone in progress] --> Execute[Execute bounded scope]
+  Execute --> Verify[Run named verification]
+  Verify -->|Pass| Record[Record evidence and complete]
+  Verify -->|Fail| Blocker[Record blocker and update plan]
+  Blocker --> Active
+  Record --> More{More milestones?}
+  More -->|Yes| Active
+  More -->|No| Done([Finish])
+```
+
+## Ownership state
+
+The checklist makes ownership visible from planning through completion.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Planned
+  Planned --> InProgress
+  InProgress --> Verifying
+  Verifying --> Complete: check passes
+  Verifying --> Blocked: check fails
+  Blocked --> InProgress: plan updated
+  Complete --> InProgress: milestones remain
+  Complete --> [*]: no milestones remain
+```

package/docs/workflows/using-git-worktrees.md

@@ -10,14 +10,18 @@ This section visualizes how the `using-git-worktrees` skill executes internally,
 
 ```mermaid
 graph TD
-  Start([Switch Context Needed]) --> CheckClean["Assess if main branch has uncommitted changes"]
-  CheckClean --> CreateWorktree["Run git worktree add to a sibling directory"]
-  CreateWorktree --> CheckoutTarget["Checkout target branch or create a hotfix branch"]
-  CheckoutTarget --> OpenWorkspace["Open the sibling directory as a separate isolated workspace"]
-  OpenWorkspace --> RunDev["Perform isolated edits, tests, and debugging"]
-  RunDev --> CommitIsolated["Commit changes in the isolated workspace"]
-  CommitIsolated --> RemoveWorktree["Prune and clean up the worktree path"]
-  RemoveWorktree --> Return([Return to original workspace with pristine unsaved state intact])
+  Start([Trigger: Need Workspace Isolation]) --> CheckIso{1. Already in Worktree? GIT_DIR != GIT_COMMON}
+  CheckIso -->|Yes| Setup["3. Project Setup & Dependency Install"]
+  CheckIso -->|No| CheckNative{2. Native Worktree Tool Available?}
+  
+  CheckNative -->|Yes| RunNative["Use Native Worktree Tool"] --> Setup
+  CheckNative -->|No| RunGit["Try git worktree add .worktrees/branch"]
+  
+  RunGit -->|Success| Setup
+  RunGit -->|Fails / Sandbox Denied| WorkInPlace["Fallback: Work in Place in Current Directory"] --> Setup
+  
+  Setup --> RunBaseline["4. Verify Clean Test Baseline"]
+  RunBaseline --> End([Isolated Workspace Ready])
 ```
 
 ---

package/docs/workflows/verification-loop.md

@@ -10,20 +10,22 @@ This section visualizes how the `verification-loop` skill executes internally, d
 
 ```mermaid
 graph TD
-  Start([Pre-PR Quality Check Triggered]) --> RunBuild["Execute compilation / project build"]
-  RunBuild --> CheckBuild{Build succeeded?}
-  CheckBuild -->|No| FixBuild["Debug and fix build errors"]
-  CheckBuild -->|Yes| RunTypeCheck["Execute language type-checking compiler"]
-  RunTypeCheck --> CheckTypes{Typecheck green?}
-  CheckTypes -->|No| FixTypes["Correct type-definition errors"]
-  CheckTypes -->|Yes| RunLint["Execute code linter checks"]
-  RunLint --> CheckLint{Lint clean?}
-  CheckLint -->|No| FixLint["Correct code-style and syntax errors"]
-  CheckLint -->|Yes| RunTests["Execute complete automated test suite"]
-  RunTests --> CheckTests{Tests passed?}
-  CheckTests -->|No| FixTests["Debug and correct failing tests"]
-  CheckTests -->|Yes| End([Pre-PR verification gate cleared successfully])
-  FixBuild & FixTypes & FixLint & FixTests --> RunBuild
+  Start([Pre-PR Quality Check Triggered]) --> RunBuild["1. Phase 1: Build Verification"]
+  RunBuild --> RunTypeCheck["2. Phase 2: Type Check (tsc / pyright)"]
+  RunTypeCheck --> RunLint["3. Phase 3: Lint Check"]
+  RunLint --> RunTests["4. Phase 4: Test Suite Execution"]
+  RunTests --> RunSecurity["5. Phase 5: Security & Secret Scan"]
+  RunSecurity --> DiffReview["6. Phase 6: Diff Review"]
+  
+  DiffReview --> CheckScript{7. Is verify-gate.js / Template Available?}
+  CheckScript -->|Yes| ScriptReport["Run harness-everything/scripts/verify-gate.js & Fill Template"]
+  CheckScript -->|No| DirectReport["Output Verification Report Inline"]
+  
+  ScriptReport --> CheckGate{All Verification Gates Passed?}
+  DirectReport --> CheckGate
+  
+  CheckGate -->|No| FixIssues["Fix Issues in Code & Re-verify"] --> RunBuild
+  CheckGate -->|Yes| End([Pre-PR Verification Gate Cleared])
 ```
 
 ---

package/docs/workflows/verify-before-claim.md

@@ -10,13 +10,17 @@ This section visualizes how the `verify-before-claim` skill executes internally,
 
 ```mermaid
 graph TD
-  Start([Claim or Estimate Proposed]) --> IdentifyAssumptions["Isolate any claim or performance assumption"]
-  IdentifyAssumptions --> QueryAuthoritative["Execute WebSearch or read local code sources"]
-  QueryAuthoritative --> CrossVerify["Cross-verify details with authoritative documentation"]
-  CrossVerify --> RunLocalExperiment["Run quick script to empirically test the assumption"]
-  RunLocalExperiment --> CaptureResult["Log actual measured results and exit-codes"]
-  CaptureResult --> AssertFact["Assert verified fact based on objective data"]
-  AssertFact --> End([Hypothesis replaced with empirical truth])
+  Start([About to Assert External Framework / API Behavior or Perf Number]) --> CheckScope{Claim Scope Check}
+  CheckScope -->|Internal Repo Code| ReadSource["Read Local Source Code -> State Facts"]
+  CheckScope -->|External Framework / API / Number| CheckNet{Web Fetch / Search / Measurement Available?}
+  
+  CheckNet -->|Yes| FetchDocs["WebFetch Official Docs / Measure Real Execution"]
+  CheckNet -->|No / Offline| EstimateFallback["Explicitly Label Response as Unverified Estimate"]
+  
+  FetchDocs --> CiteDocs["Quote Authoritative Source / State Measured Data"]
+  ReadSource --> End([Verified Output Delivered])
+  CiteDocs --> End
+  EstimateFallback --> End
 ```
 
 ---
@@ -28,7 +32,7 @@ This diagram illustrates how the `verify-before-claim` skill is triggered throug
 ```mermaid
 graph LR
   Router["harness-everything / tier-router.js"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
-  VBC -->|Empirical verification helper| RunCode["mcp_provides_tool_pylanceRunCodeSnippet / run_in_terminal"]
+  VBC -->|Empirical verification helper| RunCode["Run a real Node/terminal measurement"]
   VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
   VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
 ```

package/docs/workflows/zoom-out.md

@@ -10,13 +10,24 @@ This section visualizes how the `zoom-out` skill executes internally, detailing
 
 ```mermaid
 graph TD
-  Start([3 Consecutive Errors Triggered]) --> Tripped{Rule of 3 Tripped?}
-  Tripped -->|No| Backtrack["Review code change and retry"]
-  Tripped -->|Yes| LockWork["Lock all file edit capabilities"]
-  LockWork --> GatherState["Analyze current working directory, file states, and errors"]
-  GatherState --> GenReport["Compile formal Reflection Report: what failed, assumptions, backtracking options"]
-  GenReport --> PresentReport["Present report to human partner and request guidance"]
-  PresentReport --> End([Workforce unlocked after human direction received])
+  Start([3 Consecutive Failures / Goal Drift Triggered]) --> CeaseFire["1. Phase 1: Cease Fire - Stop Code Edits Immediately"]
+  CeaseFire --> Rebuild["2. Phase 2: Rebuild Full Picture using Read-Only Tools"]
+  Rebuild --> CheckPath{3. Resolve Reflection Report Path}
+  
+  CheckPath -->|Session Path Provided| WriteSession["Copy template to Session zoom-out-report.md"]
+  CheckPath -->|Template / Path Unavailable| WritePlatform["Write to .github/harness-everything/zoom-out-report.md or Inline"]
+  
+  WriteSession --> DecisionGate{4. Phase 4: Decision Gate}
+  WritePlatform --> DecisionGate
+  
+  DecisionGate -->|Untried Path Identified| Resume["RESUME: Execute Fresh Diagnosis in TDD / Fable"]
+  DecisionGate -->|Requirement Conflict / Access Gap| Escalate["ESCALATE: Present 2-3 Options + Recommendation to Human"]
+  
+  Resume --> Resolved{5. Problem Cracking Succeeds?}
+  Resolved -->|Yes| SelfEvolve["Call self-evolve to Persist Insight"]
+  Resolved -->|No: 3 More Failures| Escalate
+  SelfEvolve --> End([Reflection Completed & Lessons Persisted])
+  Escalate --> End
 ```
 
 ---
@@ -29,7 +40,7 @@ This diagram illustrates how the `zoom-out` skill is triggered through user requ
 graph LR
   RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
   ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
-  ZoomOut -->|Asks for human direction via| AskQuestions["vscode_askQuestions"]
+  ZoomOut -->|Asks for human direction via| AskQuestions["host user-input mechanism"]
   ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
 ```
 
@@ -43,8 +54,9 @@ Here we model concrete real-world scenarios and use cases of the `zoom-out` skil
 graph TD
   Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
   Trigger --> Lock["Workspace writes locked"]
-  Trigger --> Collect["Collect error traces and diff history"]
-  Collect --> WriteReport["Create docs/reflection/zoom-out-report.md detailing the import cyclic dependency"]
+  Trigger --> Awaken["Awaken: Stop error-fixing; review imports design & requirements (Law 2)"]
+  Awaken --> Collect["Collect error traces and diff history"]
+  Collect --> WriteReport["Create the session zoom-out-report.md detailing the import cyclic dependency"]
   WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
   Present --> UserChoice["User select: 'Option B'"]
   UserChoice --> Unlock["Unlock workspace and execute Option B"]

package/environment-detection/SKILL.md

@@ -1,77 +1,41 @@
 ---
 name: environment-detection
-description: Use at the very beginning of the session (Discover phase) to automatically detect and align with the operating system, terminal shell (e.g. Git Bash vs PowerShell vs Command Prompt), package managers, and development tools. Prevents blind command execution and repetitive tool-related errors.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+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 (Discover Phase), or before executing a complex terminal command sequence. |
-| **Expected Output** | Terminal execution of `node <this-skill-dir>/scripts/preflight.js`. Output of the detected OS and Shell. |
-| **State Mutations** | Context is updated with the correct path separator (`/` vs `\`) and environment variable syntax (`$VAR` vs `%VAR%`). |
-| **Enforcement Gate** | You MUST read the terminal output of `preflight.js`. If you use the wrong syntax (e.g. `%VAR%` in bash), the terminal will naturally Exit 1 and block your progress. |
-
-## Core Principles
-- **MUST** operate using the cognitive loop: Think > Try > Summarize > Record.
-- **[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 (僅偵測與操作當前工作區)
-- **Current Workspace Only**: 必須僅偵測與操作當前活動工作區目錄（即當前專案根目錄，亦為 `process.cwd()`）。
-- **Ignore Other Workspaces**: 即使 VS Code 內容或歷史記錄中暴露了其他工作區、暫存路徑或最近開啟的專案（例如 `d:\super.h2o.sbom`、`d:\DeveloperDocs`、`c:\Users\DanielCH.Chang\Desktop\XinputDxe_V0.0.5` 等），你也 **必須完全忽略它們**。絕對不要對這些非當前專案之路徑進行結構分析、工具檢查，更不能在其中執行任何終端機指令。
-- **Single-Workspace Execution**: 所有終端機指令、工具可用性檢查、路徑解析均必須嚴格限制在當前專案根目錄內。嚴格禁止跨越邊界操作鄰近或無關的資料夾。
-
-## [State Checkpoint]
-- Verify your environment details *before* executing commands or writing files.
-- If you just started a session, run the preflight script immediately.
-
-## [Discovery Phase: Environment Audit]
-1. 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):
-   ```bash
-   node "<this-skill-dir>/scripts/preflight.js"
-   ```
-2. Parse the output and 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.)
-3. **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:
-   ```bash
-   node "<skills-repo-root>/harness-everything/scripts/self-heal.js"
-   ```
-   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.
+| **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. |
 
-## [Execution Phase: Syntax and Command Alignment]
-Choose the correct syntax matching your active shell:
+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.
 
-### 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.
+## Workflow
 
-### 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`).
+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`.
 
-### 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`.
+Deep dive: <this-skill-dir>/references/shell-syntax-rules.md
 
-## [Verification & Reflection Phase]
-3. If any shell command fails, do **not** blindly retry the exact same command. 
-4. Stop and ask yourself: "Did I use the wrong syntax for this terminal? Is this a Git Bash vs. PowerShell syntax issue?"
-5. If you fail 3 times on the same command, trigger the `zoom-out` circuit breaker.
+## USE FOR:
+- session-start OS/shell/toolchain detection
+- per-terminal command/path/env-var alignment
+- repairing missing harness touchpoints
 
-## 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.
+## DO NOT USE FOR:
+- operating outside the current workspace
+- installing toolchains from scratch

package/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.