harness-everything 0.11.6 → 0.12.0

package/docs/workflows/security-review.md

@@ -1,77 +1,58 @@
 # Workflow: Security Review
 
-> Automated security scanning, threat modeling, and input-validation reviews to identify potential security holes and enforce robust safety guardrails.
+> Runs STRIDE threat modeling, scans secrets with the audit script, and hardens code against OWASP Top 10 risks using three-tier boundary controls — for auth, inputs, uploads, secrets, and pre-deploy audits.
+
+Source of truth: `security-review/SKILL.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `security-review` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Code Refactoring / Feature Done / Security Audit]) --> STRIDE["1. STRIDE Threat Modeling & Abuse Case Design"]
-  STRIDE --> CheckScript{2. Is audit-secrets.js Executable?}
-  
-  CheckScript -->|Yes| RunAudit["Run node security-review/scripts/audit-secrets.js"]
-  CheckScript -->|No / Fails| GrepFallback["Scan Workspace Secrets & Inputs via grep_search"]
-  
-  RunAudit --> CheckVun{3. Detect Vulnerabilities or Leaks?}
-  GrepFallback --> CheckVun
-  
-  CheckVun -->|Hardcoded Secrets| FixSecrets["Always Do: Refactor to process.env & .env.local"]
-  CheckVun -->|SQL Concatenation| FixSQL["Always Do: Refactor to Parameterized Queries / ORM"]
-  CheckVun -->|Unvalidated Input| FixInput["Always Do: Add Zod Schema Validation"]
-  CheckVun -->|High-Risk Auth Shift| AskUser["Ask First: Require User Approval for Auth Shift"]
-  
-  FixSecrets --> CompileSecurityReport["4. Compile Security Audit Report"]
-  FixSQL --> CompileSecurityReport
-  FixInput --> CompileSecurityReport
-  AskUser -->|Approved| CompileSecurityReport
-  CheckVun -->|Clean| CompileSecurityReport
-  
-  CompileSecurityReport --> ResolveReportPath{5. Resolve Audit Report Path}
-  ResolveReportPath -->|docs/ Exists| WriteDocs["Save to docs/security-audit.md"]
-  ResolveReportPath -->|Protected / No Folder| WritePlatform["Save to .github/harness-everything/security-audit.md"]
-  
-  WriteDocs --> End([Codebase hardened and verified secure])
-  WritePlatform --> End
+  ThreatModel["Threat-model with STRIDE per guides/STRIDE-THREAT-MODEL.md; misuse-case every endpoint and input"] --> SecretScan["Scan secrets and injection risks with audit script"]
+  SecretScan --> FixHarden["Fix findings per boundary system"]
+  FixHarden --> AuditReport["Write audit report to docs or platform dir"]
+  AuditReport --> DoneSecure["Codebase hardened; report recorded"]
 ```
 
----
+```mermaid
+graph TD
+  ScanCmd["Run node security-review/scripts/audit-secrets.js"] --> ScanGate["Gate: secret scan via script or grep before concluding"]
+  ScanGate --> AlwaysDo["Always Do: parameterize SQL, Zod-validate inputs, httpOnly cookies, secrets to process.env"]
+  AlwaysDo --> NeverDo["Never Do: no hardcoded secrets, no password logging, no eval or unescaped innerHTML"]
+  NeverDo --> ReportPath["Report to docs/security-audit.md or .github/harness-everything/security-audit.md"]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `security-review` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Pre-flight / Quality PR reviews| SecReview["security-review / SKILL.md"]
-  SecReview -->|Informs security tests written in| TDD["tdd / SKILL.md"]
-  SecReview -->|Integrated as mandatory PR gate in| VerLoop["verification-loop / SKILL.md"]
+  AuthReq["AuthN or authZ implementation"] --> SecSkill["security-review / SKILL.md"]
+  InputReq["User input, uploads, new API endpoints"] --> SecSkill
+  SecretReq["Secrets, credentials, payment features"] --> SecSkill
+  AuditReq["Security audit before production deploy"] --> SecSkill
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `security-review` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
-graph TD
-  Start["New search feature: executes system shell query using raw user input string"] --> Trigger["security-review skill runs"]
-  Trigger --> Scan["Flags potential command injection vulnerability in search.js"]
-  Scan --> Propose["Propose input sanitization and switching to child_process.execFile with argument array"]
-  Propose --> Implement["Refactor code to use safe argument arrays instead of raw string shell execution"]
-  Implement --> Done([Critical remote code execution vulnerability resolved])
+graph LR
+  SecSkill2["security-review / SKILL.md"] -->|Produces| ThreatOut["Threat model + scan + hardened code + audit report"]
+  PerfReq["Performance profiling"] -->|Out of scope| NotSec["Not security-review"]
+  A11yReq["Accessibility or UI styling fixes"] -->|Out of scope| NotSec
+  PlainReview["Code review without security scope"] -->|Out of scope| NotSec
 ```
 
----
+## 3. Real-World Use Case
 
-## 4. Verification Check
+A new profile endpoint accepts a username and avatar upload before a production deploy. The skill threat-models it with STRIDE, misuse-cases the input and upload path, runs `node "security-review/scripts/audit-secrets.js"`, finds an unvalidated input and a hardcoded secret, fixes them per the boundary system (Zod validation, secret moved to `process.env`, parameterized query), and writes the report to `<workspace>/docs/security-audit.md`, falling back to `<workspace>/.github/harness-everything/security-audit.md` when `docs/` is protected or absent.
 
-To ensure that the `security-review` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] STRIDE threat model completed per `security-review/guides/STRIDE-THREAT-MODEL.md`, with misuse-case for every endpoint and input
+- [ ] Secret and injection scan run via `security-review/scripts/audit-secrets.js`, or grep, before concluding
+- [ ] OWASP patterns checked per `security-review/guides/OWASP-PATTERNS.md` and `security-review/references/security-checklist.md`
+- [ ] Always Do applied: parameterized SQL, Zod-validated inputs, httpOnly cookies, secrets in `process.env`
+- [ ] Ask First respected: CORS changes, auth and login flows, file uploads, rate limits
+- [ ] Never Do respected: no committed hardcoded secrets, no logged passwords or tokens, no `eval()` or unescaped `innerHTML`
+- [ ] Audit report written to `<workspace>/docs/security-audit.md`, or `<workspace>/.github/harness-everything/security-audit.md` when docs is protected or absent
+- [ ] Scope kept to auth, inputs, uploads, endpoints, secrets, and audits — not general review, performance, or UI styling

package/docs/workflows/skill-creator.md

@@ -1,80 +1,63 @@
 # Workflow: Skill Creator
 
-> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
+> Authors, audits, and refactors SKILL.md files against the Skill Contract quality bar — for new skills, SKILL.md refactors, overlap checks, and packaging insights as dynamic skills.
+
+Source of truth: `skill-creator/SKILL.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call after LLM selection]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
-  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
-  Draft --> Test["Test 2-3 realistic prompts via multi-agent-workspace: with-skill subagent vs baseline subagent"]
-  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
-  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
-  Prune --> Checklist
-  Checklist -->|Passes| Route{Static or dynamic?}
-  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
-  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/ & register-dynamic-skill.js to manifest.json, metadata.type=dynamic, status=draft"]
-  Register --> End([Skill live in the repo, single source of truth for its own description])
-  DynamicContract --> End
+  NewReq["Trigger: new skill, SKILL.md audit, or self-evolve packaging"] --> DupGrep["Grep registry for near-duplicates; when-to-fire sentence becomes description"]
+  DupGrep --> DraftContract["Draft Contract table first, then USE FOR and DO NOT USE FOR, then steps or flat reference"]
+  DraftContract --> PushRef["Push branch-only detail to references/"]
+  PushRef --> ABTest["A/B-test via multi-agent-workspace subagents; read both transcripts"]
+  ABTest --> QualityGate["Quality Checklist gate before registering"]
+  QualityGate --> RegisterOut["Output: SKILL.md passing Quality Checklist; writes SKILL.md and updates registry or generated folder"]
 ```
 
----
+```mermaid
+graph TD
+  DynamicReq["Dynamic path: only generalizable procedures qualify"] --> SimpleRule["Simple constraints go to memories/repo/RULES.md"]
+  SimpleRule --> DynLoc["Location: workspace/.claude/harness-everything/skills/generated/kebab-case-name/SKILL.md"]
+  DynLoc --> DynFront["Frontmatter: triggers, type generated, source, status draft"]
+  DynFront --> DynLife["Lifecycle: draft to active after firing elsewhere; deprecate, do not delete; promote once proven general"]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how `skill-creator` is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
-  Creator -->|With/without test subagents| Launcher["multi-agent-workspace / SKILL.md"]
-  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
-  Evolve["self-evolve / SKILL.md §4"] -->|LLM decides to promote insight| Creator
-  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
-  Generated -->|Registered in| Manifest["manifest.json 'generated' registry"]
-  Manifest -->|Matched & auto-loaded by| Router
+  CreateReq["Create a skill from scratch"] --> CreatorSkill["skill-creator / SKILL.md"]
+  AuditReq["Audit or refactor a SKILL.md; check overlap"] --> CreatorSkill
+  PackageReq["Packaging a session insight as a dynamic skill"] --> CreatorSkill
+  CreatorSkill --> ChecklistOut["Gate: Quality Checklist, incl. USE FOR and DO NOT USE FOR"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
-
 ```mermaid
-graph TD
-  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
-  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
-  Draft1 --> Test1["Spawn with/without subagents via multi-agent-workspace on 2-3 realistic prompts"]
-  Test1 --> Check1{Quality Checklist passes?}
-  Check1 -->|No| Fix1["Fix flagged item, re-test"]
-  Fix1 --> Check1
-  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
-  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
-
-  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Decide2{"LLM: Does it warrant a standalone complex skill?"}
-  Decide2 -->|No: Simple Tip| Save2["persist-memory.js writes simple rule to RULES.md"]
-  Decide2 -->|Yes: Complex Skill| Trigger2["self-evolve §3 Step 3: Promote to Dynamic Skill"]
-  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
-  Load2 --> Gate2{Quality Checklist §3 passes?}
-  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
-  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md & run register-dynamic-skill.js"]
-  Write2 --> Done2([Dynamic skill available next session via manifest registration and tier-router.js scan])
-  Save2 --> Done3([Simple memory rule available in RULES.md])
+graph LR
+  CreatorSkill2["skill-creator / SKILL.md"] -->|A-B tests with| MultiAgent["multi-agent-workspace subagents"]
+  NonSkillDocs["Non-skill project docs"] -->|Use instead| RepoDocs["repo-docs or to-spec"]
+  ThirdParty["Third-party skill discovery"] -->|Use instead| FindSkills["find-skills"]
+  StyleOnly["Code style outside SKILL.md files"] -->|Out of scope| NotCreator["Not skill-creator"]
 ```
 
----
+## 3. Real-World Use Case
 
-## 4. Verification Check
+A team wants a new `deploy-preview` skill. The author greps the registry for near-duplicates, writes the when-to-fire sentence as the description, drafts the Contract table first with its enforcement gate, then `USE FOR` and `DO NOT USE FOR`, then the steps, pushing long detail to `references/`. They A/B-test via `multi-agent-workspace` subagents, read both transcripts, run the Quality Checklist (`skill-creator/references/quality-checklist.md`), and only then register. A separate small tip discovered mid-session does not qualify as a dynamic skill and goes to `<workspace>/memories/repo/RULES.md`.
 
-To ensure that the `skill-creator` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Registry grep for near-duplicates completed; description written as the when-to-fire sentence
+- [ ] Contract table drafted first to force the enforcement gate
+- [ ] `USE FOR` and `DO NOT USE FOR` present before steps or flat reference
+- [ ] Branch-only detail pushed to `references/` (e.g. `skill-creator/references/quality-checklist.md`)
+- [ ] A/B-tested via `multi-agent-workspace` subagents and both transcripts read
+- [ ] Quality Checklist passed before registering, including `USE FOR` / `DO NOT USE FOR` consistency
+- [ ] Output is a SKILL.md passing the Quality Checklist; `<skill>/SKILL.md` written and registry or generated folder updated
+- [ ] Dynamic path gated by Quality Checklist first; location, frontmatter triggers, generated type, and draft status correct
+- [ ] Dynamic lifecycle respected: draft to active after firing elsewhere; deprecate, do not delete; promote once proven general
+- [ ] Only generalizable procedures kept as skills; simple constraints sent to `<workspace>/memories/repo/RULES.md`
+- [ ] Not misused for non-skill docs, third-party discovery, or code style outside SKILL.md files

package/docs/workflows/skill-style.md

@@ -1,64 +1,59 @@
 # Workflow: Skill Style
 
-> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
+> Applies the Harness writing standard to SKILL.md files — covering new skills, structure reviews, naming and frontmatter conventions, tone, formatting, and progressive disclosure across the catalog.
+
+Source of truth: `skill-style/SKILL.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
-  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
-  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
-  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
-  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
-  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
-  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
-  FixSkillFile --> SaveSkillFile
-  SaveSkillFile --> End([Skill document aligned with professional guidelines])
+  TriggerEdit["Trigger: creating, reviewing, or refactoring a Harness SKILL.md"] --> FrontAccurate["Keep frontmatter accurate and description routeable"]
+  FrontAccurate --> OrderCheck["Include in order: title, introduction, Skill Contract, usage, actionable rules"]
+  OrderCheck --> ImperativeGate["Use imperative language and name the enforcing command or gate"]
+  ImperativeGate --> OverlapCheck["Avoid overlap with OS-layer routing or domain expertise"]
+  OverlapCheck --> ConsistencyGate["Gate: npm run test:consistency plus style-guide review"]
+  ConsistencyGate --> ConciseOut["Output: concise, complete, non-overlapping SKILL.md"]
 ```
 
----
+```mermaid
+graph TD
+  StyleGuide["Deep dive: skill-style/references/style-guide.md"] --> ToneFormat["Standardize tone, formatting, and progressive disclosure"]
+  ToneFormat --> NoMutate["State mutations: none; writing and review standard only"]
+  NoMutate --> OverlapAvoid["No overlap with existing catalog entries"]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
-  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
-  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
+  NewSkillReq["Creating a new SKILL.md file"] --> StyleSkill["skill-style / SKILL.md"]
+  RefactorReq["Refactoring or reviewing an existing SKILL.md"] --> StyleSkill
+  ToneReq["Deciding tone, structure, or enforcement style"] --> StyleSkill
+  OverlapReq["Checking overlap with an existing skill"] --> StyleSkill
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
-
 ```mermaid
-graph TD
-  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
-  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
-  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
-  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
-  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
-  Fix --> Checklist
-  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
-  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
+graph LR
+  StyleSkill2["skill-style / SKILL.md"] -->|For intent interviews, drafting, prompt tests| CreatorSkill["skill-creator / SKILL.md"]
+  DynRoute["Routing rules for dynamically generated mid-session skills"] -->|Owned by| SelfEvolve["self-evolve"]
+  NonHarness["Non-Harness skill formats outside harness-everything"] -->|Out of scope| NotStyle["Not skill-style"]
 ```
 
----
+## 3. Real-World Use Case
 
-## 4. Verification Check
+An author drafts a new `backup-restore` SKILL.md and runs a style pass. They tighten the frontmatter description for routing, reorder the file to title, introduction, Skill Contract, usage, and actionable rules, rewrite vague advice in imperative language naming `npm run test:consistency` as the gate, remove duplicated routing already owned elsewhere, and check `skill-style/references/style-guide.md`. Intent interviewing and prompt testing are handed to `skill-creator/SKILL.md` per the Core Rules.
 
-To ensure that the `skill-style` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Frontmatter accurate and description routeable
+- [ ] File includes in order: title, introduction, Skill Contract, usage, and actionable rules
+- [ ] Imperative language used with the enforcing command or gate named (`npm run test:consistency` plus style-guide review)
+- [ ] No overlap with OS-layer routing or domain expertise; catalog overlap checked
+- [ ] Tone, formatting, and progressive disclosure standardized per `skill-style/references/style-guide.md`
+- [ ] State mutations are none — treated as a writing and review standard only
+- [ ] Intent interviews, drafting, and prompt tests routed to `skill-creator/SKILL.md`, not handled here
+- [ ] Routing rules for dynamically generated mid-session skills left to `self-evolve`
+- [ ] Not applied to non-Harness skill formats outside `harness-everything`

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

@@ -1,67 +1,63 @@
 # Workflow: Using Git Worktrees
 
-> Manages isolated workspace environments in parallel using native Git Worktrees, enabling developers to switch contexts safely without stashing or losing unsaved progress.
+> Start isolated when feature work needs it: prefer native worktree entry before implementation plans, with raw git worktree as fallback.
 
----
+Source of truth: `using-git-worktrees/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — USE FOR: Tier 3 / Fable-class mutable engineering, feature work needing isolation, pre-implementation-plan setup. DO NOT USE FOR: nesting inside an existing worktree, read-only analysis with no mutation, branch/merge workflows unrelated to workspace isolation.
 
-This section visualizes how the `using-git-worktrees` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  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])
+  Detect[Step0 Detect Isolation] --> Isolated{Already Isolated?}
+  Isolated -->|git-dir differs from git-common-dir, no superproject| Setup[Step2 Setup Dependencies]
+  Isolated -->|same dirs or needs isolation| NestGuard{Nesting Check}
+  NestGuard -->|inside existing worktree| BlockedA[BLOCKED Never Nest]
+  NestGuard -->|top-level repo| Create[Step1 Create Enter Worktree]
+  Create -->|native EnterWorktree or worktree flag| Setup
+  Create -->|fallback git worktree add| Setup
+  Create -->|creation-entry failure| BlockedB[BLOCKED Major Mode]
+  Setup --> Baseline[Step3 Baseline Tests and Build]
+  Baseline --> Ready([Isolated Workspace Ready])
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `using-git-worktrees` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: worktree / isolate / checkout| WT["using-git-worktrees / SKILL.md"]
-  WT -->|Maintains isolation before running tests in| TDDSkill["tdd / SKILL.md"]
-  WT -->|Protects terminal environment testing in| EnvSkill["environment-detection / SKILL.md"]
+graph TD
+  Tier3[Tier3 Fable Mutable Engineering] --> Skill[using-git-worktrees SKILL]
+  Feature[Feature Work Needing Isolation] --> Skill
+  PrePlan[Pre-Implementation Plan Setup] --> Skill
+  Skill --> SkillDetect[Detect Adapted Per environment-detection]
+  ReadOnly[Read-Only Analysis No Mutation] --> Decline[Do Not Route]
+  Nested[Nesting Inside Existing Worktree] --> Decline
+  BranchOnly[Branch Merge Unrelated To Isolation] --> Decline
+  SkillDetect --> IsolatedPath[Reuse Or Create Linked Worktree]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `using-git-worktrees` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Working on deep feature 'feat-billing' (unstaged edits)"] --> Interrupt["Urgent production hotfix required!"]
-  Interrupt --> Trigger["using-git-worktrees skill invoked"]
-  Trigger --> CreateWT["Add worktree: 'git worktree add ../hotfix-auth hotfix-branch'"]
-  CreateWT --> OpenWT["Open separate workspace editor in ../hotfix-auth"]
-  OpenWT --> FixBug["Fix auth bug & run verification test"]
-  FixBug --> CommitWT["Commit fix and push branch"]
-  CommitWT --> CloseWT["Close editor, run 'git worktree prune'"]
-  CloseWT --> Resume["Return to original billing workspace with all unsaved files exactly where they were"]
-  Resume --> Done([Context switched safely with zero stashing friction])
+  Request[Feature Branch Requested With Clean Isolation] --> Detect2[Run git rev-parse git-dir common-dir branch superproject]
+  Detect2 -->|not isolated| Enter[Enter Native Worktree Else git worktree add]
+  Enter --> Setup2[Install Dependencies As Needed]
+  Setup2 --> Base2[Run Relevant Tests and Build Before Mutation]
+  Base2 -->|pre-existing failures| Surface[Surface Failures Before Implementation]
+  Base2 -->|clean| Implement[Proceed With Implementation]
+  Surface --> Implement
 ```
 
----
+Ordinary-mode note: only ordinary isolation-needing work may honor an explicit user preference to stay in place after a decline or unsupported environment. Major mode never falls back to the primary tree.
 
-## 4. Verification Check
+Deep dive: `using-git-worktrees/references/workflow-details.md`.
 
-To ensure that the `using-git-worktrees` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Tier 3 / Fable-class source or artifact mutation occurs only in a verified isolated worktree; otherwise state is `BLOCKED`
+- [ ] No worktree is nested inside an already isolated worktree
+- [ ] Isolation detection used `git rev-parse --git-dir`, `git rev-parse --git-common-dir`, `git branch --show-current`, and `git rev-parse --show-superproject-working-tree`; a submodule counted as a normal repo
+- [ ] Entry preferred native `EnterWorktree`, `/worktree`, or `--worktree` before `git worktree add "$path" -b "$BRANCH_NAME"`; major mode chose an already-ignored or external/sibling path
+- [ ] Creation or entry failure yields `BLOCKED` in major mode; in-place continuation happened only in ordinary mode after explicit decline or unsupported environment
+- [ ] Dependencies were installed as needed, then relevant tests/build ran in the isolated tree with pre-existing failures surfaced before mutation

package/docs/workflows/verification-loop.md

@@ -1,71 +1,66 @@
 # Workflow: Verification Loop
 
-> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
+> Run the objective gates — build, types, lint, tests, security, diff — and only claim done when the evidence-backed report passes.
 
----
+Source of truth: `verification-loop/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — Trigger: completed implementation or change awaiting delivery. Output: evidence-backed verification report and delivery decision. USE FOR: verify a feature or change before delivery, run quality gates before a PR. DO NOT USE FOR: fixing failures without re-running the loop, writing new features or tests (use `tdd`).
 
-This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  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])
+  Start[Completed Change Awaiting Delivery] --> Build[Gate1 Build npm run build]
+  Build --> Types[Gate2 Types tsc noEmit or pyright]
+  Types --> Lint[Gate3 Lint npm run lint or ruff]
+  Lint --> Tests[Gate4 Tests npm run test coverage]
+  Tests --> Security[Gate5 Security Secrets StrayLogs]
+  Security --> Diff[Gate6 Diff git diff stat]
+  Diff --> Report[Fill verification-report template]
+  Report --> Decision{All Gates Pass?}
+  Decision -->|yes| Deliver([Delivery Decision Ready])
+  Decision -->|no| Fix[Fix Cause Rerun From First Affected Gate]
+  Fix --> Build
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `verification-loop` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Pre-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
-  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
-  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
-  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
+graph TD
+  VerifyReq[Run Full Verification Loop Request] --> Skill[verification-loop SKILL]
+  DeliveryReq[Verify Before Delivery Request] --> Skill
+  PRReq[Quality Gates Before PR] --> Skill
+  DesignOnly[Design Discussion No Completed Work] --> Decline[Do Not Route]
+  PlanOnly[Planning Without Code Changes] --> Decline
+  NewWork[Write New Features Tests] --> TDD[tdd SKILL]
+  Skill --> Gates[Build Type Lint Test Security Diff]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
-  Trigger --> Build["Run 'npm run build' -> Succeeded"]
-  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
-  Type --> FixT["Fix incorrect type casting in routes.ts"]
-  FixT --> Recheck["Re-run typecheck -> Succeeded"]
-  Recheck --> Lint["Run 'npm run lint' -> Clean"]
-  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
-  Tests --> Done([Verification loop complete; safe to open PR])
+  Done[Feature Implemented Awaiting PR] --> B[Run npm run build]
+  B -->|pass| T[Run npx tsc noEmit]
+  T -->|fail| FixT[Fix Type Errors]
+  FixT --> B
+  T -->|pass| L[Run npm run lint]
+  L -->|pass| TS[Run npm run test coverage]
+  TS -->|pass| Sec[Check Secrets And Stray Logs]
+  Sec --> D[Check git diff stat For Unintended Changes]
+  D --> R[Fill templates verification-report template md]
+  R --> PR[Report Evidence And Delivery Decision]
 ```
 
----
+Template: `verification-loop/templates/verification-report.template.md`. Deep dive: `verification-loop/references/verification-phases.md`.
 
 ## 4. Verification Check
 
-To ensure that the `verification-loop` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] No completion was claimed until every applicable gate passed
+- [ ] Build gate ran (`npm run build`) with evidence recorded
+- [ ] Type gate ran (`npx tsc --noEmit` or `pyright .`) with evidence recorded
+- [ ] Lint gate ran (`npm run lint` or `ruff check .`) with evidence recorded
+- [ ] Test and coverage gate ran (`npm run test -- --coverage`) with evidence recorded
+- [ ] Security gate checked secrets and stray logs with evidence recorded
+- [ ] Diff gate checked `git diff --stat` and unintended changes with evidence recorded
+- [ ] `templates/verification-report.template.md` was filled with evidence, and any failure was fixed then rerun from the first affected gate rather than patched without a rerun