harness-everything 0.2.2 → 0.4.0

package/docs/workflows/security-review.md

@@ -10,13 +10,32 @@ This section visualizes how the `security-review` skill executes internally, det
 
 ```mermaid
 graph TD
-  Start([Code Refactoring / Feature Done]) --> ScanInputs["Locate all user input and API boundary points"]
-  ScanInputs --> ThreatModeling["Perform threat modeling on data flow"]
-  ThreatModeling --> CheckCommonVulnerabilities["Check for SQL Injection, XSS, CSRF, and broken access controls"]
-  CheckCommonVulnerabilities --> AuditDependencies["Scan package dependencies for known CVE vulnerabilities"]
-  AuditDependencies --> FlagSinks["Flag insecure coding patterns, hardcoded secrets, or raw exec commands"]
-  FlagSinks --> CompileSecurityReport["Compile actionable security hardening proposal"]
-  CompileSecurityReport --> End([Codebase hardened and verified secure])
+  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
 ```
 
 ---

package/docs/workflows/self-evolve.md

@@ -1,59 +1,75 @@
 # Workflow: Self-Evolve
 
-> Analyzes execution logs and session memories to extract underlying root causes, defining new error boundaries and compressing them into cognitive guardrails.
+> The host agent supplies relevant session evidence and a generalized root-cause analysis. `self-evolve` classifies, validates, and persists the lesson; it does not collect host transcripts.
 
----
+Load `self-evolve/references/memory-resolution.md` on demand when the persistence decision, fallback path, lazy-loading rule, or dynamic-skill registration details are needed.
 
-## 1. Skill Behavior Workflow
+## 1. Responsibility boundary
 
-This section visualizes how the `self-evolve` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+The host agent may inspect the current session and any history explicitly exposed by the host. It selects the evidence and states the reusable root cause. `self-evolve` MUST NOT scan global host transcript stores or persist raw transcripts.
+
+## 2. Persistence flow
 
 ```mermaid
 graph TD
-  Start([Task Completed / Error Loop Triggered]) --> ReadSessionLogs["Read active debugging logs & session history"]
-  ReadSessionLogs --> IdentifyRootCauses["Isolate and extract system failures or bottlenecks"]
-  IdentifyRootCauses --> SynthesizeGuardrails["Formulate actionable high-level cognitive guardrails"]
-  SynthesizeGuardrails --> CompressMemories["Compress repetitive events into compact markdown files in /memories/"]
-  CompressMemories --> UpdateUserMemory["Commit lessons learned to user memory space"]
-  UpdateUserMemory --> End([Agent cognitive defense expanded for future sessions])
+  Start([Agent has resolved a recurring problem]) --> Evidence["Agent selects allowed evidence and states root cause"]
+  Evidence --> Memory{Existing workspace memory?}
+  Memory -->|Yes| Lines{Target under 60 lines?}
+  Memory -->|No| Route["Choose workspace memory fallback"]
+  Lines -->|Yes| Append["Append concise rule"]
+  Lines -->|No| Modular["Create topic memory and add lazy-load pointer"]
+  Route --> Append
+  Append --> Validate["Run self-evolve self-regression and quality gates"]
+  Modular --> Validate
+  Evidence -->|Reusable multi-step pattern| Dynamic["Load skill-creator, create draft skill, register generated[]"]
+  Dynamic --> Validate
+  Validate --> Done([Lesson persisted])
 ```
 
----
+## 3. Triggering and routing
 
-## 2. Triggering and Routing Path
+The agent invokes `self-evolve/SKILL.md` after a resolved struggle, zoom-out recovery, or explicit request. It passes the selected evidence and root cause to `persist-memory.js`, or routes a reusable pattern through `skill-creator` and `register-dynamic-skill.js`. The router later matches registered `generated[]` metadata; this is not an automatic transcript scan.
 
-This diagram illustrates how the `self-evolve` 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.
+## 4. Example
 
-```mermaid
-graph LR
-  SessionEnd["Task Completed / Session Closed"] --> Evolve["self-evolve / SKILL.md"]
-  Evolve -->|Reads from| HistoryLog["VS Code Debug logs & memory directories"]
-  Evolve -->|Writes permanent updates to| UserMemory["/memories/ / user-memory files"]
-  Evolve -->|Informs future task triage in| Router["harness-everything / tier-router.js"]
-```
+After resolving a recurring Windows path error, the agent summarizes the cause, checks existing memory, and chooses either a concise rule or a draft dynamic skill. It runs the relevant quality/self-regression gate before persistence and records only the generalized lesson.
+
+## 5. Verification checklist
 
----
+- [ ] Evidence came from the host context the agent is authorized to inspect.
+- [ ] No raw transcript, secret, or one-off detail was persisted.
+- [ ] Rule/dynamic-skill classification and deduplication passed.
+- [ ] Self-regression passed before the memory or manifest changed.
 
-## 3. Real-World Use Case Flowchart
+## Persistence boundary
 
-Here we model concrete real-world scenarios and use cases of the `self-evolve` skill, illustrating standard success paths, error handling, or recovery loops.
+The host supplies selected evidence. `self-evolve` receives only that brief,
+then chooses a small rule or a reusable skill. It never scans transcript
+stores on its own.
 
 ```mermaid
-graph TD
-  Start["Session ends after solving a recurring, messy Windows path-slashes bug"] --> Trigger["self-evolve skill runs automatically"]
-  Trigger --> Analyze["Reads last 5 execution logs"]
-  Analyze --> DetectPattern["Finds 3 consecutive terminal command failures caused by path backslashes in PowerShell"]
-  DetectPattern --> Formulate["Formulate new guardrail: 'When on Windows, convert backslashes to forward slashes for cross-shell command lines'"]
-  Formulate --> Write["Write bullet point to /memories/debugging.md"]
-  Write --> Done([Memory recorded: future sessions will automatically avoid Windows path errors])
+flowchart LR
+  Host[Host evidence and root cause] --> Classify{Reusable procedure?}
+  Classify -->|No| Rule[Persist a concise rule]
+  Classify -->|Yes| Draft[Load skill-creator and draft a skill]
+  Rule --> Gate[Deduplicate and quality-check]
+  Draft --> Gate
+  Gate -->|Pass| Record[Write the selected memory or manifest]
+  Gate -->|Fail| Stop[Leave state unchanged]
 ```
 
----
-
-## 4. Verification Check
+## Persistence outcomes
 
-To ensure that the `self-evolve` skill is operating in strict compliance with Harness OS design laws, verify the following:
+The decision is made from the lesson, not from transcript discovery. A long
+existing memory is split into a topic file and reached through a pointer.
 
-- [ ] **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.
+```mermaid
+flowchart TD
+  Lesson[Resolved lesson] --> Existing{Matching workspace memory?}
+  Existing -->|Short enough| Append[Append the defensive rule]
+  Existing -->|Too long| Split[Create topic memory and pointer]
+  Existing -->|No| Fallback[Choose the workspace fallback]
+  Fallback --> Append
+  Append --> Verify[Run the relevant gate]
+  Split --> Verify
+```

package/docs/workflows/skill-creator.md

@@ -1,75 +1,80 @@
-# 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.
-
----
-
-## 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]) --> 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 create-agent-launcher: 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>/, metadata.type=dynamic, status=draft"]
-  Register --> End([Skill live in the repo, single source of truth for its own description])
-  DynamicContract --> End
-```
-
----
-
-## 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["create-agent-launcher / SKILL.md"]
-  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
-  Evolve["self-evolve / SKILL.md §4"] -->|MUST load before packaging a session insight| Creator
-  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
-```
-
----
-
-## 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 create-agent-launcher 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"] --> Trigger2["self-evolve §3 Step 3: Dynamic Skill Generation"]
-  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, metadata.type=dynamic, status=draft"]
-  Write2 --> Done2([Dynamic skill available next session, lifecycle tracked separately from static skills])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-creator` 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.
+# 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.
+
+---
+
+## 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
+```
+
+---
+
+## 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
+```
+
+---
+
+## 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])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-creator` 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.

package/docs/workflows/skill-style.md

@@ -1,64 +1,64 @@
-# Workflow: Skill Style
-
-> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
-
----
-
-## 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])
-```
-
----
-
-## 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"]
-```
-
----
-
-## 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])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-style` 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.
+# Workflow: Skill Style
+
+> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
+
+---
+
+## 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])
+```
+
+---
+
+## 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"]
+```
+
+---
+
+## 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])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-style` 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.

package/docs/workflows/tdd.md

@@ -1,39 +1,78 @@
-# Workflow: Test-Driven Development (TDD)
-
-> Enforces the classic Red-Green-Refactor development cycle. Crucially, this is NOT a linear process. It is a loop driven by terminal exit codes.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes the script-gated reality of TDD. The AI cannot progress to the next phase until the terminal script explicitly confirms the state.
-
-```mermaid
-graph TD
-  Start([Identify Feature / Bug]) --> DesignInterface["Design interface & contract"]
-  DesignInterface --> WriteTest["Write unit/integration tests first"]
-  
-  WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
-  RunRed --> VerifyRed{Gate: Exit Code 1?}
-  VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
-  FixTest --> RunRed
-  
-  VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
-  
-  WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
-  RunGreen --> VerifyGreen{Gate: verify-gate.js}
-  
-  VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
-  DebugCode --> RunGreen
-  VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
-  CircuitBreaker --> DebugCode
-  
-  VerifyGreen -->|Exit 0: Green| Refactor["Refactor code for readability"]
-  
-  Refactor --> RunVerify["Try: Run tests again"]
-  RunVerify --> VerifyRefactor{Gate: verify-gate.js}
-  VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
-  Revert --> RunVerify
-  
-  VerifyRefactor -->|Exit 0| End([Feature verified & completed])
-```
+# Workflow: Test-Driven Development (TDD)
+
+> Enforces the classic Red-Green-Refactor development cycle. Crucially, this is NOT a linear process. It is a loop driven by terminal exit codes.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes the script-gated reality of TDD. The AI cannot progress to the next phase until the terminal script explicitly confirms the state.
+
+```mermaid
+graph TD
+  Start([Identify Feature / Bug]) --> DesignInterface["Design interface & contract"]
+  DesignInterface --> WriteTest["Write unit/integration tests first"]
+  
+  WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
+  RunRed --> AssertRed["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRed --> VerifyRed{Gate: Exit Code 1?}
+  VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
+  FixTest --> RunRed
+  
+  VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
+  
+  WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
+  RunGreen --> AssertGreen["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertGreen --> VerifyGreen{Gate: verify-gate.js}
+  
+  VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
+  DebugCode --> RunGreen
+  VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
+  CircuitBreaker --> DebugCode
+  
+  VerifyGreen -->|Exit 0: Green| Refactor["Refactor: Optimize & audit Code-Doc Alignment (Law 6)"]
+  
+  Refactor --> RunVerify["Try: Run tests again"]
+  RunVerify --> AssertRefactor["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRefactor --> VerifyRefactor{Gate: verify-gate.js}
+  VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
+  Revert --> RunVerify
+  
+  VerifyRefactor -->|Exit 0| End([Feature verified & completed])
+```
+
+## Profile boundary
+
+The profile describes the boundary crossed by the behavior under test. The
+RED/GREEN/REFACTOR loop remains the same; only the evidence and fixtures
+change.
+
+```mermaid
+flowchart TD
+  Behavior[Behavior under test] --> Boundary{External process or service boundary?}
+  Boundary -->|No| Unit[Unit profile]
+  Boundary -->|Yes| Integration[Integration profile]
+  Unit --> Loop[RED -> GREEN -> REFACTOR]
+  Integration --> Loop
+  Loop --> Evidence[Run tests and score evidence]
+  Evidence -->|Gate fails| Loop
+  Evidence -->|All gates pass| Done([Verified behavior])
+```
+
+## Recovery state
+
+The circuit breaker limits repeated edits. A third failed GREEN attempt moves
+the work into `zoom-out`, where the assumptions are rebuilt before retrying.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Red
+  Red --> GreenAttempt
+  GreenAttempt --> Green: tests pass
+  GreenAttempt --> Retry: tests fail
+  Retry --> GreenAttempt: attempts one or two
+  Retry --> ZoomOut: attempt three
+  ZoomOut --> Red: assumptions rebuilt
+  Green --> Refactor
+  Refactor --> [*]
+```