harness-everything 0.11.6 → 0.11.7

package/docs/workflows/environment-detection.md

@@ -1,63 +1,73 @@
 # Workflow: Environment Detection
 
-> Active shell, operating system, and toolset environment detection, providing safety guardrails and running preflight syntactic verification.
+> Detect OS, shell variant, and available dev tools at session start so commands use the right path, variable, and CLI syntax and avoid repeated execution errors.
 
----
+Source of truth: `environment-detection/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `environment-detection` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Session Start / Discover Phase]) --> CheckNode{Node.js Executable?}
-  CheckNode -->|Yes| RunPreflight["Run scripts/preflight.js"]
-  CheckNode -->|No / Fails| Heuristic["Inspect <environment_info> & Probe Shell via echo/env"]
-  
-  RunPreflight --> ParseOutput["Parse OS, Shell, Path Separators & CLI Runtimes"]
-  Heuristic --> ParseOutput
-  
-  ParseOutput --> SelfHeal["Run self-heal.js if Node available"]
-  SelfHeal --> AlignSyntax["Adopt Path Slash (/ vs \\) & Env Var Syntax ($VAR vs %VAR%)"]
-  AlignSyntax --> End([Environment Context Established])
+  SessionStart([Session start or complex terminal sequence]) --> Preflight[Run preflight.js from skill dir]
+  Preflight --> PreflightOk{Preflight succeeded?}
+  PreflightOk -->|yes| ParseOut[Parse OS shell PATH and CLIs]
+  PreflightOk -->|no| FallbackProbe[Inspect environment_info and probe shell]
+  FallbackProbe --> ParseOut
+  ParseOut --> SelfHealAudit[Audit harness touchpoints with self-heal.js]
+  SelfHealAudit --> AdoptSyntax[Adopt shell-specific syntax]
+  AdoptSyntax --> DoneCtx([Session context aligned])
 ```
 
----
+```mermaid
+graph TD
+  Adopted[Adopted syntax context] --> GitBash[Git Bash: forward slash and dollar-VAR with Unix cmds]
+  Adopted --> PowerShell[PowerShell: env-prefix vars with cmdlets]
+  Adopted --> CmdShell[CMD: backslash and percent-VAR with dir del copy]
+  GitBash --> GuardCwd[Stay inside process cwd]
+  PowerShell --> GuardCwd
+  CmdShell --> GuardCwd
+  GuardCwd --> FailCount{Same command failed 3 times?}
+  FailCount -->|yes| ZoomEsc[Trigger zoom-out]
+  FailCount -->|no| ContinueRun[Continue with aligned syntax]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `environment-detection` 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 command execution| Env["environment-detection / SKILL.md"]
-  Env -->|Guards runner execution commands in| TDD["tdd / SKILL.md"]
-  Env -->|Guards script installations in| InstallOS["install-cognitive-os / SKILL.md"]
-  Env -->|Guards PR quality checks in| VerLoop["verification-loop / SKILL.md"]
+  StartTrigger[Session start request] --> EnvDetect[environment-detection SKILL]
+  ComplexSeq[Complex terminal sequence] --> EnvDetect
+  EnvDetect --> AlignedRun[Aligned command execution]
+  AlignedRun --> RepeatedFail{Three failures on same command?}
+  RepeatedFail -->|yes| ZoomOut[zoom-out]
+  RepeatedFail -->|no| AlignedRun
 ```
 
----
+## 3. Real-World Use Case
 
-## 3. Real-World Use Case Flowchart
+A session starts on Windows with PowerShell as the active shell. The agent needs to list files and check Node availability before running tests.
 
-Here we model concrete real-world scenarios and use cases of the `environment-detection` skill, illustrating standard success paths, error handling, or recovery loops.
+1. Run `node "<skill-dir>/scripts/preflight.js"` to detect Windows + PowerShell + available CLIs.
+2. Adopt PowerShell syntax for paths and env vars instead of Git Bash assumptions.
+3. If `preflight.js` cannot run, inspect `<environment_info>` and probe with minimal echo/env commands, then adopt syntax.
+4. Stay inside `process.cwd()`; ignore other workspace, history, or temp paths shown by the IDE.
+5. If the same aligned command still fails three times, stop retrying the syntax and trigger `zoom-out`.
 
 ```mermaid
 graph TD
-  Start["Agent wants to run: 'rm -rf build && mkdir build' on Windows Powershell"] --> Trigger["Environment detection pre-flight check"]
-  Trigger --> Detect["Identifies OS: Windows, Shell: PowerShell"]
-  Detect --> AnalyzeSyntax["Identifies that 'rm -rf' will fail or behave unexpectedly in PowerShell"]
-  AnalyzeSyntax --> Rewrite["Rewrites command to PowerShell equivalent or executes using native node commands"]
-  Rewrite --> Run["Executes safely with exit code 0"]
-  Run --> Done([Syntax error and execution crash avoided])
+  AgentGoal[Need to list files and check Node on Windows] --> DetectEnv[Run session-start detection]
+  DetectEnv --> FoundShell[Detected PowerShell on Windows]
+  FoundShell --> UseCmd[Use PowerShell syntax for listing and env lookup]
+  UseCmd --> CmdResult{Command works?}
+  CmdResult -->|yes| ProceedTask[Proceed with task]
+  CmdResult -->|no after 3 tries| ZoomStep[Trigger zoom-out]
 ```
 
----
-
 ## 4. Verification Check
 
-To ensure that the `environment-detection` 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.
+- [ ] Detection ran at session start via `environment-detection/scripts/preflight.js`, with `<environment_info>` inspection and probing used only as fallback
+- [ ] Adopted syntax matches detected shell: Git Bash uses `/`, `$VAR`, Unix cmds without `dir`/`del`; PowerShell uses `$env:VAR` and cmdlets; CMD uses `\`, `%VAR%`, `dir`/`del`/`copy` without Unix cmds
+- [ ] All commands stayed inside `process.cwd()`; no commands ran outside the current project root
+- [ ] No toolchain installation was attempted; scope stayed to detection, alignment, and touchpoint repair
+- [ ] After three failures of the same command, execution stopped blind retry and triggered `zoom-out`
+- [ ] Shell detail followed `environment-detection/references/shell-syntax-rules.md` where needed

package/docs/workflows/eval-harness.md

@@ -1,64 +1,71 @@
 # Workflow: Eval Harness
 
-> Evaluates AI developer agent performance based on accuracy, resource efficiency, and anti-loop metrics.
+> Score an agent execution log or conversation history on correctness, token efficiency, anti-loop focus, and environment awareness, and save the result as a scorecard when a benchmark is requested.
 
----
+Source of truth: `eval-harness/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `eval-harness` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Trigger: Benchmark / Evaluate Log]) --> ParseLog["1. Parse Log: Actions, Error Loops, Token Indicator"]
-  ParseLog --> CalcRubric["2. Calculate Scores across 4 Dimensions (0-10)"]
-  CalcRubric --> CheckScript{3. Is evaluate.js Executable?}
-  
-  CheckScript -->|Yes| RunScript["Run node eval-harness/scripts/evaluate.js"]
-  CheckScript -->|No / Fails| FileFallback{"4. Markdown File Fallback"}
-  
-  FileFallback -->|evals/ Exists| WriteEvals["Save Scorecard to evals/scorecard.md"]
-  FileFallback -->|No evals/ Folder| WritePlatform["Save Scorecard to .github/harness-everything/evals/scorecard.md"]
-  
-  RunScript --> End([Evaluation Scorecard Logged])
-  WriteEvals --> End
-  WritePlatform --> End
+  BenchReq([Benchmark request with log or history]) --> ParseLog[Parse actions errors tokens timing]
+  ParseLog --> ScoreDims[Score four dimensions 0-10 via scoring-rubric]
+  ScoreDims --> RunEval[Run scripts evaluate.js with scores and insights]
+  RunEval --> EvalOk{Evaluate script succeeded?}
+  EvalOk -->|yes| SavedCard([Scorecard saved])
+  EvalOk -->|no or missing| MdFallback[Write evals scorecard.md fallback]
+  MdFallback --> SavedCard
 ```
 
----
+```mermaid
+graph TD
+  ScoreStart[Start scoring] --> Correctness[Score correctness 0-10]
+  ScoreStart --> Efficiency[Score efficiency 0-10]
+  ScoreStart --> AntiLoop[Score anti-loop focus 0-10]
+  ScoreStart --> EnvAware[Score environment awareness 0-10]
+  Correctness --> CombineScores[Combine into four-dimension card]
+  Efficiency --> CombineScores
+  AntiLoop --> CombineScores
+  EnvAware --> CombineScores
+  CombineScores --> EmitCard[Emit via script or markdown fallback]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `eval-harness` 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"] -->|Analyzes performance metrics| EH["eval-harness / SKILL.md"]
-  EH -->|Synthesizes lessons learned for| Evolve["self-evolve / SKILL.md"]
-  EH -->|Detects error loops triggering| ZoomOut["zoom-out / SKILL.md"]
+  UserBench[User asks to run benchmark] --> EvalSkill[eval-harness SKILL]
+  LogInput[Execution log or conversation history provided] --> EvalSkill
+  EvalSkill --> RubricStep[Apply references scoring-rubric.md]
+  RubricStep --> ScriptStep[Run scripts evaluate.js]
+  ScriptStep --> OutputLoc[Write to workspace evals or github fallback dir]
 ```
 
----
+## 3. Real-World Use Case
 
-## 3. Real-World Use Case Flowchart
+A reviewer wants to compare two runs of a file-migration task.
 
-Here we model concrete real-world scenarios and use cases of the `eval-harness` skill, illustrating standard success paths, error handling, or recovery loops.
+1. Collect the execution log with tool calls, errors, tokens, and timing.
+2. Score correctness, efficiency, anti-loop focus, and environment awareness 0–10 using `eval-harness/references/scoring-rubric.md`.
+3. Run `node <skill-dir>/scripts/evaluate.js <A> <B> <C> <D> "insights"`.
+4. On script failure or absence, write `<workspace>/evals/scorecard.md`, or `<workspace>/.github/harness-everything/evals/` if needed.
+5. Leave the evaluated code unchanged; output is only the scorecard and insights.
 
 ```mermaid
 graph TD
-  Start["Agent session finishes implementing a complete backend server"] --> Trigger["eval-harness skill executed"]
-  Trigger --> Gather["Collects: 15 minutes elapsed, 32 tool calls, 45,000 tokens consumed"]
-  Gather --> Score["Scores: Correctness 10/10, Resource Efficiency 9/10, Anti-loop 10/10"]
-  Score --> Output["Generates benchmark report summarizing optimal execution speed and zero looping errors"]
-  Output --> Done([Benchmark logged for project history])
+  ReviewAsk[Reviewer asks to score migration run] --> GatherLog[Gather execution log]
+  GatherLog --> ApplyRubric[Score four dimensions with rubric]
+  ApplyRubric --> TryScript[Try evaluate.js]
+  TryScript --> ScriptOk{Script ok?}
+  ScriptOk -->|yes| DoneScore([Scorecard emitted])
+  ScriptOk -->|no| WriteMd[Write scorecard.md fallback]
+  WriteMd --> DoneScore
 ```
 
----
-
 ## 4. Verification Check
 
-To ensure that the `eval-harness` 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.
+- [ ] Input included both a benchmark request and an execution log or conversation history; tasks without a log were declined
+- [ ] All four dimensions were scored 0–10 using `eval-harness/references/scoring-rubric.md`: correctness, efficiency, anti-loop focus, environment awareness
+- [ ] `eval-harness/scripts/evaluate.js` was run with four scores plus insights; markdown fallback was used only if the script failed or was missing
+- [ ] Scorecard was written under `<workspace>/evals/` or `<workspace>/.github/harness-everything/evals/`
+- [ ] No evaluated code was written or fixed, and no general review was substituted for dimension scoring

package/docs/workflows/fable-discipline.md

@@ -1,59 +1,71 @@
 # Workflow: Fable Discipline
 
-> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and preserving compact stage handoffs.
+> Act as a background guard while staged multi-agent work runs, keeping output compact, stage scope tight, handoffs explicit, and diverging builds halted.
 
----
+Source of truth: `fable-discipline/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `fable-discipline` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Fable Task Initiated]) --> AuditContext["Audit active context against the stage contract"]
-  AuditContext --> CheckTokenLimit{Context exceeds the active budget?}
-  CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
-  CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
-  TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
-  KeepState --> EnforceLimit
-  EnforceLimit --> RecordHandoff["Record a compact stage handoff"]
-  RecordHandoff --> End([Context maintained under safe, high-attention limits])
+  FableActive([fable-mode active with staged work]) --> CompactMilestone[Compact state after milestone]
+  CompactMilestone --> ScopeCheck[Enforce stage scope and output limits]
+  ScopeCheck --> HandoffStep[Require state manifest at handoff]
+  HandoffStep --> BuildHealth{Build errors diverging?}
+  BuildHealth -->|yes| HaltZoom[HALT and call zoom-out]
+  BuildHealth -->|no| KeepGuard[Continue background guard]
+  KeepGuard --> CompactMilestone
+  HaltZoom --> MapErrors[Map error dependency graph for human]
 ```
 
----
+```mermaid
+graph TD
+  IncomingAgent[Incoming stage agent] --> VerifyManifest[Verify outgoing state manifest first]
+  VerifyManifest --> ManifestOk{Manifest complete?}
+  ManifestOk -->|yes| DoStage[Run stage within allowed files]
+  ManifestOk -->|no| AskManifest[Require missing APIs and IO details]
+  AskManifest --> VerifyManifest
+  DoStage --> OneCommit[One commit per independent logic block]
+  OneCommit --> LeaveManifest[Leave manifest for next agent]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `fable-discipline` 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
-  Fable["fable-mode / SKILL.md"] -->|Monitors context on every turn| FD["fable-discipline / SKILL.md"]
-  FD -->|Trims and prunes files from| ActiveContext["Active AI Session Context"]
-  FD -->|Triggers high-level reflection when overloaded| ZoomOut["zoom-out / SKILL.md"]
+  FableMode[fable-mode active] --> FableDisc[fable-discipline shadow guard]
+  FableDisc --> WorkspaceGuard[Constrain multi-agent-workspace mutations]
+  WorkspaceGuard --> FableMode
+  FableDisc --> DivergedBuild{Diverging build errors?}
+  DivergedBuild -->|yes| ZoomOut[zoom-out]
+  DivergedBuild -->|no| FableMode
 ```
 
----
+## 3. Real-World Use Case
 
-## 3. Real-World Use Case Flowchart
+Long architectural migration runs under `fable-mode` with sub-agents handling separate stages.
 
-Here we model concrete real-world scenarios and use cases of the `fable-discipline` skill, illustrating standard success paths, error handling, or recovery loops.
+1. After each milestone, compact decisions and drop unneeded history; avoid broad regex and avoid reading irrelevant files over 1000 lines.
+2. Confirm working directory before touching core architecture; keep one commit per independent logic block.
+3. Outgoing agent leaves a manifest with completed APIs and expected inputs/outputs; incoming agent verifies it first.
+4. If fixes create more breakage, halt immediately, call `zoom-out`, and map the error dependency graph instead of continued patching.
 
 ```mermaid
 graph TD
-  Start["Fable-mode is editing a large monorepo with growing context"] --> Monitor["Fable-discipline analyzes active context"]
-  Monitor --> TriggerPruning["Identifies raw logs & completed sub-task details"]
-  TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
-  Clean --> Compress["Summarizes historical state into the stage handoff"]
-  Compress --> Done([Active context remains bounded while preserving required facts])
+  LongTask[Migration stage completes] --> CompactState[Compact milestone state]
+  CompactState --> CheckBloat[Check for bloat or oversized reads]
+  CheckBloat --> Handoff[Write and verify handoff manifest]
+  Handoff --> BuildCheck{Build diverging?}
+  BuildCheck -->|yes| HaltNow[HALT and zoom-out]
+  BuildCheck -->|no| NextStage[Start next stage guarded]
 ```
 
----
-
 ## 4. Verification Check
 
-To ensure that the `fable-discipline` 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.
+- [ ] Ran only as a background shadow for the whole `fable-mode` duration; not used standalone, not used for small tasks or routine single-file edits
+- [ ] After each milestone, state was compacted and unneeded history dropped; no broad regex without precise conditions and no irrelevant 1000+ line reads
+- [ ] Working directory was confirmed before core changes, with one commit per independent logic block
+- [ ] Every sub-agent handoff via `multi-agent-workspace` left a state manifest with completed APIs and expected inputs/outputs, verified by the incoming agent first
+- [ ] On diverging build errors, execution halted immediately and called `zoom-out` with an error dependency map instead of continued patching
+- [ ] Made no direct state mutations of its own; only constrained `fable-mode` and `multi-agent-workspace` mutations
+- [ ] Detail followed `fable-discipline/references/discipline-rules.md` where needed

package/docs/workflows/git-commit.md

@@ -1,71 +1,79 @@
 # Workflow: Git Commit
 
-> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
+> Create clean Angular-style commit messages for an explicit commit request or a finished task phase, after checking repo state, submodules, and staged changes.
 
----
+Source of truth: `git-commit/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Trigger Commit Request / Task Complete]) --> CheckGit{Is Git Repo Initialized?}
-  CheckGit -->|No| OfferInit["Prompt User: Run git init or Skip Commit"]
-  CheckGit -->|Yes| CheckSubmodules{Has Submodule Changes?}
-  
-  CheckSubmodules -->|Yes| CommitSubmodules["Commit Submodules First (Bottom-Up)"] --> CheckStatus
-  CheckSubmodules -->|No| CheckStatus["Run git status & git diff --cached"]
-  
-  CheckStatus --> StageCheck{Are Files Staged?}
-  StageCheck -->|No| AskStage["Prompt User / Stage Targeted Files"] --> FormatMessage
-  StageCheck -->|Yes| FormatMessage["Format Angular Commit Message"]
-  
-  FormatMessage --> CheckShell{Shell / Multiline Escaping Check?}
-  CheckShell -->|Simple Single Line| DirectCommit["Run git commit -m 'type(scope): subject'"]
-  CheckShell -->|Multiline / Windows| TempFileCommit["Write .git-commit-msg.txt -> Run git commit -F -> Cleanup"]
-  
-  DirectCommit --> VerifyCommit["Run git log -1 to Verify"]
-  TempFileCommit --> VerifyCommit
-  VerifyCommit --> End([Staging Clean and Committed])
+  CommitTrig([Commit requested or phase concluded]) --> StatusCheck[Run git status]
+  StatusCheck --> RepoOk{Git repo present?}
+  RepoOk -->|no| InitOffer[Offer git init or skip]
+  RepoOk -->|yes| SubCheck[Check submodule changes per SUBMODULES guide]
+  SubCheck --> SubDirty{Submodules changed?}
+  SubDirty -->|yes| SubFirst[Commit submodules first]
+  SubDirty -->|no| DiffCheck[Run git diff-cached]
+  SubFirst --> DiffCheck
+  DiffCheck --> StagedOk{Anything staged?}
+  StagedOk -->|no| PromptStage[Prompt user and stage targeted files]
+  StagedOk -->|yes| FormatMsg[Format type-scope-subject message]
+  PromptStage --> FormatMsg
+  FormatMsg --> VerifyLog[Commit then verify with git log -1]
+  VerifyLog --> DoneClean([Tree updated and clean])
 ```
 
----
+```mermaid
+graph TD
+  FormatSimple[Formatted Angular message] --> EscCheck{Simple single line?}
+  EscCheck -->|yes| DirectM[git commit -m]
+  EscCheck -->|no multiline or Windows| TempF[Write commit-msg file then git commit -F and cleanup]
+  DirectM --> LogOne[git log -1 verifies commit]
+  TempF --> LogOne
+  LogOne --> CleanTree([Working tree clean])
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `git-commit` 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 / git / save| GitCommit["git-commit / SKILL.md"]
-  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
-  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
-  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
+  UserReq[User requests commit] --> GitSkill[git-commit SKILL]
+  PhaseDone[Task phase concludes with staged diff] --> GitSkill
+  GitSkill --> StatusGate[git status gate]
+  StatusGate --> SubGuide[guides SUBMODULES.md if needed]
+  SubGuide --> StyleGuide[guides ANGULAR_STYLE.md formatting]
+  StyleGuide --> CommitVerify[Commit and git log -1 check]
 ```
 
----
+## 3. Real-World Use Case
 
-## 3. Real-World Use Case Flowchart
+Developer finishes an auth fix and asks for a commit.
 
-Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
+1. Run `git status`; if not a repo, offer `git init` or skip.
+2. If submodules changed, commit those first per `git-commit/guides/SUBMODULES.md`.
+3. Run `git diff --cached`; if nothing staged, prompt before staging targeted files.
+4. Format `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`.
+5. Use `git commit -m` for a simple line, or `.git-commit-msg.txt` + `git commit -F` with cleanup for multiline/Windows, then verify with `git log -1`.
 
 ```mermaid
 graph TD
-  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
-  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
-  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
-  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
-  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
-  Commit --> Done(["Repository index updated cleanly"])
+  DevDone[Auth fix finished and staged] --> CheckStatus[Run git status and cached diff]
+  CheckStatus --> FmtMsg[Format feat-auth style message]
+  FmtMsg --> PickMethod{Multiline or Windows?}
+  PickMethod -->|no| CommitM[git commit -m]
+  PickMethod -->|yes| CommitF[git commit -F with temp file]
+  CommitM --> VerifyOne[git log -1]
+  CommitF --> VerifyOne
+  VerifyOne --> CleanDone([Committed and verified])
 ```
 
----
-
 ## 4. Verification Check
 
-To ensure that the `git-commit` 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.
+- [ ] `git status` ran first; non-repo offered `git init` or skip, and empty staging prompted the user instead of committing nothing
+- [ ] Submodule changes were handled first per `git-commit/guides/SUBMODULES.md`
+- [ ] Staged diff was reviewed with `git diff --cached`, with targeted staging only after confirmation
+- [ ] Message followed `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`
+- [ ] Multiline/Windows path used `.git-commit-msg.txt` + `git commit -F` with cleanup; simple path used `git commit -m`; result verified with `git log -1`
+- [ ] No branch, rebase, merge, or push was performed, and no staging happened without confirmation
+- [ ] Detail followed `git-commit/references/commit-flow.md` where needed

package/docs/workflows/grill-me.md

@@ -1,62 +1,60 @@
 # Workflow: Grill Me
 
-> Relentless Challenger interview process that stress-tests architectural plans, highlights hidden assumptions, and demands explicit edge-case handling.
+> A demanding challenger that pressure-tests vague plans and architectures one question at a time, exposes loopholes and undefined boundaries, counters sycophantic agreement, keeps the CONTEXT.md glossary current, and passes settled decisions to to-spec for formal specs and ADRs.
 
----
+Source of truth: `grill-me/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `grill-me` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Developer Proposes Plan]) --> Discovery["Scan Related Code, CONTEXT.md & Existing ADRs"]
-  Discovery --> AskQuestion["Ask Exactly ONE Question at a Time (with AI Recommendation)"]
-  AskQuestion --> ReceiveAnswer["Receive Developer Answer & Resolve Branch"]
-  ReceiveAnswer --> UpdateGlossary["Update CONTEXT.md Glossary Inline"]
-  UpdateGlossary --> ValidateResilience{All Decision Tree Branches Resolved?}
-  ValidateResilience -->|No| AskQuestion
-  ValidateResilience -->|Yes| HandoffToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
-  HandoffToSpec --> End([Route to to-tickets / fable-mode / tdd])
+  Propose["Vague plan or architecture proposal received"] --> Discover["Scan plan code plus CONTEXT.md, README.md, docs/adr/"]
+  Discover --> DomainTerms["Grill using project domain model and terminology"]
+  DomainTerms --> AskOne["Ask exactly ONE question with attached insight"]
+  AskOne --> ResolveBranch["Resolve decision-tree branch before moving on"]
+  ResolveBranch --> UpdateGlossary["Update CONTEXT.md glossary inline"]
+  UpdateGlossary --> ConsensusCheck{"Consensus on all branches?"}
+  ConsensusCheck -->|No| AskOne
+  ConsensusCheck -->|Yes| HandoffSpec["Hand off to to-spec to preview outline and publish"]
+  HandoffSpec --> RouteExec["Route execution to to-tickets, fable-mode, or tdd"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `grill-me` 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: grill / debate / plan| GrillMe["grill-me / SKILL.md"]
-  GrillMe -->|Vague proposal or technical robustness needed| GrillMe
-  GrillMe -->|Needs glossary/ADR documentation alignment| GWD["grill-with-docs / SKILL.md"]
-  GWD -->|Directs macro execution strategies of| Fable["fable-mode / SKILL.md"]
+  VaguePlan["Input: vague plan proposal"] --> GrillMe["grill-me / SKILL.md"]
+  EvaluateArch["Input: evaluate architecture request"] --> GrillMe
+  ExplicitAsk["Input: explicit grill me request"] --> GrillMe
+  GrillMe --> ToSpec["to-spec: preview outline and publish PRD, CLI/API reference, Schema doc, or ADR"]
+  ToSpec --> ToTickets["to-tickets for execution"]
+  ToSpec --> FableMode["fable-mode for execution"]
+  ToSpec --> TDD["tdd for execution"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `grill-me` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Proposal: 'I will write a fast cron job to sync database tables directly'"] --> Trigger["grill-me skill activated"]
-  Trigger --> Challenger["Challenger SRE: 'What happens if the cron script fails mid-sync? Will there be database lock contention? How do we prevent partial/corrupt states?'"]
-  Challenger --> Answer1["Dev: 'I'll add database transaction wraps and skip locks'"]
-  Answer1 --> Challenger2["Challenger: 'How will we monitor and alert if locks are skipped repeatedly?'"]
-  Challenger2 --> Answer2["Dev: 'I'll add structured logging and trigger a standard Slack web-hook alerting'"]
-  Answer2 --> Approve["Challenger: 'Excellent. Let's record these lock-skip alerts as mandatory requirements.'"]
-  Approve --> Done([Plan hardened and logged])
+  CronProposal["Proposal: nightly cron syncs tables directly"] --> GrillStart["grill-me starts single-question loop"]
+  GrillStart --> Q1["Q1: What happens on mid-sync failure with locks held?"]
+  Q1 --> A1["Answer: wrap in transactions, define lock behavior"]
+  A1 --> Glossary1["Update CONTEXT.md glossary for sync and lock terms"]
+  Glossary1 --> Q2["Q2: What are boundary conditions for partial state?"]
+  Q2 --> Consensus["Consensus reached on failure and boundary handling"]
+  Consensus --> SpecHandoff["to-spec publishes ADR and spec"]
 ```
 
----
+Concrete example: a developer proposes a direct table-sync cron job. `grill-me` scans `CONTEXT.md` and related code, asks one question about mid-sync failure, resolves it, updates the glossary, asks the next question about monitoring and boundary conditions, then hands the hardened decisions to `to-spec` for a PRD or ADR. Execution follows via `to-tickets`, `fable-mode`, or `tdd`.
 
-## 4. Verification Check
+Deep detail: `grill-me/references/grilling-playbook.md`.
 
-To ensure that the `grill-me` 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.
+- [ ] Exactly ONE question asked at a time; questionnaires prohibited
+- [ ] Each question carries the agent's insight and its branch is resolved before advancing
+- [ ] Questions use the project's domain model and terminology from `CONTEXT.md`, `README.md`, and `docs/adr/`
+- [ ] `CONTEXT.md` glossary updated inline as terms resolve; document creation left to `to-spec`
+- [ ] On consensus, `to-spec` invoked to preview outline and publish PRD, CLI/API reference, Schema doc, or ADR
+- [ ] No code implementation or ticket breakdown inside this skill; execution routed to `to-tickets`, `fable-mode`, or `tdd`
+- [ ] Not used for casual Q and A, direct spec writing, or ticket breakdown of an approved spec