@mrciphersmith/keryx 0.2.97 → 0.2.99

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: feature-dev
-description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow."
+description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow. NOT for: splitting an issue into tasks run by parallel sub-agents (use job-orchestrator)."
 triggers:
-  - "/feature-dev"
-  - "Develop feature"
+  - "feature dev"
+  - "develop feature"
+  - "guided feature workflow"
   - "Build feature"
   - "Implement feature"
   - "Feature from scratch"
 metadata:
   author: "MrCipherSmith"
   version: "2.0.0"
-  category: "workflow"
+  category: "orchestration"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -89,7 +90,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 1. Implement changes file by file, following the plan from Phase 2
 2. Goal: make the failing tests from Phase 4 GREEN
 3. Follow existing code patterns and loaded rules
-4. After each file group, run quick inline check: `npx tsc --noEmit` (type errors only)
+4. After each file group, run a quick inline check: `keryx health run --changed --source typescript` (type errors only, over the changed files — `src/health/sources/typescript.ts` resolves the real invocation, so this is never a hardcoded `npx tsc`; on a project with no keryx health config, fall back to its own configured type-check command)
 5. Commit with conventional message after each logical chunk
 
 ### Phase 6: VERIFY (code-verifier gate)
@@ -97,7 +98,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 Run `code-verifier` on the full diff:
 
 ```
-Invoke: skills/orchestration/code-verifier/SKILL.md
+Invoke: .metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md
 Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
 ```
 
@@ -161,3 +162,16 @@ At each phase transition, report progress:
 | "I understand the requirements, confirmation is just a formality" | The confirmation step exists to catch the gap between what you understood and what was meant |
 
 **The three constraints that hold the pipeline together:** no implementation before the spec is written and confirmed; no implementation code before tests-creator has generated failing stubs; no delivery without a passing code-verifier gate and a Change Report.
+
+## Verification
+
+Do not report the feature as delivered until all of these hold:
+
+- The user explicitly confirmed the Phase 1 spec and the Phase 2 design — a confirmation you can quote, not one you inferred from silence.
+- Phase 4's test stubs were observed FAILING before any implementation code was written, and the same tests pass now. Tests that were green the moment they were written tested nothing.
+- Every acceptance criterion in the Phase 1 spec maps to at least one test, and each is checked off in the Change Report.
+- `code-verifier` was re-run after the last fix and its final result is `gate: PASS` (or `PASS_WITH_WARNINGS` with the warnings named in the Change Report). A gate result from before the last edit does not count.
+- `git diff <base>...HEAD` shows no TODOs, debug logging, or hardcoded values introduced by this work.
+- Commits are atomic — one logical chunk each — and the branch is pushed.
+- The PR exists with the issue link, acceptance-criteria checklist, test plan and gate result; if no PR was created, the Change Report says why.
+- The Change Report was printed to the user and names files changed, test count and result, gate result, checked-off criteria, and the commit list.

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: flow-orchestrator
-description: "Use when Task Manager is enabled and a non-trivial feature, issue, or story should be driven through keryx flow from initialization to a user-selected completion, verified handoff, or open state."
+description: "Use when Task Manager is enabled and a non-trivial feature, issue, or story should be driven through keryx flow from initialization to a user-selected completion, verified handoff, or open state. NOT for: the same pipeline without Task Manager state (use job-orchestrator)."
 triggers:
-  - "создай flow"
   - "создай фло"
-  - "заведи стори"
-  - "implement with flow"
+  - "create flow"
   - "issue to flow"
+  - "managed implementation"
   - "task manager orchestration"
+  - "создай flow"
+  - "заведи стори"
+  - "implement with flow"
   - "flow orchestration"
-  - "managed implementation"
 metadata:
   author: "MrCipherSmith"
   version: "1.4.0"
@@ -231,6 +232,7 @@ Required rules:
 - `.metaproject/rules/core/error-handling.mdc`
 - `.metaproject/rules/core/implementation-doc-mandate.mdc`
 - `.metaproject/rules/core/execution-metrics.md`
+- `.metaproject/rules/core/git-concurrency.mdc` — no `git stash`, no unscoped `git add`, pin every dispatch to its worktree
 
 Execution metrics (opt-in): when a USER runs this orchestrator directly, at the
 start ask "Collect execution statistics for this run? (yes/no)" per
@@ -320,6 +322,19 @@ worker reply is a `subagent-result` object
 line is `STATUS: <status>`
 (`.metaproject/rules/core/subagent-status-protocol.md`).
 
+`<worktree_path>` below is the absolute root of the checkout this flow's work
+happens in: the git worktree the flow runs in, or the project root when it runs
+in the main checkout. Resolve it once, before the first dispatch
+(`git rev-parse --show-toplevel` from that checkout), check
+`git -C <worktree_path> branch --show-current` is the branch the work belongs
+on, and pin every dispatch to it (`rules/core/git-concurrency.mdc`, "Pinning A
+Dispatch To Its Worktree").
+
+Workers do not commit: flow-orchestrator owns every commit and dispatches with
+auto-commit off (task-implementer's `automation.auto_commit: false`). A
+`subagent-dispatch` has no `automation` field, so the setting travels as the
+explicit constraint below — never as the worker's default, which is `true`.
+
 Dispatch payload, bound to the flow (map `target_skill` from the routing table):
 
 ```json
@@ -340,7 +355,10 @@ Dispatch payload, bound to the flow (map `target_skill` from the routing table):
   "constraints": [
     "Never edit flow.json.",
     "Never edit frozen acceptance criteria.",
-    "Return a subagent-result; first line must be STATUS:."
+    "Return a subagent-result; first line must be STATUS:.",
+    "Follow rules/core/git-concurrency.mdc: never git stash; never git add -A.",
+    "Root: <worktree_path>. Before the first write run `cd <worktree_path> && pwd && git branch --show-current`; run every git command as `git -C <worktree_path>`.",
+    "Auto-commit is off (automation.auto_commit: false): do not commit; list every path you changed in changed_files. flow-orchestrator commits them at the task boundary."
   ],
   "allowed_actions": ["read", "write", "run-command", "git"],
   "output_contract": { "schema": "subagent-result", "artifact_path": ".metaproject/flows/<dir>/journal.md" },
@@ -349,12 +367,37 @@ Dispatch payload, bound to the flow (map `target_skill` from the routing table):
 }
 ```
 
-After a worker succeeds, the flow-orchestrator marks task progress:
+**Task boundary commit, after every accepted worker result** (`DONE` or
+`DONE_WITH_CONCERNS`), then mark task progress. It commits exactly those
+`changed_files` from the worker's `subagent-result` that git still shows as
+changed, never `-A`/`--all`/`.` (`rules/core/git-concurrency.mdc` rule 4 and
+"Reporting Back"). It skips cleanly when none remain. That is expected, not an
+error, for a worker that reported no files (review, context, docs) or that
+committed on its own (tests-creator's stubs):
 
 ```bash
+set -- <each changed_files path, single-quoted: 'src/a.ts' 'docs/b c.md'>   # may be none; an unquoted path with a space splits and is skipped
+PENDING=()
+for p in "$@"; do
+  [ -n "$(git -C <worktree_path> status --porcelain -- "$p")" ] && PENDING+=("$p")
+done
+if [ ${#PENDING[@]} -eq 0 ]; then
+  echo "boundary commit: nothing left to commit, skipped"
+else
+  git -C <worktree_path> add -- "${PENDING[@]}"
+  git -C <worktree_path> commit -m "<type>(<scope>): <Tn title>
+
+task: <Tn>" -- "${PENDING[@]}"
+fi
 keryx flow task done <id> <Tn>
 ```
 
+Why each path is checked on its own: `git status --porcelain --` with no path
+lists the whole tree, `git add` fails on a path that is neither on disk nor
+tracked, and `git commit` with nothing staged exits 1. The trailing
+`-- "${PENDING[@]}"` commits only these paths, so a file another lane staged is
+not swept into this commit.
+
 If new work is discovered:
 
 ```bash
@@ -369,8 +412,8 @@ properly formatted `subagent-result`.
 
 | Worker `status` | flow-orchestrator action |
 |---|---|
-| `DONE` | Accept. `keryx flow task done <id> <Tn>`. Continue. |
-| `DONE_WITH_CONCERNS` | Accept, record every concern in `journal.md`, decide continue vs. add a fix task, then `flow task done`. Never silently drop concerns. |
+| `DONE` | Accept, run the task boundary commit (above), `keryx flow task done <id> <Tn>`. Continue. |
+| `DONE_WITH_CONCERNS` | Accept, run the task boundary commit (above), record every concern in `journal.md`, decide continue vs. add a fix task, then `flow task done`. Never silently drop concerns. |
 | `NEEDS_CONTEXT` | Do not fail. Enrich `context_refs`/`files_to_read` from gdgraph/gdctx/wiki/memory, then re-dispatch the same `dispatch_id`. |
 | `BLOCKED` | `keryx flow block <id> --reason "<worker reason>"`; resolve or escalate one concise question, then `flow unblock` and re-dispatch. |
 | `FAILED` | Emitted by harness **child** workers (`src/harness/child/contract.ts`), never by skill workers — `task-implementer` maps its own `failed` onto `BLOCKED`. Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
@@ -636,3 +679,18 @@ keryx skills contracts validate <file> --schema subagent-result
   completion.
 - Do not read broad source trees when gdgraph/gdctx/wiki/memory can first
   narrow context.
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The worker's reply reads like it finished, so the task is done." | The STATUS protocol says read the `STATUS:` line first and never infer the outcome from prose. A reply without one is `NEEDS_CONTEXT` — a confident-sounding summary is exactly what an unusable result looks like. |
+| "`DONE_WITH_CONCERNS` is still done, so I can move on." | Every concern goes into `journal.md` and gets an explicit continue-or-fix decision before `flow task done`. Concerns dropped at the task boundary are invisible by the completion report, which is where they would have mattered. |
+| "The acceptance criterion no longer matches what we built, so I'll reword it." | Frozen AC changes only through `keryx flow ac update <id> --reason "<why>"`. Rewriting a criterion to fit the implementation makes the flow pass a gate it actually failed, and leaves no record that it moved. |
+| "`flow.json` is just a file — editing one field is faster than the CLI." | `flow.json`, status transitions, task status and attempt counts are CLI-owned. A hand-written field desynchronises the durable state from the flow's own history, and the CLI's next gate check reads yours, not reality. |
+| "Tests pass and the review is clean, so I'll open the PR and complete the flow." | Phase 4 stops and asks the user how the flow should end; not every flow wants a PR. And completion requires a confirmed merge into the base branch captured at creation — not a green local run. |
+| "The worker returned BLOCKED twice — faster if I implement this task myself." | The implementer never self-accepts and the orchestrator never implements. Block the flow, escalate one concise question, then unblock and re-dispatch. Doing the work here erases the boundary the whole flow model rests on. |
+| "Verification is described in the plan, so it will happen." | A verification step in the plan is a task, not a sentence. If it is not a task with a status, nothing records whether it ran, and the flow reaches `implemented` with an unrun gate. |
+| "The review fan-out is cheap, so the budget check can wait." | `keryx review budget --spent … --outstanding …` gates the fan-out, and `review-orchestrator` nests under this skill where keryx cannot see the in-flight subagents. Skipping the check means the cap bounds nothing. |

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: issue-analyzer
-description: "Use when decomposing a GitHub issue into atomic tasks for AI implementation, planning task breakdown, or preparing work for task-implementer agents."
+description: "Use when decomposing a GitHub issue into atomic tasks for AI implementation, planning task breakdown, or preparing work for task-implementer agents. NOT for: writing the code for those tasks (use task-implementer)."
 triggers:
-  - "Analyze issue"
-  - "Decompose issue"
-  - "Break down issue"
+  - "analyze issue"
+  - "decompose issue"
+  - "break down issue"
   - "Issue to tasks"
   - "Plan issue implementation"
 metadata:
   author: "MrCipherSmith"
   version: "1.1.0"
-  category: "analysis"
+  category: "orchestration"
   agent_worthy: true
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/orchestrator-prompt.md

@@ -62,7 +62,7 @@ Fill in the template below and launch via Task tool.
 You are running the issue-analyzer skill in AUTONOMOUS MODE.
 DO NOT ask the user any questions. Execute the full workflow end-to-end.
 
-Load the skill: issue-analyzer (from skills/issue-analyzer/SKILL.md)
+Load the skill: issue-analyzer (from skills/gdskills/orchestration/issue-analyzer/SKILL.md)
 
 ═══════════════════════════════════════════════
   INPUT PARAMETERS

package/src/gdskills/bundled/skills/orchestration/job-documenter/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: job-documenter
 model_tier: light
-description: "Use when a job folder needs to be initialized, or analysis/report/review documents need to be created or updated in jobs/."
+description: "Use when a job folder needs to be initialized, or analysis/report/review documents need to be created or updated in jobs/. NOT for: producing the analysis or report content itself — this skill persists what the orchestrator hands it (use job-orchestrator)."
 triggers:
-  - "Document job"
+  - "job docs"
+  - "document job"
+  - "persistent job documentation"
   - "Initialize job folder"
   - "Save job report"
   - "Add job document"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "documentation"
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -345,7 +347,7 @@ When the orchestrator dispatches this skill as a sub-agent, it should use this p
 ```
 You are the job-documenter agent. Your task is to manage job documentation.
 
-Load the skill from: skills/orchestration/job-documenter/SKILL.md
+Load the skill from: .metaproject/skills/gdskills/orchestration/job-documenter/SKILL.md
 Follow the rules from: rules/core/jobs-documentation.mdc
 
 ACTION: <action>
@@ -372,3 +374,41 @@ Execute the action and return a DOCUMENTER_RESULT block.
 8. **DO NOT** delete or overwrite existing documents without explicit instruction.
 9. **DO NOT** modify files in other job folders.
 10. **DO NOT** interact with the user directly — all communication goes through the orchestrator.
+
+---
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The write call raised no error, so the file is there." | Rule 3 requires verifying existence after every write. A missing parent directory, a `JOBS_ROOT` that does not exist, or a path assembled from a truncated job name all fail in ways that look like success until the orchestrator reads back nothing. |
+| "`JOBS_ROOT` wasn't in the dispatch, so `.metaproject/jobs/` is the obvious default." | The JOBS_ROOT note forbids resolving it yourself, with no fallback. A missing `JOBS_ROOT` is a `status: error` result — writing to a guessed root scatters a job's documents where the orchestrator will never look for them. |
+| "The README table already lists this document, so the directory must match it." | The README is what you wrote; the directory is what exists. `finalize` cross-checks every table entry against a real listing precisely because those two drift, and the drift is invisible from either side alone. |
+| "A document with this name already exists, so the new content replaces it." | Rule 8: no overwrite without explicit instruction. The existing file is a previous phase's record; the orchestrator asked to ADD a document, not to erase the trail it is keeping. |
+| "The file operation failed, so I should stop and surface the exception." | Rule: never throw. The orchestrator has a decision to make (retry, continue, abort) and can only make it from a structured `DOCUMENTER_RESULT` with `status: error` and `error_details`. A crash gives it nothing to route on. |
+| "The payload the orchestrator sent is thin — I'll ask the user what to put in the report." | Rule 10: no direct user contact. Persist exactly what was handed over; an incomplete payload is reported as a discrepancy, not filled in from a conversation this skill is not part of. |
+| "The job is basically finished, so I'll set the README status to completed." | Only the `finalize` action, with an explicit `FINAL_STATUS`, may set it. Marking a job complete from inside `add-document` reports an outcome the orchestrator has not reached. |
+
+---
+
+## Verification
+
+Report `STATUS: <TOKEN>` as the first line of the response, followed by the `DOCUMENTER_RESULT` block:
+
+```
+STATUS: DONE                — the action completed and every written path was verified to exist
+STATUS: DONE_WITH_CONCERNS  — the action completed, but the README/directory cross-check found discrepancies
+STATUS: BLOCKED             — cannot proceed: JOBS_ROOT missing from the dispatch, job folder absent for a non-init action
+STATUS: FAILED              — a file operation failed and could not be recovered; error_details says what
+```
+
+Before reporting `DONE`, all of these must hold:
+
+- Every path named in `DOCUMENTER_RESULT` was listed or read back after writing, not inferred from the write succeeding.
+- Every document written carries its metadata block and an ISO 8601 UTC timestamp.
+- `README.md`'s Documents tables and the real contents of `man/` and `ai/` agree entry for entry; any mismatch is reported in `verification`, never quietly corrected in only one of the two.
+- No file was created, modified or deleted outside `<JOBS_ROOT>/<JOB_NAME>/`.
+- The `DOCUMENTER_RESULT` block names the action actually performed and has every field that action's contract defines; `status: error` always carries `error_details`.
+- For `finalize`: README Status equals the given `FINAL_STATUS`, `total_documents` matches the real file count, and the summary is present.

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -1,19 +1,14 @@
 ---
 name: job-orchestrator
-description: "Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents."
+description: "Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents. NOT for: the same pipeline under Task Manager flow state (use flow-orchestrator)."
 triggers:
-  - "Implement issue"
+  - "implement issue"
+  - "full workflow"
+  - "orchestrate task"
   - "Issue to PR"
-  - "Orchestrate"
   - "Run pipeline"
   - "Analyze and implement"
   - "Full implementation"
-  - "Full review"
-  - "Полное ревью"
-  - "Review my code"
-  - "Analyze branch"
-  - "Review via orchestrator"
-  - "Orchestrated review"
   - "Auto-implement"
   - "Auto-implement issue"
   - "Orchestrate issue"
@@ -610,19 +605,14 @@ CONTEXT_RESULT:
 into every subsequent dispatch prompt:
 
 ```
-CONTEXT_LOCATION: <JOBS_ROOT>/<job-name>/context_v<N>.md
+CONTEXT_LOCATION: <JOBS_ROOT>/<job-name>/ai/context.md
 ```
 
-**Context versioning:** never overwrite an existing context file — write snapshots as
-`context_v1.md`, `context_v2.md`, and so on. Version 1 comes from the first collect in
-2.3; each update writes the next number.
-
-The current version is the highest-numbered file in the package, which is a fact on
-disk that any session can read:
-
-```bash
-ls .metaproject/jobs/<job-name>/context_v*.md
-```
+**Context versioning:** the file lives at this one fixed path and is overwritten in
+place on every update — never written to a new, version-numbered filename. Each
+collect/update instead increments the `Version` field in the document's own
+"Document Metadata" table and appends a line to its `Update Log` section (see
+context-collector SKILL.md §4.1, §4.3); that table on disk is the current version.
 
 `state.json` does not carry a context pointer and nothing writes one — do not tell a
 sub-agent to look for one. The orchestrator passes the path (Constructing Subagent
@@ -645,7 +635,7 @@ Task({
     JOB_NAME: <job-name>
     JOBS_ROOT: <JOBS_ROOT>
     PROJECT_DIR: <project_dir>
-    CONTEXT_VERSION: <current version + 1>  ← write to context_v<N+1>.md
+    CONTEXT_VERSION: <current version + 1>  ← written into ai/context.md's Version field; file overwritten in place
 
     DATA:
       TASK_DESCRIPTION: <original task description>
@@ -703,6 +693,8 @@ fi
 
 > **IMPORTANT**: After creating the worktree, ALL subsequent operations (implementation, review, lint, test, git) MUST run in the **worktree directory**, NOT in the original project directory.
 
+> **Concurrency**: every subsequent git command MUST use `git -C <worktree_path>`, never a bare `git`, and MUST NOT `git stash` or `git add -A`/`--all`/`.` — see `rules/core/git-concurrency.mdc`. Pin each dispatch to `<worktree_path>` explicitly; a dispatched agent's first action is `cd <worktree_path> && pwd && git branch --show-current`, re-checked before its first write.
+
 **Record state:**
 ```
 BRANCH_STATE:
@@ -770,9 +762,15 @@ FOR wave_index, wave_tasks in enumerate(WAVES):
   Wait for ALL of them.
 
   Read each result's STATUS line:
-    all DONE                  → continue to next wave
-    any DONE_WITH_CONCERNS    → record the concerns, continue
-    any BLOCKED               → STOP, read the result file, resolve or ask the user
+    DONE / DONE_WITH_CONCERNS → accept it (record every concern)
+    BLOCKED                   → do not accept it; read its result file
+
+  # Task boundary commit, for EVERY accepted result, before anything else,
+  # whatever auto_commit was (see "Task boundary commit" below):
+  FOR each accepted result: commit its still-changed reported paths, or skip
+
+  any BLOCKED → STOP, resolve or ask the user
+  otherwise   → continue to next wave
 ```
 
 #### tests-creator dispatch (Step A)
@@ -792,7 +790,7 @@ Task({
     - branch:           <branch name>
     - package_manager:  <pm>
     - run_command:      <runner>
-    - context_path:     <JOBS_ROOT>/<job-name>/context_v<N>.md
+    - context_path:     <JOBS_ROOT>/<job-name>/ai/context.md
 
     ## Required response
     Begin with STATUS: <STATUS>. Return the test_case_specs for this task and
@@ -820,12 +818,15 @@ Task({
     - run_command:      <runner>
     - issue_number:     <N>
     - job_name:         <job-name>
-    - context_path:     <JOBS_ROOT>/<job-name>/context_v<N>.md
+    - context_path:     <JOBS_ROOT>/<job-name>/ai/context.md
+
+    ## Automation (task-implementer input `automation`)
+    - auto_commit:      <implementer_settings.auto_commit>   # false: do not commit; report exact paths
 
     ## Required response format (compact — no inline JSON)
     STATUS: DONE
     Task: <task_id>
-    Commits: [abc1234 feat(x): ...]
+    Commits: [abc1234 feat(x): ...]    # auto_commit=false: Commits: none (auto_commit=false)
     Tests: <N passed, M failed>
     Result file: <JOBS_ROOT>/<job-name>/results/<task_id>.json
 
@@ -833,6 +834,42 @@ Task({
 })
 ```
 
+**Who commits is set by the dispatch, never by a default.** Step B always passes
+`auto_commit` explicitly. The worker's own default is `true`, so a dispatch that
+leaves it out gets a worker that commits even when `implementer_settings.auto_commit`
+is `false`.
+
+**Task boundary commit, for every accepted result, whatever `auto_commit` was:**
+a task is not done until its diff is committed (`rules/core/git-concurrency.mdc`
+rule 4, "Reporting Back"). As soon as a result is accepted (`STATUS: DONE` or
+`DONE_WITH_CONCERNS`), take its reported `files_modified`/`files_created`/
+`files_deleted` from the result file and commit the ones git still shows as
+changed, never `-A`/`--all`/`.`:
+```bash
+set -- <each files_modified/files_created/files_deleted path, single-quoted: 'src/a.ts' 'docs/b c.md'>   # may be none; an unquoted path with a space splits and is skipped
+PENDING=()
+for p in "$@"; do
+  [ -n "$(git -C <worktree_path> status --porcelain -- "$p")" ] && PENDING+=("$p")
+done
+if [ ${#PENDING[@]} -eq 0 ]; then
+  echo "boundary commit: nothing left to commit, skipped"
+else
+  git -C <worktree_path> add -- "${PENDING[@]}"
+  git -C <worktree_path> commit -m "<type>(<scope>): <task description>
+
+task: <task_id>" -- "${PENDING[@]}"
+fi
+```
+With `auto_commit=false` this commits exactly the worker's paths. With
+`auto_commit=true` the worker already committed, so nothing is left and the step
+skips. That is the expected outcome, not an error. If paths remain after an
+`auto_commit=true` worker, it left part of its diff uncommitted: the step
+commits it, and you record that as a concern. Each path is checked on its own
+because `git status --porcelain --` with no path lists the whole tree, `git add`
+fails on a path that is neither on disk nor tracked, and `git commit` with
+nothing staged exits 1. The trailing `-- "${PENDING[@]}"` commits only these
+paths, so a file another lane staged is not swept into this commit.
+
 **Each wave runs in ONE worktree.** The worktree created in 2.4 is the whole job's
 workspace — waves are ordered, not isolated from each other, and a later wave sees
 what an earlier one committed. That is what makes the dependency order mean anything.
@@ -904,7 +941,7 @@ git log <merge_base>..HEAD --oneline
 
 | Check | Pass | Fail action |
 |-------|------|-------------|
-| At least 1 commit exists | ≥1 commit | `retryable` — re-dispatch the task-implementers for that wave with: "No commits were made. Implement the changes and commit them." |
+| At least 1 commit exists | ≥1 commit | `implementer_settings.auto_commit=true`: `retryable` — re-dispatch the task-implementers for that wave with: "No commits were made. Implement the changes and commit them." `auto_commit=false`: the task-boundary commit (wave loop, after Step B) should already have committed each accepted result's files — if none exist, `retryable`: re-run that commit step for the wave's result files instead of re-dispatching workers. |
 | At least 1 file modified | ≥1 file changed | Same as above |
 | Claimed files actually modified | All files named in the result files appear in the diff | Log discrepancy as a concern, continue |
 
@@ -1095,7 +1132,7 @@ Task({
     flags:            <selected flags, e.g. --backend --security --testing-practices>
     commit_range:     <BASE_SHA>..HEAD
     issue_url:        <issue URL, when the job has one — enables the Stage 1 spec gate>
-    context_doc:      <JOBS_ROOT>/<job-name>/context_v<N>.md
+    context_doc:      <JOBS_ROOT>/<job-name>/ai/context.md
     verification_mode: annotate
     managed_review:   { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
     is_fix_round:     <true on any round after the first>
@@ -1426,7 +1463,7 @@ IF no skill_drift and Skill Learning == none:
 ELSE for each flagged project-skill:
   1. Dispatch a subagent to build the learning proposal:
      - Model: COMPUTED, not chosen — run
-         keryx review tier --scope narrow --json
+         keryx review tier --findings 1 --diff-lines 0 --json
        and paste the `model` block into the dispatch. The command names no model:
        it ranks what the provider reports at runtime, and when it cannot rank
        anything it prints `inherit: true`, which means the dispatch runs on the
@@ -1514,7 +1551,7 @@ JOB_NAME: <job-name>
 BRANCH: <feature_branch>
 BASE: <base_branch>
 ISSUE_NUMBER: <issue_number if available>
-CONTEXT_PATH: <JOBS_ROOT>/<job-name>/context_v<N>.md
+CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md
 ```
 
 `pr-issue-documenter` will analyze the branch diff and produce a structured PR description (Summary + Changes by area + Key Files table). Use its output as the `body` for the PR.
@@ -1704,7 +1741,7 @@ the dispatch prompt, or it does not reach the sub-agent:
 ```
 branch:      { name, worktree_path, merge_base, package_manager, run_command }
 analysis:    { total_tasks, tasks, dependency_order }
-context_doc: the path to the highest-numbered context_v<N>.md in the package
+context_doc: the path to the job's ai/context.md
 review:      the current round's findings — the durable copy is the managed review
              package, not this
 ```
@@ -2087,6 +2124,25 @@ wrong, cannot be undone by trying again.
 
 ---
 
+## Red Flags
+
+The two callouts above ("the result looks fine without a status line", "the
+subagent can read `state.json` itself") are the two this orchestrator gets wrong
+most often. These are the rest. Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The worker returned `STATUS: DONE`, so the task is verified." | `DONE` is the worker's report that it finished its own task, self-check included. The gate is step 2.8: `code-verifier` over the wave's whole diff. A task can be individually DONE and still break the build the moment it meets the other tasks in the wave. |
+| "The user is right here — I'll just ask which option they prefer." | Between Phase 0 and completion there are exactly two reasons to ask: a critical failure, and extending the plan from analyze to implement. Everything else was settled in Phase 0. A mid-run question turns an autonomous run into a session the user has to babysit. |
+| "`git checkout -b` is simpler than setting up a worktree for this one." | It switches the user's own working directory out from under their live session, mid-run. This is in the "unrecoverable if wrong" list: `git worktree add`, always, and every later command runs inside that worktree. |
+| "I know this step completed — recording it through `keryx job` is bookkeeping." | The package IS the state. `keryx job` is the only writer of `state.json`, and a resumed session knows only what it reads there. A step held in this session's head did not happen as far as the next session is concerned. |
+| "The subagent will work better with the full analysis JSON, so I'll paste it in." | The minimality principle: each subagent type gets its scoped slice. Extra context does not add capability; it fills the window with material the worker must first decide is irrelevant, and raises the odds it invents something from it. |
+| "This step failed twice — one more attempt with a sharper prompt should do it." | The retry protocol is one retry with the EXACT same prompt plus the error list; a second failure escalates to the user. Re-deriving the prompt causes drift, and the drifted attempt no longer tests the same thing. |
+| "The branch is ready and the PR is the obvious next step, so I'll push." | Do not push until the user confirms, unless `auto_create_pr` is set. A push is visible to everyone watching the repository, and there is no un-push they will not see. |
+| "The job finished cleanly, so the report can be short." | Say where the job package is, every time. It is the only durable record of the run; a user who cannot find it is left with a summary and nothing to check it against. |
+
+---
+
 ## Configurable Jobs Root
 
 `JOBS_ROOT` in this document is shorthand for **`.metaproject/jobs`, relative to the