@mrciphersmith/keryx 0.2.98 → 0.2.99

package/src/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.md

@@ -131,7 +131,7 @@ Three fields, three different jobs, and mixing them is the recorded failure mode
 somewhere else and will move on; without the hash, a reviewer built from last
 month's version reads as current forever, and nobody finds out until its findings
 disagree with the standard it claims to encode. With it,
-`keryx review reviewers` reports `drift: changed` the moment the file differs.
+`keryx review reviewers` prints that reviewer's row as `- <name> (<origin> — changed)` the moment the file differs.
 
 Quote the path if it starts with `~` and you want it stored that way; an
 unquoted `~` is expanded by the shell before keryx sees it. Either is fine —
@@ -192,8 +192,8 @@ keryx review reviewers
 
 The second is the one that matters: it is the same call
 `review-orchestrator` makes, so its output is proof the reviewer will be
-dispatched rather than a hope. Check the row shows your reviewer with
-`drift: clean`.
+dispatched rather than a hope. Check the row reads `- <reviewer-name> (<origin> — clean)` — `changed` means the
+source moved, `missing` that it no longer resolves, `no recorded origin` that the reviewer was created without `--origin`.
 
 Then say, in your reply, which of the three piles from Step 1 you kept, which you
 dropped, and what you could not verify against this project.
@@ -216,8 +216,8 @@ dropped, and what you could not verify against this project.
 
 ## Refreshing a reviewer whose source moved on
 
-`keryx review reviewers` reporting `drift: changed` means the source file differs
-from what was imported. It does **not** mean the reviewer is wrong.
+A row of `- <name> (<origin> — changed)` from `keryx review reviewers` means the
+source file differs from what was imported. It does **not** mean the reviewer is wrong.
 
 Re-read the source, diff it against what the skill encodes, and then decide per
 change: fold it in, or record in the skill why this project deliberately differs.
@@ -241,3 +241,40 @@ undocumented is drift that will be silently "fixed" by whoever refreshes next.
 | Decide which reviewers a round dispatches | NO | `review-orchestrator` |
 | Import a tree of overlay reviewers | YES — `keryx skills import --from <dir> --module review` (`keryx review import` alias) | — |
 | Import a non-review SKILL.md / GitHub URL | NO | `entity-skill-creator` / `keryx skills import` |
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "The source's voice is what makes it a good standard — stripping it loses the edge." | A reviewer distilled from someone's tone reviews tone. Step 4 drops the persona pile whole and keeps the method with its reason beside it; a reason transplants into a codebase the author never saw, and an assertion does not. |
+| "I know where the source file lives, so `--origin` adds nothing." | Without the recorded hash, a reviewer built from last month's version of that file reads as current forever, and nobody finds out until its findings disagree with the standard it claims to encode. `drift: changed` is the whole point. |
+| "The target should say what the reviewer is for, so a sentence is clearer." | The target is a routing key that `keryx skills route` matches queries against. A sentence there produces a skill that matches nothing and verifies as permanently stale. The prose belongs in `--note`. |
+| "The source has a clear severity scale, so I will carry it over." | Ten private rubrics feeding one sorted report produce a ranking that means ten things at once. Point at **Severity (canonical)** and add one table saying where this reviewer's recurring conditions land under it. |
+| "The files are written and the frontmatter is valid, so the reviewer is wired." | Creating files is not registration, and registration is not discovery. Until `keryx review reviewers` prints the name, the orchestrator will never dispatch it. |
+| "The source's conventions are sensible, so they will hold in this project too." | They are true of the source's own codebase until verified here. Keep a convention only after checking it against this project, and say in your reply which ones you could not check. |
+| "The row came back `— changed`, so the reviewer is wrong and I will overwrite it." | It means the source moved, not that the reviewer is wrong. Diff the two and decide per change: fold it in, or write down why this project deliberately differs. An undocumented divergence is drift the next refresh silently "fixes". |
+
+---
+
+## Verification
+
+Report done only once all of these hold:
+
+- `keryx skills verify review/<reviewer-name>` passes.
+- `keryx review reviewers` lists the reviewer as `- <reviewer-name> (<origin> — clean)` — that literal row, not a `drift:` field, which the command never prints. This is the
+  same call `review-orchestrator` makes, so its output — not the presence of the
+  files — is what proves the reviewer will be dispatched.
+- The `SKILL.md` carries all six required parts from Step 3: Scope naming the
+  neighbouring reviewers it excludes, a Checklist of performable checks, a
+  pointer to the canonical severity rubric with no rubric of its own, the three
+  shared laws verbatim, the class-scope contract, and the Orchestrated Review
+  Contract with its own finding-id prefix.
+- `--origin` was passed whenever a source file exists, and the recorded path is
+  the one a human would read later.
+- Any method that only works when a command is run — a mutation, a measurement, a
+  probe — is stated as an iron law, together with what the finding is worth
+  without it.
+- The reply says which of Step 1's three piles were kept, which were dropped, and
+  what could not be verified against this project.

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: code-verifier
 model_tier: light
-description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report."
+description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report. NOT for: fixing what the gate reports — this skill is read-only (use task-implementer)."
 triggers:
+  - "verify code"
+  - "run checks"
+  - "quality gate"
   - "Run verification"
-  - "Quality gate"
   - "Check code quality"
   - "Run lint and tests"
   - "Verify implementation"
-  - "Run checks"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
@@ -328,3 +329,18 @@ code-verifier:
 3. **Scope to changed files** by default — full scans are slow and produce noise.
 4. **Be specific** in findings — include file, line, rule, message. Vague "lint failed" is not actionable.
 5. Return `VERIFICATION_RESULT` as the **final message** to the orchestrator.
+
+---
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "Lint already failed, so running the type-check and tests adds nothing." | Rule 1: run ALL checks. The orchestrator sizes one fix wave from the full picture. Aborting early means it fixes lint, re-dispatches, then discovers the type errors — one wave per check instead of one wave. |
+| "This type error is a one-line fix — faster to correct it than to report it." | Rule 2: this gate is read-only. A verifier that edits has verified its own edit, and the diff the reviewer sees no longer matches what the implementer wrote. Report it; let the fix come back through the loop. |
+| "The lint binary isn't installed, so there is nothing wrong — the gate passes." | A check that did not run is `status: skipped`, never `pass`. `gate: PASS` on an empty check set is a false all-clear, and zero checks available is `STATUS: BLOCKED` by the Error Handling table. |
+| "`gate: FAIL`, so my STATUS must be BLOCKED." | STATUS reports whether THIS SKILL ran, not what it found. A complete report of a failing gate is `STATUS: DONE`. `BLOCKED` tells the orchestrator verification never happened and it must resolve tooling — a different, wrong branch. |
+| "That failing test is unrelated to the diff, so I'll record it as skipped." | `skipped` means it did not run. A failure you judged out of scope is still `failed`, with a finding. Deciding what is in scope is the orchestrator's call, and it cannot make it on a result you rewrote. |
+| "I hit `max_findings_reported`, so the remaining findings can go unmentioned." | The cap limits the list, not the count. Report the true totals in `checks:` and say in `summary` that the finding list is truncated, or the orchestrator plans a fix wave against a number that is quietly too small. |

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: context-collector
-description: "Use when a job needs a unified context document — gathering docs, libraries, and references for sub-agents before execution."
+description: "Use when a job needs a unified context document — gathering docs, libraries, and references for sub-agents before execution. NOT for: deciding what to build from that context (use interview, or job-orchestrator for the whole pipeline)."
 triggers:
-  - "Collect context"
-  - "Build context"
-  - "Gather context"
+  - "collect context"
+  - "gather context"
+  - "build context"
   - "Update context"
   - "Refresh context"
   - "Context for job"
@@ -653,3 +653,19 @@ Execute update flow and return a CONTEXT_RESULT block.
 10. **DO NOT** fetch external docs for standard well-known patterns already covered by project rules.
 11. **DO NOT** modify any project files — this is a read + research + write-to-jobs skill only.
 12. **DO NOT** skip the metadata block and update log — they are mandatory for version tracking.
+
+---
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "More context is safer, so I'll include everything I found." | Rule 9 caps `context.md` at ~500 lines, and 3.4 admits only HIGH and MEDIUM findings. A 1200-line context is read by no sub-agent; the three paragraphs that mattered are now buried, which is the same as not having collected them. |
+| "I know this library well, so I can write the API section from memory." | Phase 3 fetches the docs for the version the project actually pins. A remembered signature is the single most expensive thing in this document: every sub-agent downstream implements against it without checking. |
+| "The task mentions React, so I should fetch React documentation." | Rule 10: no external fetch for well-known patterns already covered by project rules. External research is for the specific API, version gotcha or convention this task turns on — not for a topic overview. |
+| "This section of the existing context looks stale, so I'll drop it while updating." | 4.3 and Rule 4: preserve existing sections unless they are explicitly outdated. "Looks stale" from inside a scoped update usually means "I did not re-research it" — removing it silently deletes a decision another agent is relying on. |
+| "I fixed the small inconsistency I noticed in the source file while reading it." | Rule 11: this skill writes only into the job folder. An edit made during collection lands in a diff nobody attributed to a task, and the implementer inherits it without knowing. |
+| "The context is written, so I can return — job-documenter can be called later." | Phase 5 is part of the skill. A `context.md` that was never persisted through `job-documenter` is absent from the README index, and the next phase resolves the path to nothing. |
+| "The content changed only slightly, so bumping the Version and update log is overkill." | Rule 12 and Rule 3: version, timestamp and update log are mandatory. Without them, two agents reading different revisions have no way to tell which one they have. |

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

@@ -1,7 +1,10 @@
 ---
 name: feature-analyzer
-description: "Use when analyzing feature branch changes across repos, planning implementation, or understanding backend→frontend contracts. Requires the source repository, target repository, and branch as confirmed input; the skill's PRE-STEP validates them before any analysis."
+description: "Use when analyzing feature branch changes across repos, planning implementation, or understanding backend→frontend contracts. Requires the source repository, target repository, and branch as confirmed input; the skill's PRE-STEP validates them before any analysis. NOT for: breaking an issue into implementable tasks (use issue-analyzer)."
 triggers:
+  - "analyze feature"
+  - "study module"
+  - "investigate branch"
   - "Analyze branch"
   - "Analyze changes"
   - "Analyze commit"
@@ -409,15 +412,35 @@ Follow `documentation-management.mdc`: update `<DOCS_ROOT>/readme.md`, add entry
 
 ---
 
-## Success Criteria
+## Red Flags
 
-Analysis is successful when:
-- Business logic is fully understood and documented
-- API contracts are clearly specified
-- Breaking changes are identified
-- Implementation plan is actionable
-- User confirms understanding via intermediate review
-- All P0 files analyzed completely
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The user named a branch, so I have enough to start." | The PRE-STEP needs source repo, target repo and branch, each confirmed. A branch without its repo pair is how a cross-repo analysis quietly becomes source-only and reports no frontend impact because it never looked at the frontend. |
+| "`git diff` came back empty, so the branch changed nothing." | Step 12 names the three usual causes: the wrong BASE_SHA, changes that are staged or untracked, and the wrong branch checked out. Report "no changes" only after `--cached`, `git status` and the branching point all agree. |
+| "I read the diff hunks, so I understand the change." | A hunk shows the lines that moved, not the contract they belong to. The Deep Dive Protocol reads P0 files whole because the breaking part of a change is usually the caller the diff never touched. |
+| "The finding is clear from the code I just read — the line reference can wait." | Step 11 makes a `file:L123` citation mandatory for every claim. An uncited claim cannot be checked by the developer acting on it, and a report of uncited claims is indistinguishable from a plausible guess. |
+| "There are 6 P0 files but the picture is obvious, so I'll skip the intermediate review." | Rule 5 forbids skipping it above 3 P0 files. The intermediate review is the only point where the user can correct the scope before a full report is written against the wrong one. |
+| "An analysis for this feature already exists, so I'll write mine into a new folder." | Step 10 requires updating `report.md` and `implementation-plan.md` in place. Parallel copies mean the next reader picks one, and nothing marks which is current. |
+| "GitHub MCP is unavailable, so issue and PR context is out of reach." | Step 12's fallback is git history plus a notice to the user — not silence. An analysis that drops the issue context without saying so reads as if the issue held nothing relevant. |
+
+---
+
+## Exit Criteria
+
+Do not report the analysis as complete until all of these hold:
+
+- The PRE-STEP inputs (source repo + branch, target repo + branch, mode) were confirmed by the user, not inferred — and the report states them.
+- Mode A: `BASE_SHA` is recorded in the report. Mode B: the report says explicitly that it describes current state, not a diff.
+- Every P0 file was read in full and appears in the analysed-files list; the P0/P1/P2 counts in `## Analysis Metrics` match that list.
+- `report.md` contains at least 3 code examples, and every claim carries a `file:line` reference.
+- API contracts and breaking changes each have a section — a "none found" is written out with what was checked to reach it.
+- `implementation-plan.md` exists and every step names a file or module to touch; no step reads "investigate".
+- `## Analysis Metrics` includes the computed complexity score and its inputs.
+- The user answered the intermediate review prompt (mandatory whenever P0 files > 3), and any correction they made is reflected in the final report.
+- Step 15 post-analysis is done: `<DOCS_ROOT>/readme.md` and the analysis index name this analysis.
 
 ---
 

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

@@ -1,9 +1,10 @@
 ---
 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"
@@ -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)
@@ -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"
@@ -678,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,10 +1,10 @@
 ---
 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:

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,9 +1,11 @@
 ---
 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"
@@ -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"
@@ -2129,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

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: task-implementer
 model_tier: standard
-description: "Use when implementing a single decomposed task from issue-analyzer end-to-end, or executing autonomous code changes from a JSON task object."
+description: "Use when implementing a single task out of an issue-analyzer breakdown end-to-end, or executing autonomous code changes from a JSON task object. NOT for: splitting an issue into that breakdown in the first place (use issue-analyzer)."
 triggers:
-  - "Implement task"
+  - "implement task"
+  - "execute task"
+  - "atomic task"
   - "Execute task scenario"
   - "Code this task"
   - "Run task-implementer"
@@ -183,7 +185,7 @@ This step is read-only and inline; do not spawn a subagent for it.
   (`input-contract.schema.json`). Empty means none; the string `"none"` is not a
   legal value and a request carrying it is refused by 1.4
 - Read each file listed in either array
-- Understand existing test patterns (describe/it structure, mocks, fixtures)
+- Understand existing test patterns (describe/it structure, mocks, fixtures) and, for every file in `existing_stories`, the story patterns it uses (`Meta`/`StoryObj` shape, how variants are declared, how callbacks are stubbed) — 4.4 builds on what you record here
 
 **2.3 Read module neighbors:**
 - List sibling files in the same directory as each target file
@@ -223,16 +225,6 @@ Based on what you're implementing, load and follow the relevant project rules.
 Rules live at `.metaproject/rules/core/<rule>.mdc` on every harness — that is the
 one tree `keryx init` installs and the one every build of this skill reads.
 
-**Output of Phase 2:** Mental model of the implementation:
-```
-RESEARCH_SUMMARY:
-  target_files_status: [{path, exists: bool, line_count, key_exports}]
-  test_pattern: <describe structure, assertion style>
-  story_pattern: <Meta/StoryObj, args pattern>
-  module_conventions: <naming, imports, exports, TS patterns>
-  relevant_rules_loaded: [<rule names>]
-```
-
 ### Phase 3: PLAN
 
 Decide the implementation approach. Self-validate — no orchestrator approval needed.
@@ -286,13 +278,6 @@ Execute the change plan. Write production-quality code.
 5. Component/UI layer implementation (make component tests GREEN)
 6. Stories (if needed)
 
-**4.1 Implementation order (TDD Mode — test_case_specs provided):**
-1. Read all test stubs from `test_case_specs.test_files`
-2. Understand the expected API shape from test assertions
-3. Implement types/interfaces to satisfy test imports
-4. Implement code layer by layer until all tests are GREEN
-5. Stories (if needed)
-
 **4.2 Code standards (always follow):**
 - TypeScript strict mode — no `any`, no `as` casts unless justified
 - Use project path aliases for imports (`@components/...`, `@utils/...`)
@@ -302,16 +287,10 @@ Execute the change plan. Write production-quality code.
 - Follow existing module patterns discovered in Phase 2
 
 **4.3 Test standards:**
-- Unit tests: Vitest with `describe`/`it`, `@testing-library/react` for components
-- Use `data-testid` for test selectors
-- Follow AAA pattern (Arrange, Act, Assert)
-- Mock external dependencies, not internal module logic
+- Use the runner, selectors and structure Phase 2.2 found in this project's own tests — not a remembered stack. Arrange/Act/Assert; mock external dependencies, not internal module logic.
 
 **4.4 Story standards:**
-- `Meta` + `StoryObj` pattern
-- `args`-based variants
-- `fn()` for action callbacks
-- Cover: default state, edge cases, error states
+- Use the story patterns Phase 2.2 found (`Meta` + `StoryObj`, `args`-based variants, `fn()` callbacks); cover default state, edge cases and error states.
 
 **4.5 Commit after implementation:**
 
@@ -399,7 +378,6 @@ attempts. The counter cannot tell "converging slowly" from "stuck", and three
 identical outputs cost the whole budget to learn what the second one already
 said. Report the block instead, naming what repeated.
 
-
 **ROLLBACK POLICY**: If implementation fatally fails (tests still failing after 3 attempts, or unresolvable compilation errors), restore ONLY the files this task changed — `git -C "<codebase_path>" checkout -- <your files>` for tracked ones, delete the untracked ones you created — then report the failure in Phase 6.
 
 **Never run `git reset --hard`, `git clean`, or any unscoped revert.** You do not own the worktree. `job-orchestrator` dispatches implementers in PARALLEL WAVES sharing a single worktree, so an unscoped reset destroys a wave-mate's uncommitted work — work that is not yours, cannot be recovered, and whose loss is invisible to you because the other agent's failure surfaces somewhere else entirely. If you cannot identify which files are yours, leave the tree exactly as it is and say so in the report: a dirty tree is recoverable, a destroyed one is not.
@@ -447,12 +425,30 @@ Write full JSON to `<JOBS_ROOT>/<JOB_NAME>/results/<task_id>.json`:
   "story_result": "<pass|build error: details|not applicable>",
   "acceptance_criteria_met": "<all|partial: list of unmet criteria|none>",
   "skill_drift": "<none | stale: <module>/<skill> — <what diverged> | missing: <module> should have a project-skill>",
+  "noticed_not_touched": [{ "what": "<problem>", "where": "<path|symbol>" }],
+  "assumptions": ["<what you assumed where the task did not say>"],
+  "not_touched": [{ "path": "src/path/file.ts", "reason": "<why left alone>" }],
   "notes": "<any warnings, blockers, or additional context>"
 }
 ```
 
 Set `skill_drift` from Phase 2.0b: if the project-skill you used was not `fresh`, or the code you wrote diverged from what a skill documents, name the skill and the divergence. The orchestrator uses this to decide whether to trigger `skills learn` (do NOT run `learn` yourself — it is a mutating step the orchestrator dispatches; see `rules/core/skill-lifecycle.mdc`).
 
+Three of those fields have a bar, and a field that collects noise trains the
+reader to skim all three. Omit one rather than pad it. The trio is adapted (MIT)
+from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) as contract fields rather than a free-text template; the bars below are ours.
+
+- `assumptions` — what you assumed where the task was silent AND acted on. If
+  the assumption being wrong would not change a line you wrote, it is a hedge,
+  not an assumption; leave it out.
+- `noticed_not_touched` — a problem in code you actually read, stated so a
+  follow-up task could be written from it alone, with `where` it lives. Not a
+  dumping ground for every smell seen in passing, and not style opinion.
+- `not_touched` — of the files this task was aimed at (`target_files`), the ones
+  absent from `files_modified`/`files_created`/`files_deleted`, each with why.
+  It answers that one question and no other: a reader subtracts those lists and
+  this one from `target_files`, and flags the remainder as an unexplained omission.
+
 Then check the shape and record the file — two commands, both of which refuse
 rather than warn:
 
@@ -496,8 +492,14 @@ Return a compact STATUS response following `rules/core/subagent-status-protocol.
 The inline response must contain only: STATUS line + Completed bullets + Files changed + Verification summary.
 
 **Status classification:**
-- `success` → `STATUS: DONE`
-- `partial` → `STATUS: DONE_WITH_CONCERNS`
+- `success` → `STATUS: DONE`, or `DONE_WITH_CONCERNS` when work that cleared the
+  bar still carries something the orchestrator must know.
+- `partial` → `STATUS: BLOCKED` — never `DONE_WITH_CONCERNS`. An unmet criterion,
+  a failed gate or a gate that did not run breaks `rules/core/definition-of-done.mdc`,
+  and `DONE_WITH_CONCERNS` reports on work that cleared that bar, never a lower
+  one. The harness already reads it this way: `shouldEscalate`
+  (`src/harness/child/escalation.ts`) escalates on any `acceptance[].status` of
+  `not_met` whatever token arrived with it.
 - `failed` → `STATUS: BLOCKED`
 
 ---

package/src/gdskills/bundled/skills/orchestration/task-implementer/output-contract.schema.json

@@ -47,9 +47,40 @@
       "type": "string",
       "description": "Set from SKILL.md Phase 2.0b: 'none' | 'stale: <module>/<skill> — <what diverged>' | 'missing: <module> should have a project-skill'. SKILL.md has required this field since project-skill verification was added; this object is `additionalProperties: false`, so until it was declared here a compliant result was REFUSED by its own contract."
     },
+    "noticed_not_touched": {
+      "type": "array",
+      "description": "Problems seen in passing and deliberately left alone because they were out of scope. Candidate follow-up work: the location is required because a note a reader has to go searching for is a note nobody acts on. Omit the field when nothing was noticed; `[]` says the same thing explicitly.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["what", "where"],
+        "properties": {
+          "what": { "type": "string", "minLength": 1, "description": "The problem, stated so a follow-up task could be written from it alone" },
+          "where": { "type": "string", "minLength": 1, "description": "Path, directory or symbol it lives at" }
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "description": "What was assumed where the task did not say. A wrong assumption is the usual cause of a rejected result, so these are the first thing a reviewer should check. Read only by a human — nothing in the result or the request can confirm an assumption, so this is deliberately an array of sentences rather than a structure that would imply a check nobody performs.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "not_touched": {
+      "type": "array",
+      "description": "Files a reader would expect in `files_modified` and will not find there, each with the reason. `path` is a separate field because this is machine-checkable: a reader holding the request can subtract `files_modified`/`files_created`/`files_deleted` and this list from `task.target_files` and flag whatever is left as an unexplained omission.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1, "description": "Why it was left alone — 'already correct', 'out of scope', 'blocked by <x>'" }
+        }
+      }
+    },
     "notes": {
       "type": "string",
-      "description": "Warnings, blockers, or additional context"
+      "description": "Warnings, blockers, or additional context. The three fields above were carved out of this one: free text is where they went before they were declared, and anything that fits one of them belongs there instead."
     }
   }
 }