harness-everything 0.11.5 → 0.11.7

package/docs/workflows/improve-codebase-architecture.md

@@ -1,68 +1,60 @@
 # Workflow: Improve Codebase Architecture
 
-> Finds deepening opportunities in the codebase, consolidating tightly-coupled modules and mapping dependencies visually using Mermaid diagram reports.
+> Finds thin or overweight modules and reshapes them into focused, single-responsibility units by dividing large objects and functions, isolating seams, and separating interfaces.
 
----
+Source of truth: `improve-codebase-architecture/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `improve-codebase-architecture` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Audit Request / Refactoring / SRP Object Splitting]) --> ScanDirectories["Scan code directories, CONTEXT.md & ADRs"]
-  ScanDirectories --> IdentifyTarget["Identify Monolithic Objects (>300 lines) or Shallow Modules"]
-  IdentifyTarget --> FormulatePlan["Formulate Deepening & SRP Object Extraction Plan"]
-  FormulatePlan --> Propose["Present Deepening & SRP Proposal to User"]
-  Propose --> UserApproved{"User Approves Proposal?"}
-  
-  UserApproved -->|Yes| CheckTests{"Existing Test Safety Net Present?"}
-  UserApproved -->|No| AdjustPlan["Adjust Proposal Scope"] --> Propose
-  
-  CheckTests -->|No Tests| WriteCharTests["Write Characterization Tests First"] --> ExecuteTDD
-  CheckTests -->|Tests Present| ExecuteTDD["Execute Object Extraction via TDD"]
-  
-  ExecuteTDD --> CheckErrors{"Cascading Errors > 3?"}
-  CheckErrors -->|Yes| Rollback["Rollback Changes & Trigger zoom-out"]
-  CheckErrors -->|No| Complete["Refactoring Complete & Record Lessons in self-evolve"]
+  RefactorAsk["Input: refactor architecture, split object, apply SRP, tech debt"] --> DiscoverScan["Scan CONTEXT.md, docs/adr/, and core interfaces first; no blind refactoring"]
+  DiscoverScan --> FindTargets["Target SRP violations over 300 lines or over 10 complexity, shallow modules, coupled seams"]
+  FindTargets --> Proposal["Present Deepening and SRP proposal: object splitting plus seam abstraction"]
+  Proposal --> Approved{"Proposal approved?"}
+  Approved -->|No| Proposal
+  Approved -->|Yes| SafetyNet{"Legacy code has tests?"}
+  SafetyNet -->|No| CharTests["Write Characterization Tests first via tdd"]
+  SafetyNet -->|Yes| Extract["Extract incrementally via tdd; verify tests after each change"]
+  CharTests --> Extract
+  Extract --> ErrorCheck{"More than 3 cascading errors?"}
+  ErrorCheck -->|Yes| Rollback["Rollback plus zoom-out; record traps in self-evolve"]
+  ErrorCheck -->|No| DoneState["Refactoring complete"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `improve-codebase-architecture` 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: refactor / architecture / couple| ICA["improve-codebase-architecture / SKILL.md"]
-  ICA -->|Deductions challenged by SRE via| GrillMe["grill-me / SKILL.md"]
-  ICA -->|Guides large-scale structural rewrites in| Fable["fable-mode / SKILL.md"]
-  ICA -->|Extracts interfaces to simplify unit tests in| TDD["tdd / SKILL.md"]
+  TechDebt["Trigger: refactor architecture or split object or apply SRP or tech debt"] --> ICA["improve-codebase-architecture / SKILL.md"]
+  ICA --> TDD["tdd: Characterization Tests first, then incremental extraction"]
+  ICA --> ZoomOut["zoom-out: invoked with rollback after more than 3 cascading errors"]
+  ICA --> SelfEvolve["self-evolve: record traps"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `improve-codebase-architecture` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Monolithic file 'utils.js' handles email, token creation, DB pooling, and logging"] --> Trigger["improve-codebase-architecture skill analyzed"]
-  Trigger --> Audit["Analyzes dependency graphs and calculates coupling scores"]
-  Audit --> FindSeams["Identifies three distinct interfaces: IEmailService, ITokener, IDbPool"]
-  FindSeams --> GenMermaid["Output detailed Mermaid diagram visualizing the proposed separated structure"]
-  GenMermaid --> RefactorPlan["Drafts multi-stage module extraction plan"]
-  RefactorPlan --> Done([Clear, modular architectural blueprint established])
+  BloatedUtil["utils.js handles email, tokens, DB pooling, logging"] --> ScanInterfaces["Scan CONTEXT.md, ADRs, core interfaces"]
+  ScanInterfaces --> SRPProposal["Propose split into focused units plus seam abstractions"]
+  SRPProposal --> CharNet["Add Characterization Tests for untested legacy paths"]
+  CharNet --> Incremental["Incremental extraction with test check after each step"]
+  Incremental --> RollbackGate{"More than 3 cascading errors?"}
+  RollbackGate -->|Yes| RollbackZoom["Rollback and zoom-out"]
+  RollbackGate -->|No| ModularDone["SRP-compliant modules with safety net"]
 ```
 
----
+Concrete example: a 600-line utility module is scanned for interfaces and ADR constraints, proposed for splitting into single-purpose units, guarded by Characterization Tests, then extracted step by step with verification after each change.
 
-## 4. Verification Check
+Deep detail: `improve-codebase-architecture/references/README.md`.
 
-To ensure that the `improve-codebase-architecture` 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.
+- [ ] `CONTEXT.md`, `docs/adr/`, and core interfaces scanned first; no blind refactoring
+- [ ] Targets match the skill bar: SRP violations over 300 lines or over 10 complexity, shallow modules, coupled seams
+- [ ] Deepening and SRP proposal with object splitting and seam abstraction presented and approved before code changes
+- [ ] `tdd` launched; Characterization Tests added first when legacy code lacks tests
+- [ ] Extraction done incrementally with tests verified after each change
+- [ ] On more than 3 cascading errors, changes rolled back with `zoom-out` and traps recorded in `self-evolve`
+- [ ] Not used for features, bugfixes, or style-only cleanups with no structure change

package/docs/workflows/install-cognitive-os.md

@@ -1,60 +1,67 @@
 # Workflow: Install Cognitive OS
 
-> Automates the installation of the Agent Cognitive Loop (Think > Try > Summarize > Record) into the user's active workspace and environment configs.
+> Explain or explicitly apply the Harness cognitive policy: Discover, Think, Try, Summarize, Record. This skill is a human-readable/manual entry point, not an installer and not a required peer-skill selection.
+
+Source of truth: `install-cognitive-os/SKILL.md`. Deep dive: `install-cognitive-os/references/cognitive-loop.md`.
+
+The runtime invariant contract is established by supported host integrations independently of this skill. Domain skills never need to invoke this skill first as long as Harness invariants remain satisfied.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `install-cognitive-os` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Bootstrap Hook Triggered]) --> DetectTargetEnv["Scan for active IDE / Client config paths"]
-  DetectTargetEnv --> InjectAdvisoryRules["Append advisory rules to .cursorrules, .github/copilot-instructions.md, or AGENTS.md"]
-  InjectAdvisoryRules --> InstallHooks["Configure Claude Code settings.json hook pre-flights"]
-  InstallHooks --> DeployScripts["Deploy core bootstrap.js, self-heal.js, and tier-router.js scripts"]
-  DeployScripts --> RunVerification["Execute self-heal audit test to confirm platform integrations"]
-  RunVerification --> End([Harness cognitive guardrails fully established])
+  Start([Explicit request OR host without kernel context]) --> Discover["Discover: verify relevant workspace state with read-only tools"]
+  Discover --> Think["Think: establish intent, scope, and failure modes"]
+  Think --> Try["Try: make the smallest useful change and gather evidence"]
+  Try --> Summarize["Summarize: ground conclusions in tool output"]
+  Summarize --> FailCheck{Same-signature failure x3?}
+  FailCheck -->|Yes| ZoomOut["zoom-out: stop edits, rebuild facts, report RESUME or ESCALATE"]
+  FailCheck -->|No| Record["Record: persist milestones only when evidence supports them"]
+  ZoomOut --> Think
+  Record --> End([Evidence-grounded work, no fixed domain sequence])
 ```
 
+This skill writes no installer state, deploys no hooks, and copies no skill directories. Workspace installation is owned by the general installer (`node scripts/installer.js`), not by this skill.
+
 ---
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `install-cognitive-os` 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
-  BootstrapCmd["Bootstrap CLI Command / npm install"] --> InstallSkill["install-cognitive-os / SKILL.md"]
-  InstallSkill -->|Deploys core router script| Router["harness-everything / scripts / tier-router.js"]
-  InstallSkill -->|Establishes memory loop configs for| Evolve["self-evolve / SKILL.md"]
-  InstallSkill -->|Guards all file edits using| Todo["todo-driven-workflow / SKILL.md"]
-  InstallSkill -->|Enforces Always-On Normalization for all responses| ADHD["Always-On ADHD-Friendly Output Shaping"]
+  Trigger["Explain policy / Apply loop manually / Debug cognitive behavior"] --> Skill["install-cognitive-os / SKILL.md"]
+  Skill -->|No kernel context| Manual["Run Discover → Think → Try → Summarize → Record explicitly"]
+  Skill -->|Kernel present| Policy["Treat as policy reference; domain skill proceeds directly"]
+  Manual --> Gates["Gates: evidence before claims; re-plan after x3 same-signature failures"]
+  Policy --> Gates
+
+  style Skill fill:#d35400,stroke:#e67e22,stroke-width:2px,color:#ffffff
+  style Gates fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ffffff
 ```
 
 ---
 
 ## 3. Real-World Use Case Flowchart
 
-Here we model concrete real-world scenarios and use cases of the `install-cognitive-os` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
 graph TD
-  Start["Fresh repository checkout"] --> Trigger["Run 'node scripts/installer.js install --all --yes'"]
-  Trigger --> Scan["Detects Cursor editor rules and GitHub action configurations"]
-  Scan --> BuildAdvisory["Appends mandatory routing checkpoint and cognitive compliance blocks to .cursorrules"]
-  BuildAdvisory --> CopySkills["Copies all current skills into .cursor/skills/ and .github/skills/"]
-  CopySkills --> CheckHeal["Runs preflight audit to confirm 100% path coverage"]
-  CheckHeal --> Done([Harness OS environment setup is complete and active])
-```
+  Case1["User on advisory-only host: 'walk me through the loop'"] --> Explain["Explain Discover → Think → Try → Summarize → Record with a small example"]
+  Explain --> Done1([User can apply the loop manually])
 
----
+  Case2["Host without automatic kernel context"] --> Apply["Apply the five steps explicitly to the task at hand"]
+  Apply --> Done2([Work proceeds with evidence gates, no hook installation claimed])
+
+  Case3["User asks for domain work: 'implement feature X test-first'"] --> Direct["Proceed directly with tdd; this skill is NOT a prerequisite"]
+  Direct --> Done3([Domain skill executes under Harness invariants])
+```
 
 ## 4. Verification Check
 
 To ensure that the `install-cognitive-os` 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.
+- [ ] **Policy, not installation**: no hook deployment, file copying, or config mutation claimed as this skill's effect.
+- [ ] **Full five-step loop**: Discover → Think → Try → Summarize → Record applied in order, not the truncated four-step variant.
+- [ ] **Evidence gates honored**: completion claims need evidence; repeated same-signature failures require re-planning via `zoom-out`.
+- [ ] **No prerequisite fabrication**: domain skills (`tdd`, `security-review`, `repo-docs`) proceed without selecting this skill first.

package/docs/workflows/repo-docs.md

@@ -1,64 +1,53 @@
 # Workflow: Repo Docs
 
-> Generates high-quality, professional README.md and AGENTS.md files based on actual workspace structures and product-archetype templates.
+> Creates or refreshes reader-focused README.md and AGENTS.md from real repository scans, carefully blending discovered facts with existing custom notes for projects missing docs or needing better agent onboarding.
 
----
+Source of truth: `repo-docs/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `repo-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Generate / Update Repository Docs]) --> AuditProjectStructure["Audit workspace directory tree & build configs"]
-  AuditProjectStructure --> CheckExisting{Existing README / AGENTS File Found?}
-  
-  CheckExisting -->|Yes| ReadOld["Read Existing File & Extract Bespoke Notes (env vars, URLs, gotchas)"]
-  CheckExisting -->|No| ClassifyProductArchetype["Classify repository archetype"]
-  
-  ReadOld --> ClassifyProductArchetype
-  ClassifyProductArchetype --> LoadTemplates["Load standard README and AGENTS templates"]
-  LoadTemplates --> SmartMerge["Smartly Merge Codebase Facts + Bespoke Notes + Template Structure"]
-  SmartMerge --> FormatMarkdown["Format documents following clean layout rules"]
-  FormatMarkdown --> WriteFiles["Save / Merge README.md and AGENTS.md at Root or .github/"]
-  WriteFiles --> End([Professional onboarding documentation created without losing history])
+  MissingDocs["Input: missing docs or request to update README.md and AGENTS.md"] --> ScanConfigs["Scan configs such as package.json and Cargo.toml as Source of Truth; never fabricate"]
+  ScanConfigs --> ReadExisting["Read existing docs fully first; extract bespoke notes: env vars, URLs, gotchas"]
+  ReadExisting --> PickTemplate["Pick template from repo-docs/templates/ else built-in structure"]
+  PickTemplate --> DraftDocs["Draft README as user journey; AGENTS.md as conventions and build/test commands"]
+  DraftDocs --> VerifyCmds["Verify commands run; mark doubts with TODO Pending confirmation; ask via grill-me"]
+  VerifyCmds --> WriteRoot["Write to root; if protected use .github/AGENTS.md or docs/README.md"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `repo-docs` 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: doc / readme / agents-template| RepoDocs["repo-docs / SKILL.md"]
-  RepoDocs -->|Integrates frontmatter constraints into| BMAS["multi-agent-workspace / SKILL.md"]
-  RepoDocs -->|Leverages ADR details generated in| GWD["grill-with-docs / SKILL.md"]
+  UndocProject["Trigger: undocumented project needs README"] --> RepoDocs["repo-docs / SKILL.md"]
+  StructuralChange["Trigger: structural change needs AGENTS.md refresh"] --> RepoDocs
+  RepoDocs --> GrillMe["grill-me: clarify doubts marked TODO Pending confirmation"]
+  RepoDocs --> WriteOut["Write README.md and AGENTS.md to root or fallback locations"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `repo-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["New library lacks onboarding docs and setup details"] --> Trigger["repo-docs skill invoked"]
-  Trigger --> Scan["Scans folders: discovers it's a TypeScript utility package"]
-  Scan --> MatchTemplate["Loads library archetype README template"]
-  MatchTemplate --> GenDocs["Outputs README.md with TypeScript usage examples, badges, and structure"]
-  GenDocs --> GenOnboarding["Outputs AGENTS.md defining the developer agent rules for the repo"]
-  GenOnboarding --> Done([Clean, standardized documentation committed])
+  BareRepo["New TypeScript utility package with no onboarding docs"] --> ScanProj["Scan package.json and directory tree"]
+  ScanProj --> PreserveNotes["Read existing stub docs; preserve custom env vars and gotchas"]
+  PreserveNotes --> SelectTemplate["Select library README template from repo-docs/templates/"]
+  SelectTemplate --> MergeDraft["Merge scan facts plus bespoke notes into README journey and AGENTS conventions"]
+  MergeDraft --> VerifyStep["Verify build and test commands; mark unconfirmed items TODO Pending confirmation"]
+  VerifyStep --> PublishDocs["Write README.md and AGENTS.md to root or fallback"]
 ```
 
----
+Concrete example: an undocumented utility repo is scanned for its real entry points and scripts, its bespoke environment notes are preserved, a template from `repo-docs/templates/` shapes the draft, commands are verified, and the merged README and AGENTS files are written without blind overwrites.
 
-## 4. Verification Check
+Deep detail: `repo-docs/references/process-guide.md`.
 
-To ensure that the `repo-docs` 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.
+- [ ] Configs scanned as Source of Truth; no facts fabricated without repo evidence
+- [ ] Existing docs read fully first; bespoke notes preserved and never overwritten blindly
+- [ ] Template picked from `repo-docs/templates/` or built-in structure applied
+- [ ] `README.md` covers the user journey; `AGENTS.md` covers conventions and build/test commands
+- [ ] Commands verified to run; unresolved doubts marked `// TODO: Pending confirmation` and clarified with `grill-me`
+- [ ] Written to root, or to `<workspace>/.github/AGENTS.md` and `<workspace>/docs/README.md` when root is protected
+- [ ] Not used for marketing copy, fabrication without scanning, or non-repository wikis

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