@mrciphersmith/keryx 0.3.120 → 0.3.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.120",
+  "version": "0.3.122",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/install-manifest.json

@@ -455,7 +455,7 @@
     },
     "review-core-skills": {
       "kind": "skill",
-      "description": "Generic (non-stack-specific) review skills: orchestrator, logic, architecture, security, performance, clean-code, highload, regression, core-boundaries, flow-graph, layout, style, testing-practices, verifier, pr-feedback, and the legacy AI/learned/style review profiles.",
+      "description": "Generic (non-stack-specific) review skills: orchestrator, logic, architecture, security, performance, clean-code, highload, regression, core-boundaries, flow-graph, layout, style, testing-practices, verifier, premise, pr-feedback, and the legacy AI/learned/style review profiles.",
       "paths": [
         "src/gdskills/bundled/skills/review/review-orchestrator/**",
         "src/gdskills/bundled/skills/review/review-logic/**",
@@ -472,6 +472,7 @@
         "src/gdskills/bundled/skills/review/review-style/**",
         "src/gdskills/bundled/skills/review/review-testing-practices/**",
         "src/gdskills/bundled/skills/review/review-verifier/**",
+        "src/gdskills/bundled/skills/review/review-premise/**",
         "src/gdskills/bundled/skills/review/review-pr-feedback/**",
         "src/gdskills/bundled/skills/review/code-ai-review/**",
         "src/gdskills/bundled/skills/review/code-learned-review/**",

package/src/gdskills/bundled/rules/core/session-plan-bridge.mdc

@@ -36,7 +36,7 @@ in progress, so it never makes the agent continue on its own, which is what make
 |---|---|---|
 | `job-orchestrator` | the step ids `keryx job status <name> --json` reports — `analyze`, `context`, `prepare`, `tests-creator`, `implement`, `sanity-check`, `verify`, `review`, `security`, `fix`, `verify-post-fix`, `perf-check`, `report`, `pr`, `deploy` | `keryx job status <name>` (read it, never retype it) |
 | `flow-orchestrator` | the Flow's task ids `T1..Tn` | `keryx flow status <id>` / the Flow's `tasks.md` |
-| `review-orchestrator` | `step-0` … `step-14`, from its own numbered checklist | its Workflow section |
+| `review-orchestrator` | `step-0` … `step-14` and `step-10b`, from its own numbered checklist | its Workflow section |
 
 An id that exists only in the session plan is drift by construction: the operator
 cannot reconcile it with the CLI, and a resumed run cannot match it. If a

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

@@ -39,7 +39,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 
 ### Phase 1: REQUIREMENTS + SPEC
 
-1. Parse input (description or GitHub issue via `gh issue view`)
+1. Parse input (description or GitHub issue via `gh issue view`). An issue filed from a review finding, or an external review comment, is a premise to check: dispatch `review-premise` on it first, shaped and recorded as `flow-orchestrator` Phase 1 says ("A flow sourced from a finding": no `decide-premise`; claims in `<flow-dir>/premise/<n>.json` if a flow exists; with none, its claims object goes into the Implementation Spec under **Premise**), and on `challenged` or `owner-decision` ask the operator its question with its options and journal their answer before writing the spec
 2. Clarify ambiguities — ask the user up to 3 questions max
 3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
@@ -48,8 +48,8 @@ End-to-end feature development workflow from idea to merge-ready PR.
    - **Acceptance criteria**: testable bullet points
    - **Approach**: which files will change, key design decisions
    - **Test strategy**: framework, which scenarios will be covered
-4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already)
-5. **Get user confirmation before proceeding**
+   - **Premise** (only for an input sourced from a finding, with no flow): the review-premise claims object and the operator's answer, in their words
+4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already), then **get user confirmation before proceeding**
 
 ### Phase 2: DESIGN
 
@@ -113,7 +113,7 @@ Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
    - Verify all acceptance criteria from Phase 1 spec
-3. Fix any findings (max 2 review-fix cycles). Each next round is `keryx review start` or `keryx review plan` on the new head: the round comes from `round.json`; no own range, no whole-branch re-review (the `git diff main...HEAD` above is round 1 only).
+3. Fix any findings (max 2 review-fix cycles), never one `review-premise` holds: a held finding is neither fixable nor clean and blocks the cycle until answered; ask the operator about it as `review-orchestrator` "Wave D" says, and only an upheld one is fixed, carrying `premise_verdict` and `premise_answer` as task-implementer's `FIX_CONTEXT` defines them (unattended: stop and report the held list). Each next round is `keryx review start` or `keryx review plan` on the new head: the round comes from `round.json`; no own range, no whole-branch re-review (the `git diff main...HEAD` above is round 1 only).
 4. Re-run `code-verifier` after any fixes
 
 ### Phase 8: DELIVER + CHANGE REPORT

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

@@ -264,17 +264,8 @@ Tasks are the mechanism for this. `keryx flow complete` runs a `tasks` gate over
 
 Know the gate's exact scope, because for years this file claimed a gate that did not exist and 24 completed flows shipped with an open task:
 
-- the gate is **opt-in per flow package**, keyed on `gates.tasks` in
-  `flow.json`, which `keryx flow init` writes for every flow it creates. A
-  package created before the gate landed does not carry the flag, and for it
-  the gate reports `skipped` and blocks nothing;
-- a task fails the gate when its status is not `done`; when its disposition is
-  `failed`; when its disposition is `blocked` (terminal, but the work did not
-  happen — and the harness emits this disposition on its own for a run that
-  ended blocked); when its disposition is `skipped` with no recorded reason; or
-  when its disposition is a value this build does not recognise. An
-  unrecognised disposition FAILS rather than falling through: a gate whose
-  default for the unknown case is "pass" is not a gate;
+- the gate is **opt-in per flow package**, keyed on `gates.tasks` in `flow.json`, which `keryx flow init` writes for every flow it creates. A package created before the gate landed does not carry the flag, and for it the gate reports `skipped` and blocks nothing;
+- a task fails the gate when its status is not `done`; when its disposition is `failed`; when its disposition is `blocked` (terminal, but the work did not happen — and the harness emits this disposition on its own for a run that ended blocked); when its disposition is `skipped` with no recorded reason; or when its disposition is a value this build does not recognise. An unrecognised disposition FAILS rather than falling through: a gate whose default for the unknown case is "pass" is not a gate;
 - to close a task as deliberately not needed, record why:
 
   ```bash
@@ -283,6 +274,8 @@ Know the gate's exact scope, because for years this file claimed a gate that did
 
 Read the `tasks` line in the `flow complete` output. If it says `skipped`, the gate did not run and the task list is yours to verify by hand.
 
+**A flow sourced from a finding: check its premise before freeze.** A follow-up issue filed from a review, or an external review comment, is a premise to check, not a settled requirement. Before `flow freeze`, dispatch `review-premise` with `source: follow-up-issue` or `external-comment` and the finding shaped as its Input Contract `source` row says (the issue number or the comment's `C-NNN` as `id`, its URL as `url`). Skip it when the dispatch says the premise is already recorded (`review-pr-feedback` rule 7 sends a `premise:` constraint). No review package exists, so no `ingest` or `decide-premise` runs: save its claims as `<flow-dir>/premise/<n>.json`, and apply every refusal of the merge by hand, as that `source` row lists them (`PREMISE_REJECTION_REASONS`, `src/review/premise.ts`): a refused claim leaves the finding upheld. On `challenged` or `owner-decision` ask the operator its question with its options (`ask_user` in keryx shell, the host's question tool elsewhere), journal their answer, and plan only what the operator upholds.
+
 Then freeze and start (`--yes`: the operator already answered the kinds question, so the freeze must not prompt):
 
 ```bash
@@ -444,6 +437,7 @@ Before accepting implementation:
 6. If findings require code changes, run a fix round through `task-implementer`, recorded as a flow fix task:
    - **Scope freeze.** A fix round fixes the round's findings and nothing else. Hardening, refactors or new cells a fix suggests go to the operator as a question (as in step 4); never grow scope inside a fix round.
    - **Red probes → ONE implementer.** When reviewers left red probes (failing tests or commands on the findings), pass them as `test_case_specs` to one `task-implementer` dispatch — no separate `tests-creator` task. `tests-creator` runs only for a new contract no probe covers.
+   - **A held finding is not fixed.** A finding `review-premise` held (`challenged` or `owner-decision`) is neither fixable nor clean: it never goes into `fix_context.review_feedback` and it blocks the loop until answered. Ask the operator about it as `review-orchestrator` "Wave D" says (the card in keryx shell; elsewhere the question tool, then the exact `keryx review decide-premise` command for them to run in their terminal) and journal the recorded answer; only an upheld finding enters a fix round, carrying `premise_verdict` and `premise_answer` as task-implementer's `FIX_CONTEXT` defines them. A dispatched run leaves it held and journals it.
    - **`suggested_fix` is a hypothesis.** Pass each finding's `id` and `suggested_fix` in `fix_context.review_feedback`; the implementer reproduces the finding (red), checks the suggestion against the state × event matrix, then fixes (task-implementer 1.3). Journal every `suggested_fix diverged` / `did not reproduce` note it returns.
 7. Close the skill-learning loop (see `rules/core/skill-lifecycle.mdc`). Collect
    the `skill_drift` fields from task-implementer results and the
@@ -532,16 +526,12 @@ the bound plus an escalation — never an unbounded loop.
 
 ### PR review/fix loop
 
-1. Each round — the first and every one after a fix — is `keryx review start` on the PR's current head, then `review-orchestrator` from that package. `review start` finds the previous round itself (local package, git history, the PR's round block, the flow package) and, when the previous reviewed head is an ancestor, reviews the delta: fix changes with a small roster (logic, regression, the findings' authors, the verifier) and the prior findings attached, new changes as round 1, unchanged code carried with its dispositions. Never pass a whole-branch range or `--all` per round; `<package>/round.json` records the round, its source and its mode.
-2. If findings or required check failures remain, run a fix round under Phase 3 step 6 (flow fix task, `task-implementer`), push the fix, and run the next round as in step 1.
+1. Each round — the first and every one after a fix — is `keryx review start` on the PR's current head, then `review-orchestrator` from that package. `review start` finds the previous round itself (local package, git history, the PR's round block, the flow package) and, when the previous reviewed head is an ancestor, reviews the delta: fix changes with a small roster (logic, regression, the findings' authors, security-code when a security finding is attached, the content roles of the fix lines themselves, the verifier) and the prior findings attached, new changes as round 1, unchanged code carried with its dispositions. Never pass a whole-branch range or `--all` per round; `<package>/round.json` records the round, its source and its mode.
+2. If findings (held ones aside: Phase 3 step 6) or required check failures remain, run a fix round under Phase 3 step 6 (flow fix task, `task-implementer`), push the fix, and run the next round as in step 1.
 
    **A required check failure is not automatically a fix task.** When `review.jev.ci_triage` is on, run `keryx review ci-triage --run <id> --json` on each failed run first: `top: flaky` (or a `deterministic` override) → rerun once (`gh run rerun --failed <id>`), record it in `journal.md`, and treat a second failure as `real-regression` regardless; `top: real-regression` → investigate and fix as usual; `top: infra` → report it in the completion notes and leave the code alone. The verdict is advisory only — never the sole reason to skip a fix task.
 
-   **The threshold is `minor`.** The loop exits when the round reports zero
-   findings at `blocker`, `major` or `minor`; `info` does not hold it. State the
-   remaining `info` findings in the completion report rather than fixing them
-   under a loop that was not opened for them. A caller may lower the threshold in
-   `constraints`; it cannot raise it to merge over a `minor`.
+   **The threshold is `minor`.** The loop exits when the round reports zero findings at `blocker`, `major` or `minor` that are not held, and no held finding awaits the operator; `info` does not hold it. A held finding counts as neither fixable nor clean: while one is unanswered, run no fix round for it and stop to ask (unattended: stop and report the held list). State the remaining `info` findings in the completion report rather than fixing them under a loop that was not opened for them. A caller may lower the threshold in `constraints`; it cannot raise it to merge over a `minor`.
 3. Allow at most **five** review/fix attempts for the current approach. Count
    an attempt when review/check results are available, including a clean result,
    and record it with `keryx flow task attempt <id> <Tn> --outcome ...` so the
@@ -686,6 +676,7 @@ Stop and re-read this skill if you are thinking:
 | "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` runs inline in this same main session, where keryx cannot see the in-flight subagents; declare them with `--outstanding`. Skipping the check means the cap bounds nothing. |
 | "The reviewer wrote the fix; applying it is the fastest close." | A `suggested_fix` is a hypothesis. Most majors in a long fix loop are introduced by fixes: reproduce the finding red, check the suggestion against the state × event matrix, then fix (Phase 3 step 6). |
+| "The finding came from a review, so its premise is settled." | A finding can reproduce and still not be a defect. Never pass a held finding in `fix_context.review_feedback`; ask the operator as `review-orchestrator` "Wave D" says (Phase 3 step 6); a flow sourced from a finding runs `review-premise` before freeze (Phase 1). |
 | "While I'm in this code, the fix round can also harden the empty state." | Scope freeze: a fix round fixes findings. New hardening is an operator decision at the first-green gate or as an explicit question, never silent growth. |
 | "The implementer journaled its UX choice, so it is decided." | A `behavior_changes` entry with `needs_operator: true` is decided by the operator, asked with options before the result is accepted (Phase 2). A journal line decides nothing. |
 | "I'll set the verification kind later." | An `unclassified` criterion cannot become data afterwards without a recorded rewrite: `keryx flow ac update <id> --criterion ACn --text "…" --reason "<why>"`. Put the `[verify: …]` marker on every criterion before `flow freeze`. |

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

@@ -0,0 +1,70 @@
+# Job Orchestrator - Reference Detail
+
+Reference material moved out of `SKILL.md` to keep it within its length ceiling:
+rationale, evidence and long examples. Nothing here is an instruction the agent must
+follow at a step; each section is linked from the spot in `SKILL.md` that used it.
+
+## Dry-run plan output example
+
+```
+Dry-run plan for: issue-4141--pipeline-validation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Step 1: analyze          [issue-analyzer]           → input: issue #4141
+Step 2: context          [context-collector]        → input: analysis result, project_dir
+Step 3: prepare          [orchestrator]             → creates: feature/pipeline-validation worktree
+Step 4: tests-creator    [tests-creator × 3]        → RED stubs, one per task
+Step 5: implement        [task-implementer × 3]     → wave-parallel, 3 tasks
+Step 6: sanity-check     [orchestrator]             → verifies commits exist
+Step 7: verify           [code-verifier]            → lint + type-check + test + imports
+Step 8: review           [review-orchestrator]      → managed round, ingested
+Step 9: security         [security-audit]           → conditional: auth/API/DB/env files
+Step 10: fix             [task-implementer]         → conditional: if NEEDS_FIX
+Step 11: verify-post-fix [code-verifier]            → conditional: after fix
+Step 12: perf-check      [perf-check]               → conditional: frontend/bundle files
+Step 13: report          [orchestrator]             → aggregates all results
+Step 14: pr              [orchestrator + gh CLI]    → conditional: if create_pr
+Step 15: deploy          [deploy]                   → conditional: if user asks
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Estimated sub-agent calls: 11-14 (varies with tasks and review findings)
+No changes will be made. Use without --dry-run to execute.
+```
+
+## Post-mortem document template
+
+```markdown
+# Post-Mortem: <job-name>
+
+## Timeline
+(from .metaproject/jobs/<job-name>/journal.md — every line as recorded)
+- <ISO timestamp> - created
+- <ISO timestamp> - step: implement in-progress (retries 0)
+- <ISO timestamp> - step: implement in-progress (retries 1)
+- <ISO timestamp> - step: implement failed (retries 1) — <reason>
+
+## What Went Wrong
+- <Step name> failed with: <error class> — <error message>
+- Recorded retries: <metrics.steps[].retries>
+- Root cause hypothesis: <analysis>
+
+## What Worked
+- <N> tasks completed successfully
+- Context collection was accurate
+
+## Recommendations for Retry
+- Fix <specific issue> before re-running
+- Consider splitting task-3 into smaller subtasks
+```
+
+## Metrics table in the report
+
+**Aggregated in the report:**
+```markdown
+## Metrics
+| Step | Duration | Retries |
+|------|----------|---------|
+| Analyze | 45s | 0 |
+| Context | 30s | 0 |
+| Implement | 5m 22s | 1 |
+| Review | 1m 10s | 0 |
+| **Total** | **7m 47s** | **1** |
+```

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

@@ -989,7 +989,7 @@ transcript and nothing else, which is precisely the failure the managed pipeline
 replaced.
 
 A pull request driven by this orchestrator has to pass the completion gate shipped in
-0.2.71. Its five conditions are what 2.6 and 2.7 are built to satisfy:
+0.2.71. Its conditions are what 2.6 and 2.7 are built to satisfy:
 
 | Gate condition | Satisfied by |
 |---|---|
@@ -998,6 +998,7 @@ A pull request driven by this orchestrator has to pass the completion gate shipp
 | scope B is recorded when a scope-B reviewer ran | `keryx review blast-radius --json` → `review ingest --blast-radius` (2.6.1) |
 | no inbound PR comment is unanswered | `keryx review comments collect` every round, `… reply --final` once (2.6.2) |
 | verification stats exist | `review-verifier` dispatched, passed as `--verifications` (2.6.1) |
+| no held finding lacks an operator decision | `review-premise` (Wave D) claims passed as `--premises`; each held finding asked as `review-orchestrator` "Wave D" says (2.6.1) |
 
 #### 2.6.0 Review Scope Selection
 
@@ -1134,15 +1135,17 @@ is_fix_round:      <true on any round after the first; the round, its range and
 pr_comments:       { enabled: <true when a PR exists> }
 ```
 
-It emits the unified report AND the fenced ```json keryx:findings``` block, and runs
-`review-verifier` (Wave C) over the consolidated findings, returning its verification
-claims as a file path.
+It emits the unified report AND the fenced ```json keryx:findings``` block, runs
+`review-verifier` (Wave C) and then `review-premise` (Wave D) over the consolidated
+findings, and returns the verification claims and the premise claims as file paths.
 
-**Step 7 — verification is part of the round, not an extra.** `review-orchestrator`
-dispatches `review-verifier` in Wave C over the consolidated findings. The verifier
-**runs something** and can only delete — it never raises a severity, adds a finding,
-or rewrites one, and it never verifies a finding raised by the same reviewer. Its
-claims are merged by the CLI, not by hand.
+**Step 7 — verification and the premise check are part of the round, not extras.**
+`review-orchestrator` dispatches `review-verifier` in Wave C over the consolidated
+findings. The verifier **runs something** and can only delete — it never raises a
+severity, adds a finding, or rewrites one, and it never verifies a finding raised by the
+same reviewer. After it, `review-premise` (Wave D) judges whether each finding is a
+defect at all: it can lower a severity or hold a finding for the operator, never add
+one. Both claim sets are merged by the CLI, not by hand.
 
 **Step 8 — ingest the round.** This is what makes it citable.
 
@@ -1152,13 +1155,14 @@ keryx review ingest --report <path/to/review-report.md> --ref <feature-branch> \
   --scope <JOBS_ROOT>/<job-name>/scope.json \
   --blast-radius <JOBS_ROOT>/<job-name>/blast-radius.json \
   --verifications <path/to/verifications.json> --verification-mode annotate \
-  --refuted <path/to/refuted.json> \
+  --premises <path/to/premises.json> --refuted <path/to/refuted.json> \
   --spent <usd-so-far> --outstanding <subagents in flight>
 ```
 
 An unrecognised option is **refused, not ignored** — a silently dropped flag writes
 nothing and still reports success. `--refuted` carries findings this round raised and
 then dismissed; without it the package keeps only the survivors of an unlogged triage.
+A first ingest without `--premises` holds nothing; a re-ingest carries earlier holds.
 
 **Findings are the canonical shape.** One vocabulary, everywhere in this skill:
 
@@ -1174,9 +1178,18 @@ then dismissed; without it the package keeps only the survivors of an unlogged t
 
 **Classify:**
 ```
-NEEDS_FIX = count(blocker) > 0 OR count(major) > 0
+HELD      = findings review-premise holds (challenged / owner-decision) with no operator decision
+OPEN      = blocker + major findings not in HELD
+NEEDS_FIX = count(OPEN) > 0
 ```
 
+A HELD finding is neither fixable nor clean: it never enters a fix prompt, and it blocks
+the job until answered. Ask the operator about each one as `review-orchestrator` "Wave
+D" says; an upheld one rejoins OPEN at its severity (carrying `premise_verdict` and
+`premise_answer` as task-implementer's `FIX_CONTEXT` defines them), a dismissed one
+carries `dismissed-incorrect` from the operator's decision. Unattended: stop and report
+the HELD list; never let the loop end reading clean while HELD is non-empty.
+
 **Document:** record the report in the job package too, so the job and the review
 record point at each other:
 
@@ -1276,7 +1289,7 @@ still reported — so a finding the next reviewer simply did not look at was rec
 fixed. That is absence-as-evidence, and the completion gate refuses it.
 
 ```
-UNRESOLVED_FINDINGS = all blocker + major findings from step 2.6
+UNRESOLVED_FINDINGS = OPEN from step 2.6          # never a HELD finding (Classify, 2.6.1)
 PREVIOUS_REVIEW_OUTPUT = <the ingested report from step 2.6>
 
 FOR iteration in [1, 2, 3]:
@@ -1305,8 +1318,8 @@ FOR iteration in [1, 2, 3]:
        <run review-orchestrator inline, in this session; it takes the round from round.json>
        keryx review ingest  --report <new-report> --ref <feature-branch> --head <new-head> \
                             --scope scope.json --blast-radius blast-radius.json \
-                            --verifications <file> --refuted <file> --outstanding <n>
-  6. Recompute NEEDS_FIX from the ingested findings
+                            --verifications <file> --premises <file> --refuted <file> --outstanding <n>
+  6. Recompute HELD, OPEN and NEEDS_FIX from the ingested findings; a new HELD finding is asked about as in Classify
   7. Record what became of each finding raised in the PREVIOUS round — every one of
      them, before the next iteration starts:
 
@@ -1320,9 +1333,8 @@ FOR iteration in [1, 2, 3]:
      must cite where the outcome is written down. A recorded state and its citation
      cannot be overwritten by a later close — record a correction as a new round.
      Closing with no dispositions leaves every finding reading `unknown`, which means
-     "nobody wrote down what happened".
-  8. UNRESOLVED_FINDINGS = the blocker + major findings of the NEW round that are
-     still without a terminal disposition
+     "nobody wrote down what happened". A HELD finding gets no disposition here: it waits for the operator.
+  8. UNRESOLVED_FINDINGS = the OPEN findings of the NEW round still without a terminal disposition
 
   9. STUCK CHECK — runs before the next iteration and ignores the budget:
      IF any finding identity is in UNRESOLVED_FINDINGS for the SECOND iteration
@@ -1351,6 +1363,8 @@ IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
   steps. Give every surviving finding a disposition (dismissed-wont-fix or
   dismissed-deprioritised, with evidence) rather than leaving it `unknown`
   → continue to VERIFY (2.8)
+
+IF HELD is non-empty when the loop ends: ask the operator (Classify); unattended, stop and report the HELD list
 ```
 
 `comments reply` **refuses without `--final`**: replying per round turns one review
@@ -1936,28 +1950,8 @@ When `dry_run: true` is set (or `--dry-run` is passed):
 3. **Phase 2 is skipped entirely** — no sub-agents dispatched, no git operations
 4. **Output:** Full plan tree with agent names, input data shapes, dependencies:
 
-```
-Dry-run plan for: issue-4141--pipeline-validation
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Step 1: analyze          [issue-analyzer]           → input: issue #4141
-Step 2: context          [context-collector]        → input: analysis result, project_dir
-Step 3: prepare          [orchestrator]             → creates: feature/pipeline-validation worktree
-Step 4: tests-creator    [tests-creator × 3]        → RED stubs, one per task
-Step 5: implement        [task-implementer × 3]     → wave-parallel, 3 tasks
-Step 6: sanity-check     [orchestrator]             → verifies commits exist
-Step 7: verify           [code-verifier]            → lint + type-check + test + imports
-Step 8: review           [review-orchestrator]      → managed round, ingested
-Step 9: security         [security-audit]           → conditional: auth/API/DB/env files
-Step 10: fix             [task-implementer]         → conditional: if NEEDS_FIX
-Step 11: verify-post-fix [code-verifier]            → conditional: after fix
-Step 12: perf-check      [perf-check]               → conditional: frontend/bundle files
-Step 13: report          [orchestrator]             → aggregates all results
-Step 14: pr              [orchestrator + gh CLI]    → conditional: if create_pr
-Step 15: deploy          [deploy]                   → conditional: if user asks
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Estimated sub-agent calls: 11-14 (varies with tasks and review findings)
-No changes will be made. Use without --dry-run to execute.
-```
+The full plan tree (agent names, input shapes, dependencies, no changes made):
+`SKILL.detail.md`, "Dry-run plan output example".
 
 5. Ask user: "Execute this plan? (yes / adjust / abort)"
 
@@ -2158,29 +2152,7 @@ When a job ends with a step recorded `failed`, or with unresolved blocker findin
    off `journal.md`, which `keryx job` timestamped as the job ran, and the retry counts
    come from `keryx job status <job-name> --json`:
 
-```markdown
-# Post-Mortem: <job-name>
-
-## Timeline
-(from .metaproject/jobs/<job-name>/journal.md — every line as recorded)
-- <ISO timestamp> - created
-- <ISO timestamp> - step: implement in-progress (retries 0)
-- <ISO timestamp> - step: implement in-progress (retries 1)
-- <ISO timestamp> - step: implement failed (retries 1) — <reason>
-
-## What Went Wrong
-- <Step name> failed with: <error class> — <error message>
-- Recorded retries: <metrics.steps[].retries>
-- Root cause hypothesis: <analysis>
-
-## What Worked
-- <N> tasks completed successfully
-- Context collection was accurate
-
-## Recommendations for Retry
-- Fix <specific issue> before re-running
-- Consider splitting task-3 into smaller subtasks
-```
+Use the template in `SKILL.detail.md`, "Post-mortem document template".
 
 2. Save to `.metaproject/jobs/<job-name>/post-mortem.md`
 3. Include in final user message: "Post-mortem saved to `.metaproject/jobs/<job-name>/post-mortem.md`"
@@ -2220,16 +2192,7 @@ terminal disposition.
 keryx job status <job-name> --json     # `retries` per step, plus phase and next_step
 ```
 
-**Aggregated in the report:**
-```markdown
-## Metrics
-| Step | Duration | Retries |
-|------|----------|---------|
-| Analyze | 45s | 0 |
-| Context | 30s | 0 |
-| Implement | 5m 22s | 1 |
-| Review | 1m 10s | 0 |
-| **Total** | **7m 47s** | **1** |
-```
+**Aggregated in the report:** a per-step Duration/Retries table with a total row
+(`SKILL.detail.md`, "Metrics table in the report").
 
 This data identifies which steps are bottlenecks and which ones needed a second attempt.

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

@@ -98,7 +98,7 @@ For a description-based task, omit `issue_number` and issue references in commit
 
 ```
 FIX_CONTEXT:
-  review_feedback:      structured findings from reviewer (id, file, line, severity, message, suggested_fix)
+  review_feedback:      structured findings from reviewer (id, file, line, severity, message, suggested_fix); the one statement of the premise fields (flow 459): `premise_verdict` on each item review-premise judged, and `premise_answer: "uphold"` on a held one (challenged, owner-decision) the operator upheld; an item with a held `premise_verdict` and no `premise_answer: "uphold"` is refused, not fixed
   original_task_ids:    the tasks that introduced the findings (array)
   iteration:            fix iteration number, 1..3 — the same repair bound as 5.4
 ```

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

@@ -178,10 +178,25 @@
                 "type": "string",
                 "description": "Which review skill found this",
                 "examples": ["code-ai-review", "code-learned-review", "code-style-review"]
+              },
+              "premise_verdict": {
+                "type": "string",
+                "enum": ["upheld", "downgraded", "challenged", "owner-decision"],
+                "description": "What review-premise found, when it judged this finding (flow 459). `challenged` and `owner-decision` HOLD the finding: such an item is valid only with `premise_answer: uphold`, so a held finding that reached a fixer without the operator's answer fails this contract instead of being fixed."
+              },
+              "premise_answer": {
+                "type": "string",
+                "enum": ["uphold"],
+                "description": "The operator's answer to a held finding, recorded with `keryx review decide-premise` (or the `review_decide_premise` card). Only `uphold` returns a finding to the fix; a dismissed one is never dispatched."
               }
-            }
+            },
+            "if": {
+              "required": ["premise_verdict"],
+              "properties": { "premise_verdict": { "enum": ["challenged", "owner-decision"] } }
+            },
+            "then": { "required": ["premise_answer"] }
           },
-          "description": "Structured findings from review skills"
+          "description": "Structured findings from review skills, to fix. Never carries a finding held by review-premise (verdict challenged or owner-decision) until the operator upholds it with `keryx review decide-premise`; the caller filters held findings out before dispatch, and an item that names a held verdict without `premise_answer: uphold` is refused by this contract."
         },
         "original_task_ids": {
           "type": "array",

package/src/gdskills/bundled/skills/review/review-architecture/SKILL.md

@@ -26,7 +26,7 @@ license: "MIT"
 
 Specialized reviewer for **architectural patterns and structural decisions**.
 Reviews only changes introduced in the current branch (merge-base to HEAD).
-Focuses exclusively on verifiable structural violations — not style opinions or hypothetical concerns. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+Focuses exclusively on verifiable structural violations — not style opinions or hypothetical concerns. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ---
 
@@ -66,7 +66,7 @@ See shared script: `.metaproject/skills/gdskills/shared/git-merge-base.md`
 Review scope: **changes introduced in the current branch since merge-base only**.
 Do not review pre-existing architectural problems unless they are directly touched by the diff.
 
-**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text: a read-only child has no shell, so run no git command and never rebuild the diff. Only with none supplied, collect it:
+**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text and never rebuild the diff. A choice's history (law 4) is read with `git log`, `git blame` and `git show` only where the host gives a read-only child git; on keryx shell a read-only child has no shell and no git tool, so read the `git log -L`/`git blame` excerpts the payload supplies, or say the history was not read. Only with none supplied, collect it:
 ```bash
 git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files --others --exclude-standard
 # explicit range: <FROM_SHA>..<TO_SHA> in place of "${BASE_SHA}"
@@ -269,15 +269,10 @@ if the concern is purely readability it belongs to `review-style`.
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the

package/src/gdskills/bundled/skills/review/review-backend/SKILL.md

@@ -26,7 +26,7 @@ license: "MIT"
 
 Focused backend reviewer covering NestJS patterns, REST API design, database access patterns,
 and TypeScript correctness for service-layer code. This skill does NOT duplicate security or
-performance checks — those belong to `review-security-code` and `review-performance`. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+performance checks — those belong to `review-security-code` and `review-performance`. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ---
 
@@ -65,7 +65,7 @@ Run that script to determine `BASE_SHA` before collecting the diff.
 
 Only review files changed in scope. Do not comment on legacy code outside the diff.
 
-**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text: a read-only child has no shell, so run no git command and never rebuild the diff. Only with none supplied, collect it:
+**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text and never rebuild the diff. A choice's history (law 4) is read with `git log`, `git blame` and `git show` only where the host gives a read-only child git; on keryx shell a read-only child has no shell and no git tool, so read the `git log -L`/`git blame` excerpts the payload supplies, or say the history was not read. Only with none supplied, collect it:
 ```bash
 git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files --others --exclude-standard
 # explicit range: <FROM_SHA>..<TO_SHA> in place of "${BASE_SHA}"
@@ -187,15 +187,10 @@ git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files -
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the

package/src/gdskills/bundled/skills/review/review-clean-code/SKILL.md

@@ -27,7 +27,7 @@ license: "MIT"
 # Review: Clean Code + SOLID
 
 Specialized reviewer for **Clean Code principles** (Robert C. Martin) and **SOLID** at the
-function and class level. Focuses on code in the current branch diff only. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+function and class level. Focuses on code in the current branch diff only. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 The goal is not stylistic nitpicking — every finding here points to a concrete
 maintainability, readability, or extensibility problem that will cause friction
@@ -71,7 +71,7 @@ Review scope: **only code introduced or modified in this branch since merge-base
 Pre-existing problems in unchanged lines are out of scope unless a change directly
 worsens them.
 
-**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text: a read-only child has no shell, so run no git command and never rebuild the diff. Only with none supplied, collect it:
+**Supplied text first.** When the payload carries `slices`, `context_files`, `diff` or `file_contents`, review exactly that text and never rebuild the diff. A choice's history (law 4) is read with `git log`, `git blame` and `git show` only where the host gives a read-only child git; on keryx shell a read-only child has no shell and no git tool, so read the `git log -L`/`git blame` excerpts the payload supplies, or say the history was not read. Only with none supplied, collect it:
 ```bash
 git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files --others --exclude-standard
 # explicit range: <FROM_SHA>..<TO_SHA> in place of "${BASE_SHA}"
@@ -83,15 +83,10 @@ git diff --name-status "${BASE_SHA}" && git diff "${BASE_SHA}" && git ls-files -
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the

package/src/gdskills/bundled/skills/review/review-core-boundaries/SKILL.md

@@ -24,7 +24,7 @@ license: "MIT"
 # Review — Core Boundaries
 
 Reviewer for shared infrastructure modules. A core module should provide stable foundations
-used by feature modules; it should not accumulate feature-specific behaviour. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`.
+used by feature modules; it should not accumulate feature-specific behaviour. Its inputs are the reviewer payload only; session memory and earlier conversation are not inputs. It runs no command unless its payload's `allowed_tools` says `run-tests`, except the read-only `git log`, `git blame` and `git show` where its host gives a read-only child git (keryx shell does not: there the payload supplies the history).
 
 ---
 
@@ -58,15 +58,10 @@ If a more specific module reviewer also applies, run both.
 
 ### Shared laws (every reviewer)
 
-1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
-   name the input, call, or condition that reaches the code, you have an
-   observation, not a finding. Report it as `info` and say what would settle it.
-2. **Never flag the theoretical.** The path you describe must exist in the code
-   under review. Do not report a safe API because it could be misused, or a
-   pattern because it is often wrong elsewhere.
-3. **One finding per class, not one per occurrence.** When the same shape appears
-   at several sites, report it once and list every site. Ten findings that are one
-   finding hide the other nine problems.
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot name the input, call, or condition that reaches the code, you have an observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code under review. Do not report a safe API because it could be misused, or a pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears at several sites, report it once and list every site. Ten findings that are one finding hide the other nine problems.
+4. **A deliberate choice is not a defect until its reason is read and shown wrong.** An explicit override, suppression or exemption, a comment or commit giving a reason, or a sibling doing the same is a decision: read its reason (the comment, `git log -L` or `git blame`, the sibling) before you report it, and report it only when you can show that reason wrong. A project rule is checked against accepted platform practice and its known exceptions before a deviation from it is reported.
 
 Severity levels are defined once, in `review-orchestrator/SKILL.md` →
 **Severity (canonical)**. This reviewer does not restate them: `blocker` is the