harness-everything 0.11.6 → 0.12.0

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

package/docs/workflows/grill-with-docs.md

@@ -1,69 +1,59 @@
-# Workflow: Grill with Docs
+# Workflow: Grill With Docs
 
-> Decision tracking, Glossary alignment, and ADR-driven (Architecture Decision Record) grilling to eliminate technical drift between code and documentation.
+> Tests a plan against the recorded domain language and past decisions, tightens fuzzy terminology into canonical terms, and writes CONTEXT.md and ADR updates inline as choices settle.
 
----
+Source of truth: `grill-with-docs/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `grill-with-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Plan Proposed against Domain]) --> CheckCoreValidity{Plan vague or unverified?}
-  CheckCoreValidity -->|Yes| RecommendGrillMe["Recommend running grill-me first"]
-  CheckCoreValidity -->|No| ReadDomainModel["Read CONTEXT.md and existing ADRs"]
-  RecommendGrillMe --> EndVague([Postponed until plan is hardened])
-  ReadDomainModel --> ChallengeDrift["Examine plan for term drift or architectural violations"]
-  ChallengeDrift --> UpdateGlossary["Refine and match terminology with current Glossary"]
-  UpdateGlossary --> ResolveADRPath{Resolve ADR Storage Path}
-  
-  ResolveADRPath -->|docs/adr/ or CONTEXT-MAP.md Exists| WriteDocs["Write ADR to docs/adr/ or CONTEXT-MAP.md Location"]
-  ResolveADRPath -->|No Folder Found| WriteFallback["Write to committable docs/adr"]
-  
-  WriteDocs --> ToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
-  WriteFallback --> ToSpec
-  ToSpec --> End([Route to to-tickets / fable-mode / tdd])
+  PlanInput["Plan needing domain alignment"] --> ResolveStorage["Resolve storage with project-docs-resolver.js; CONTEXT-MAP.md root wins"]
+  ResolveStorage --> ChallengeTerms["Challenge glossary conflicts; sharpen fuzzy terms to canonical ones"]
+  ChallengeTerms --> ScenarioTest["Stress-test relationships with concrete scenarios; cross-check claims against code"]
+  ScenarioTest --> InlineUpdate["Update context glossary inline, never batched; zero implementation details"]
+  InlineUpdate --> ADRGate{"ADR warranted: hard to reverse plus surprising without context plus real trade-off?"}
+  ADRGate -->|Yes| WriteADR["Offer and write ADR at resolved location"]
+  ADRGate -->|No| SkipADR["Skip ADR; keep pure glossary"]
+  WriteADR --> Handoff["Hand off aligned design to to-spec"]
+  SkipADR --> Handoff
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `grill-with-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: adr / decision / glossary| GWD["grill-with-docs / SKILL.md"]
-  GrillMe["grill-me / SKILL.md"] -->|Hardened plan ready for formalization| GWD
-  GWD -->|Aligns documentation during macro work in| Fable["fable-mode / SKILL.md"]
-  GWD -->|Triggers todo tasks tracked by| Todo["todo-driven-workflow / SKILL.md"]
-  GWD -->|Hands off to generate specifications| ToSpec["to-spec / SKILL.md"]
+  DomainStress["Input: stress-testing a plan against domain language and documented decisions"] --> GWD["grill-with-docs / SKILL.md"]
+  GWD --> GrillMe["grill-me for unverified design"]
+  GWD --> ToSpec["to-spec for aligned design"]
+  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-with-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Requirement: Change notification retry rate limits"] --> Trigger["grill-with-docs skill invoked"]
-  Trigger --> ReadDocs["Analyzes docs/adr/003-rate-limiting.md"]
-  ReadDocs --> CheckDrift["Finds that proposed change violates the maximum overload protection limit"]
-  CheckDrift --> RefinePlan["Plan updated to stay within the 003-rate-limiting contract"]
-  RefinePlan --> CreateADR["Create docs/adr/008-notification-retries.md"]
-  CreateADR --> SyncCode["Modify code and inject aligned TODO tags directly in code to maintain truth"]
-  SyncCode --> Done([Zero architectural drift achieved])
+  RetryProposal["Proposal: change notification retry limits"] --> ResolveDocs["Resolve docs location; read CONTEXT.md and rate-limit ADR"]
+  ResolveDocs --> Conflict["Find glossary conflict: retry versus backoff"]
+  Conflict --> Scenario["Scenario test: burst retry against overload protection limit"]
+  Scenario --> GlossaryFix["Inline glossary fix to canonical terms"]
+  GlossaryFix --> ADRDecision["ADR offered because limit change is hard to reverse and involves trade-off"]
+  ADRDecision --> AlignedHandoff["Aligned design to to-spec; execution to to-tickets, fable-mode, or tdd"]
 ```
 
----
+Concrete example: a retry-limit change is checked against the existing rate-limiting ADR and code. Fuzzy retry language is sharpened, the glossary is fixed inline, and only because the decision is hard to reverse and surprising without context is an ADR written. An unverified design would go to `grill-me` first instead.
 
-## 4. Verification Check
+Deep detail: `grill-with-docs/references/session-playbook.md`. Formats: `grill-with-docs/ADR-FORMAT.md`, `grill-with-docs/CONTEXT-FORMAT.md`.
 
-To ensure that the `grill-with-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.
+- [ ] Storage resolved with `multi-agent-workspace/scripts/project-docs-resolver.js`; `<workspace>/CONTEXT-MAP.md` root wins
+- [ ] Fuzzy terms sharpened to canonical ones; glossary stays pure with zero implementation details
+- [ ] Relationships tested with concrete scenarios and claims cross-checked against code
+- [ ] Context glossary updated inline, never batched
+- [ ] ADR offered only when hard to reverse plus surprising without context plus a real trade-off
+- [ ] ADRs meet the 3-part bar; handoff to `to-spec` after alignment
+- [ ] Routing respected: unverified design to `grill-me`; aligned design to `to-spec`; execution to `to-tickets`, `fable-mode`, or `tdd`
+- [ ] Not used for verifying unstable designs without a grilling pass, and not used for spec publishing without grilling