harness-everything 0.11.6 → 0.11.7

package/docs/workflows/rewrite-commits.md

@@ -1,60 +1,64 @@
 # Workflow: Rewrite Commits
 
-> Safely rewrites or squashes a specified range of commits into highly professional, Conventional Commits (Angular style) on a new branch.
+> Rewrites past Git history into Angular Style messages — cleaning unpushed commits before a PR, squashing fixups, rewording, and reordering safely on a temp branch with abort on conflict.
+
+Source of truth: `rewrite-commits/SKILL.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `rewrite-commits` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Define Commit Range]) --> BackupBranch["Create a backup branch of current state"]
-  BackupBranch --> ReadCommits["Read all commit messages in the range"]
-  ReadCommits --> AnalyzeDiffs["Read files & diffs associated with each commit"]
-  AnalyzeDiffs --> GenNewMessages["Generate high-quality Angular-style messages for each diff"]
-  GenNewMessages --> SoftReset["Execute git reset --soft to merge range changes"]
-  SoftReset --> ReapplyCommits["Re-apply changes with perfectly clean, segmented commit history"]
-  ReapplyCommits --> VerifyBranch["Run verification checks on the final rebuilt branch"]
-  VerifyBranch --> End([Perfectly clean Git history on new branch])
+  DiscoverRange["Discover: git log --oneline -n <num> to confirm range"] --> PushedGuard{"Pushed to remote main/master?"}
+  PushedGuard -->|Yes| WarnConfirm["Warn and require secondary human confirmation"]
+  PushedGuard -->|No| TempBranch["Create temp branch for rewrite"]
+  WarnConfirm --> TempBranch
+  TempBranch --> ResetSoft["Rewrite via git reset --soft HEAD~N plus structured commits"]
+  ResetSoft --> AngularMsg["Messages follow Angular Style per git-commit skill"]
+  AngularMsg --> ConfirmLog["Confirm with git log --oneline"]
+  ConfirmLog --> ConflictCheck{"Merge conflict?"}
+  ConflictCheck -->|Yes| AbortStop["Run git rebase --abort, STOP, hand to human or zoom-out"]
+  ConflictCheck -->|No| DoneHistory["Rewritten Angular-Style history on temp branch"]
 ```
 
----
+```mermaid
+graph TD
+  NoRebaseI["Gate: no bare interactive git rebase -i"] --> ScriptOpt["Use git reset --soft or Node.js scripting, no hardcoded sed -i"]
+  ScriptOpt --> DeepRef["Deep dive: rewrite-commits/references/workflow.md"]
+  DeepRef --> ConfirmOut["Expected output: temp-branch history confirmed via git log --oneline"]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `rewrite-commits` 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: commit / rewrite / squash| Rewrite["rewrite-commits / SKILL.md"]
-  Rewrite -->|Supplements convention templates in| GitCommit["git-commit / SKILL.md"]
-  Rewrite -->|Pre-verify rewritten commits via| VerLoop["verification-loop / SKILL.md"]
+  UserReq["User requests cleaning, squashing, or rewriting past history to Angular Style"] --> RewriteSkill["rewrite-commits / SKILL.md"]
+  RewriteSkill --> TempOut["Output: rewritten history on temp branch"]
+  RewriteSkill --> AbortPath["On conflict: git rebase --abort + handover"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `rewrite-commits` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
-graph TD
-  Start["Branch has messy commits: 'fixed stuff', 'more fixes', 'bug'"] --> Trigger["Rewrite-commits skill run for HEAD~3"]
-  Trigger --> Backup["Backup branch 'backup-feature-x' created"]
-  Trigger --> GatherDiffs["Analyze total diff across the 3 messy commits"]
-  GatherDiffs --> Generate完美["Determine changes relate to user auth session handling"]
-  Generate完美 --> Rebuild["Reset and make 1 perfect commit: 'fix(auth): correct token refresh race condition'"]
-  Rebuild --> Done([Clean, reviewable PR history ready])
+graph LR
+  RewriteSkill2["rewrite-commits / SKILL.md"] -->|Message conventions per| GitCommit["git-commit skill"]
+  RewriteSkill2 -->|Conflict handover to| ZoomOut["zoom-out"]
+  NewCommitReq["New commits on current work"] -->|Not this skill| GitCommit
+  PushedMain["Rewrite of pushed main/master without confirmation"] -->|Blocked| NeedConfirm["Require explicit human confirmation"]
 ```
 
----
+## 3. Real-World Use Case
 
-## 4. Verification Check
+A branch has 4 messy unpushed commits before a PR (`wip`, `fix`, `oops`, `final fix`). The user asks to squash to Angular Style. The skill runs `git log --oneline -n 4` to confirm the range, verifies the commits are not pushed to `main`, creates a temp branch, uses `git reset --soft HEAD~4` plus structured recommits with Angular Style messages, then confirms with `git log --oneline`. If a rebase conflict appears, it runs `git rebase --abort`, stops, and hands over for a human decision.
 
-To ensure that the `rewrite-commits` 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.
+- [ ] Range confirmed with `git log --oneline -n <num>` before rewriting
+- [ ] Rewrite done on a temp branch first, not directly on `main` / release branches
+- [ ] No bare interactive `git rebase -i` used; used `git reset --soft HEAD~<N>` or script editors
+- [ ] No hardcoded `sed -i` scripting used
+- [ ] All new messages follow Angular Style per the `git-commit` skill
+- [ ] Final history confirmed with `git log --oneline`
+- [ ] If commits were pushed to remote `main` / `master`, warned and obtained secondary human confirmation
+- [ ] On merge conflict, ran `git rebase --abort`, stopped, and handed over instead of resolving beyond abort
+- [ ] Not used for creating new commits on current work (belongs to `git-commit`)
+- [ ] Deep detail checked in `rewrite-commits/references/workflow.md` where needed

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