harness-everything 0.11.5 → 0.11.7

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

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

@@ -1,64 +1,61 @@
 # Workflow: Verify Before Claim
 
-> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
+> Check external framework, SDK, CLI, and API claims plus any unmeasured performance or cost numbers against an authoritative source, then deliver a cited claim, a real measurement, or a labeled estimate.
 
----
+Source of truth: `verify-before-claim/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — Trigger: external behavior, version/config/exit-code claim, or unmeasured number. Output: official citation, real measurement, or explicitly labeled estimate. State mutation: none; evidence travels with the claim. Gate: official source or real measurement; unresolved claims stay inconclusive. USE FOR: stating how an external framework, SDK, CLI tool, or API behaves; quoting performance, cost, latency, or timing numbers; answering "does X support Y" or version-specific questions; citing defaults, exit codes, config flags, pricing, or rate limits. DO NOT USE FOR: claims about this repository's own code, facts the user supplied directly, generic CS knowledge such as Big-O.
 
-This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  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
+  Claim[External Claim Or Unmeasured Number] --> Scope{Claim Scope?}
+  Scope -->|this repo own code| Local[Read Local Source Report Observed Facts]
+  Scope -->|external behavior or number| Official[Consult Official Docs First]
+  Official --> Numbers{Needs Number?}
+  Numbers -->|yes| Measure[Real Measurement Or Labeled Estimate]
+  Numbers -->|no| Cite[Return Cited Claim]
+  Measure --> Output[Claim With Evidence]
+  Cite --> Output
+  Local --> Output2[Fact From Source]
+  Official -->|contradiction or missing evidence| Inconclusive[Report Inconclusive]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `verify-before-claim` 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"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
-  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"]
+graph TD
+  ExtBehave[State External Framework SDK CLI API Behavior] --> Skill[verify-before-claim SKILL]
+  PerfNum[Quote Perf Cost Latency Timing] --> Skill
+  SupportQ[Does X Support Y Version Question] --> Skill
+  ConfigQ[Cite Default ExitCode Flag Pricing Limit] --> Skill
+  OwnCode[Claim About This Repo Own Code] --> LocalSrc[Read Actual Source]
+  UserFact[Fact User Supplied Directly] --> Decline[Do Not Route]
+  GenericCS[Generic CS Knowledge BigO] --> Decline
+  Skill --> Cited[Cited Claim Or Measurement Or Estimate]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
+## 3. Real-World Use Case
 
-Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
+A developer is about to assert a version-specific SDK default and a latency number in a design note. The skill routes the default to official documentation for a citation, routes the latency claim to a real measurement, and labels the value an estimate when no run exists. If sources contradict each other or no authoritative source exists, the result is reported as inconclusive rather than asserted as certain, even under time pressure.
 
 ```mermaid
 graph TD
-  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
-  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
-  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
-  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
-  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
-  UpdateCode --> Done([Potential production runtime crash prevented])
+  Draft[Draft Asserts SDK Default And Latency] --> CheckDocs[Check Official Docs For Default]
+  CheckDocs --> CheckNum[Require Real Measurement For Number]
+  CheckNum -->|measured| Cited2[Cited Default Plus Measured Number]
+  CheckNum -->|no run| Labeled[Labeled Estimate]
+  CheckDocs -->|conflict or gap| Inconc[Inconclusive Report]
 ```
 
----
+Deep dive: `verify-before-claim/references/verification-guide.md`.
 
 ## 4. Verification Check
 
-To ensure that the `verify-before-claim` 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.
+- [ ] Local-repository claims were settled by reading the actual source, not by external citation
+- [ ] External framework, SDK, CLI, or API behavior used official documentation first with a citation
+- [ ] Performance, cost, latency, or timing numbers came from a real measurement or were explicitly labeled as estimates
+- [ ] Defaults, exit codes, config flags, pricing, and rate limits were cited rather than asserted from memory
+- [ ] Contradictions or missing evidence were reported as inconclusive
+- [ ] No unverified external fact was claimed as certain, even under time pressure