@mrciphersmith/keryx 0.2.72 → 0.2.74

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

@@ -308,7 +308,7 @@ FOCUS AREA:
 ```javascript
 Task({
   description: "Feature analysis: pipeline-variables",
-  subagent_type: "general",
+  subagent_type: "general-purpose",
   prompt: "<сгенерированный промпт выше>"
 })
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: feature-dev
-description: "7-phase feature development workflow: requirements → design → implement → test → review → fix → PR. Full cycle from idea or GitHub issue to merge-ready PR. Confirms requirements and design with user before autonomous execution."
+description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow."
 triggers:
   - "/feature-dev"
   - "Develop feature"
@@ -9,12 +9,18 @@ triggers:
   - "Feature from scratch"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "2.0.0"
   category: "workflow"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for interactive feature development sessions only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Feature Development (7-Phase)
 
 End-to-end feature development workflow from idea to merge-ready PR.
@@ -25,66 +31,104 @@ End-to-end feature development workflow from idea to merge-ready PR.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 
-## 7-Phase Architecture
+## 8-Phase Architecture
+
+> **Rules always loaded:** `tdd-workflow.mdc`, `implementation-doc-mandate.mdc`, `error-handling.mdc`
+> **Sub-agents used:** `tests-creator` (before implement), `code-verifier` (after implement)
+
+### Phase 1: REQUIREMENTS + SPEC
 
-### Phase 1: REQUIREMENTS
 1. Parse input (description or GitHub issue via `gh issue view`)
 2. Clarify ambiguities — ask the user up to 3 questions max
-3. Produce a brief spec:
+3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
    - **Why**: user value / business reason
    - **Scope**: what's in, what's explicitly out
    - **Acceptance criteria**: testable bullet points
-4. **Get user confirmation before proceeding**
+   - **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**
 
 ### Phase 2: DESIGN
+
 1. Research the codebase:
    - Find related modules via search tools
    - Read neighboring implementations for patterns
-   - Check existing tests for testing conventions
+   - **Detect test framework** (package.json, existing test files) — needed for tests-creator
 2. Produce implementation plan:
    - Files to create/modify (with brief description of changes)
    - Dependencies or packages needed
    - Data model changes if any
    - Estimated complexity: S / M / L
-3. **Get user confirmation on the plan**
+3. Load relevant rules from `.metaproject/rules/core/` based on what will be built:
+   - Always: `tdd-workflow.mdc`, `error-handling.mdc`, `solid-principles.mdc`
+   - API/service code: `api-contracts.mdc`, `clean-architecture.mdc`
+   - Database: `database-patterns.mdc`
+   - Async: `async-patterns.mdc`
+   - Security-sensitive: `security-baseline.mdc`
+4. **Get user confirmation on the plan**
 
 ### Phase 3: PREPARE
-1. Create a feature branch: `git checkout -b feat/<name>`
-2. If large feature, consider `git worktree add` for isolation
-3. Install any new dependencies
-
-### Phase 4: IMPLEMENT
-1. Implement changes file by file, following the plan
-2. Follow existing code patterns discovered in Phase 2
-3. After each logical chunk, run available checks:
-   - Lint: `npm run lint` or equivalent
-   - Type-check: `npx tsc --noEmit` or equivalent
-   - Fix issues immediately before moving on
-
-### Phase 5: TEST
-1. Write tests matching the project's testing patterns
-2. Unit tests for new functions/modules
-3. Integration tests for API/data flow changes
-4. Run full test suite
-5. Fix failing tests (max 3 attempts per test)
-
-### Phase 6: REVIEW (Self)
+
+1. Create a feature branch: `wt switch -c feat/<name>`
+2. Install any new dependencies
+
+### Phase 4: TESTS-CREATOR (TDD — RED phase)
+
+**Run before writing any implementation code.**
+
+1. For each group of acceptance criteria, invoke `tests-creator`:
+   - Input: acceptance criteria from Phase 1 spec + target files from Phase 2 plan
+   - tests-creator detects framework and generates failing test stubs
+   - tests-creator commits the stubs and verifies RED state
+2. Confirm test stubs are in place and failing before proceeding to Phase 5
+
+### Phase 5: IMPLEMENT (TDD — GREEN phase)
+
+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)
+5. Commit with conventional message after each logical chunk
+
+### Phase 6: VERIFY (code-verifier gate)
+
+Run `code-verifier` on the full diff:
+
+```
+Invoke: skills/orchestration/code-verifier/SKILL.md
+Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
+```
+
+- `gate: PASS` → proceed to Phase 7
+- `gate: FAIL` → fix findings, re-run code-verifier (max 2 cycles)
+- Still FAIL after 2 cycles → report blocker to user, stop
+
+### Phase 7: REVIEW (Self)
+
 1. Launch the `review-orchestrator` skill on own changes
 2. Or run a focused self-review:
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
-   - Verify all acceptance criteria from Phase 1
+   - Verify all acceptance criteria from Phase 1 spec
 3. Fix any findings (max 2 review-fix cycles)
+4. Re-run `code-verifier` after any fixes
+
+### Phase 8: DELIVER + CHANGE REPORT
 
-### Phase 7: DELIVER
-1. Final checks: lint + type-check + tests all pass
-2. Commit with conventional message: `feat(<scope>): <description>`
-3. Push branch
-4. Create PR:
+1. Push branch
+2. Create PR:
    - Link to issue if applicable
-   - Include acceptance criteria as checklist
-   - Add test plan
+   - Include acceptance criteria checklist
+   - Add test plan and code-verifier results
+3. **Produce Change Report** (per `implementation-doc-mandate.mdc`):
+   - Files created/modified with descriptions
+   - Test count and results
+   - code-verifier gate result
+   - Acceptance criteria checklist (checked off)
+   - Commits list
+4. Print Change Report to user
 5. Report PR URL to user
 
 ## Status Updates
@@ -97,9 +141,25 @@ At each phase transition, report progress:
 
 ## Rules
 
-- ALWAYS get user confirmation after Phase 1 (requirements) and Phase 2 (design)
-- Phases 4-6 are autonomous — no user interaction needed
+- ALWAYS get user confirmation after Phase 1 (requirements + spec) and Phase 2 (design)
+- Phases 4-7 are autonomous — no user interaction needed
 - If stuck for >3 attempts on any step, report the blocker and ask user
-- NEVER skip Phase 5 (testing) even if user says "skip tests"
-- NEVER commit broken code (lint/type-check must pass)
-- Keep commits atomic: one commit per logical change, not one giant commit
+- NEVER skip Phase 4 (tests-creator) even if user says "skip tests" — this is TDD, not optional testing
+- NEVER skip Phase 6 (code-verifier) — it is the quality gate, not a suggestion
+- NEVER commit broken code (code-verifier gate must pass before PR)
+- Keep commits atomic: one commit per logical chunk, not one giant commit
+- ALWAYS produce the Change Report in Phase 8 — even if the PR was not created
+
+## Red Flags — Stop and re-read this skill if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Requirements are clear enough, I'll skip the design phase" | Skipping design means discovering mismatches after code is written, not before |
+| "The user already approved this approach verbally, no need to document" | Undocumented approval is invisible to reviewers and future agents; it doesn't exist |
+| "Tests can be written after — implementation first to check if the approach works" | Writing tests after implementation makes you test what you built, not what was required |
+| "This phase isn't needed for such a straightforward feature" | Every skipped phase is a deferred bug report |
+| "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 |
+
+**IRON LAW 1: NEVER START IMPLEMENTING BEFORE THE SPEC IS WRITTEN AND CONFIRMED.**
+**IRON LAW 2: NEVER WRITE IMPLEMENTATION CODE BEFORE TESTS-CREATOR HAS GENERATED FAILING STUBS.**
+**IRON LAW 3: NEVER DELIVER WITHOUT A PASSING CODE-VERIFIER GATE AND A CHANGE REPORT.**

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

@@ -1,6 +1,6 @@
 ---
 name: feature-dev
-description: "7-phase feature development workflow: requirements → design → implement → test → review → fix → PR. Full cycle from idea or GitHub issue to merge-ready PR. Confirms requirements and design with user before autonomous execution."
+description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow."
 triggers:
   - "/feature-dev"
   - "Develop feature"
@@ -9,12 +9,18 @@ triggers:
   - "Feature from scratch"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "2.0.0"
   category: "workflow"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for interactive feature development sessions only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Feature Development (7-Phase)
 
 End-to-end feature development workflow from idea to merge-ready PR.
@@ -25,66 +31,104 @@ End-to-end feature development workflow from idea to merge-ready PR.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 
-## 7-Phase Architecture
+## 8-Phase Architecture
+
+> **Rules always loaded:** `tdd-workflow.mdc`, `implementation-doc-mandate.mdc`, `error-handling.mdc`
+> **Sub-agents used:** `tests-creator` (before implement), `code-verifier` (after implement)
+
+### Phase 1: REQUIREMENTS + SPEC
 
-### Phase 1: REQUIREMENTS
 1. Parse input (description or GitHub issue via `gh issue view`)
 2. Clarify ambiguities — ask the user up to 3 questions max
-3. Produce a brief spec:
+3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
    - **Why**: user value / business reason
    - **Scope**: what's in, what's explicitly out
    - **Acceptance criteria**: testable bullet points
-4. **Get user confirmation before proceeding**
+   - **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**
 
 ### Phase 2: DESIGN
+
 1. Research the codebase:
    - Find related modules via search tools
    - Read neighboring implementations for patterns
-   - Check existing tests for testing conventions
+   - **Detect test framework** (package.json, existing test files) — needed for tests-creator
 2. Produce implementation plan:
    - Files to create/modify (with brief description of changes)
    - Dependencies or packages needed
    - Data model changes if any
    - Estimated complexity: S / M / L
-3. **Get user confirmation on the plan**
+3. Load relevant rules from `.metaproject/rules/core/` based on what will be built:
+   - Always: `tdd-workflow.mdc`, `error-handling.mdc`, `solid-principles.mdc`
+   - API/service code: `api-contracts.mdc`, `clean-architecture.mdc`
+   - Database: `database-patterns.mdc`
+   - Async: `async-patterns.mdc`
+   - Security-sensitive: `security-baseline.mdc`
+4. **Get user confirmation on the plan**
 
 ### Phase 3: PREPARE
-1. Create a feature branch: `git checkout -b feat/<name>`
-2. If large feature, consider `git worktree add` for isolation
-3. Install any new dependencies
-
-### Phase 4: IMPLEMENT
-1. Implement changes file by file, following the plan
-2. Follow existing code patterns discovered in Phase 2
-3. After each logical chunk, run available checks:
-   - Lint: `npm run lint` or equivalent
-   - Type-check: `npx tsc --noEmit` or equivalent
-   - Fix issues immediately before moving on
-
-### Phase 5: TEST
-1. Write tests matching the project's testing patterns
-2. Unit tests for new functions/modules
-3. Integration tests for API/data flow changes
-4. Run full test suite
-5. Fix failing tests (max 3 attempts per test)
-
-### Phase 6: REVIEW (Self)
+
+1. Create a feature branch: `wt switch -c feat/<name>`
+2. Install any new dependencies
+
+### Phase 4: TESTS-CREATOR (TDD — RED phase)
+
+**Run before writing any implementation code.**
+
+1. For each group of acceptance criteria, invoke `tests-creator`:
+   - Input: acceptance criteria from Phase 1 spec + target files from Phase 2 plan
+   - tests-creator detects framework and generates failing test stubs
+   - tests-creator commits the stubs and verifies RED state
+2. Confirm test stubs are in place and failing before proceeding to Phase 5
+
+### Phase 5: IMPLEMENT (TDD — GREEN phase)
+
+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)
+5. Commit with conventional message after each logical chunk
+
+### Phase 6: VERIFY (code-verifier gate)
+
+Run `code-verifier` on the full diff:
+
+```
+Invoke: skills/orchestration/code-verifier/SKILL.md
+Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
+```
+
+- `gate: PASS` → proceed to Phase 7
+- `gate: FAIL` → fix findings, re-run code-verifier (max 2 cycles)
+- Still FAIL after 2 cycles → report blocker to user, stop
+
+### Phase 7: REVIEW (Self)
+
 1. Launch the `review-orchestrator` skill on own changes
 2. Or run a focused self-review:
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
-   - Verify all acceptance criteria from Phase 1
+   - Verify all acceptance criteria from Phase 1 spec
 3. Fix any findings (max 2 review-fix cycles)
+4. Re-run `code-verifier` after any fixes
+
+### Phase 8: DELIVER + CHANGE REPORT
 
-### Phase 7: DELIVER
-1. Final checks: lint + type-check + tests all pass
-2. Commit with conventional message: `feat(<scope>): <description>`
-3. Push branch
-4. Create PR:
+1. Push branch
+2. Create PR:
    - Link to issue if applicable
-   - Include acceptance criteria as checklist
-   - Add test plan
+   - Include acceptance criteria checklist
+   - Add test plan and code-verifier results
+3. **Produce Change Report** (per `implementation-doc-mandate.mdc`):
+   - Files created/modified with descriptions
+   - Test count and results
+   - code-verifier gate result
+   - Acceptance criteria checklist (checked off)
+   - Commits list
+4. Print Change Report to user
 5. Report PR URL to user
 
 ## Status Updates
@@ -97,9 +141,25 @@ At each phase transition, report progress:
 
 ## Rules
 
-- ALWAYS get user confirmation after Phase 1 (requirements) and Phase 2 (design)
-- Phases 4-6 are autonomous — no user interaction needed
+- ALWAYS get user confirmation after Phase 1 (requirements + spec) and Phase 2 (design)
+- Phases 4-7 are autonomous — no user interaction needed
 - If stuck for >3 attempts on any step, report the blocker and ask user
-- NEVER skip Phase 5 (testing) even if user says "skip tests"
-- NEVER commit broken code (lint/type-check must pass)
-- Keep commits atomic: one commit per logical change, not one giant commit
+- NEVER skip Phase 4 (tests-creator) even if user says "skip tests" — this is TDD, not optional testing
+- NEVER skip Phase 6 (code-verifier) — it is the quality gate, not a suggestion
+- NEVER commit broken code (code-verifier gate must pass before PR)
+- Keep commits atomic: one commit per logical chunk, not one giant commit
+- ALWAYS produce the Change Report in Phase 8 — even if the PR was not created
+
+## Red Flags — Stop and re-read this skill if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Requirements are clear enough, I'll skip the design phase" | Skipping design means discovering mismatches after code is written, not before |
+| "The user already approved this approach verbally, no need to document" | Undocumented approval is invisible to reviewers and future agents; it doesn't exist |
+| "Tests can be written after — implementation first to check if the approach works" | Writing tests after implementation makes you test what you built, not what was required |
+| "This phase isn't needed for such a straightforward feature" | Every skipped phase is a deferred bug report |
+| "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 |
+
+**IRON LAW 1: NEVER START IMPLEMENTING BEFORE THE SPEC IS WRITTEN AND CONFIRMED.**
+**IRON LAW 2: NEVER WRITE IMPLEMENTATION CODE BEFORE TESTS-CREATOR HAS GENERATED FAILING STUBS.**
+**IRON LAW 3: NEVER DELIVER WITHOUT A PASSING CODE-VERIFIER GATE AND A CHANGE REPORT.**

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

@@ -12,7 +12,7 @@ triggers:
   - "managed implementation"
 metadata:
   author: "MrCipherSmith"
-  version: "1.3.0"
+  version: "1.4.0"
   category: "orchestration"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
@@ -418,12 +418,59 @@ How should this flow end?
   Preserve the base branch recorded during initialization. Do not mark the
   flow implemented or complete before the PR is merged into that branch.
 
+### A dispatched run answers the question from its input
+
+The choice above is the USER's, and a subagent has no user to ask. When this
+skill is dispatched by another skill the answer arrives in the input, and asking
+anyway is how a dispatched run stalls forever on a prompt nobody will read.
+
+Read it from the **typed fields**, and validate them first:
+
+```bash
+keryx skills contracts validate <dispatch.json> --schema flow-orchestrator-input
+```
+
+`base_branch`, `completion_outcome` and `operator_confirmed` are properties of
+that contract, not constraint strings. The distinction is the whole point:
+nothing parses `constraints[]`, so a load-bearing value misspelled there is
+dropped in silence and the run merges wherever it resolved a base on its own.
+`constraints[]` carries advisory scope and policy — never a merge target.
+
+`completion_outcome` is **required** by the contract, so an absent one is a
+refused dispatch rather than a question. That is deliberate: the previous rule
+here said "ask", prescribed fourteen lines after this section says asking is how
+a dispatched run stalls on a prompt nobody reads — and it left the
+`create-pr-and-merge` conditional reachable-around by simply omitting the field.
+A dispatched run that cannot name its outcome returns **BLOCKED** naming the
+missing field. Only an interactive run asks. Record in `journal.md` which field
+answered it and who is behind it.
+
+| Input | Obey it as |
+|---|---|
+| `base_branch` | Cut the flow branch from **that** branch and merge back into it. Never substitute the repository default: a fix aimed at a pull request's own branch has to land inside that pull request, and the default branch is a different review. Absent, resolve the base yourself and record what you resolved. |
+| `completion_outcome: create-pr-and-merge` | Skip the Completion Choice question, run the PR review/fix loop, merge into `base_branch`, complete the flow. |
+| `operator_confirmed` | The human decision behind an outward-facing completion. See the row below for when its absence is a refusal. |
+| `review: the caller owns the reply on #<n>` | Pass it through to every `review-orchestrator` dispatch. Reviews of **this flow's own** PR reply as normal — that is a separate conversation. What the round must not do is answer `#<n>`, which the caller is already answering. |
+| `attempt budget: at most <n> attempts` | A numeric ceiling BELOW your own bound is obeyed. One at or above it is not — the bound is yours, and the paragraph under this table says why. |
+| `completion: <anything>` as a constraint STRING | **Not an outcome. Refuse it and ask for the typed field.** `constraints[]` is parsed by nothing, so a completion arriving there is never read at all. Such a dispatch is now refused for the missing `completion_outcome` rather than silently accepted — but the refusal is the contract's, not this row's, and a row telling you to honour the string would be a documented bypass of the fence in the file that owns it. |
+
+A constraint that would raise this skill's own attempt budget is **not** obeyed.
+The three-attempt bound and the `keryx review loop` repetition check are this
+skill's, they are evidence-backed, and a caller asking for "loop until clean" gets
+the bound plus an escalation — never an unbounded loop.
+
 ### PR review/fix loop
 
 1. Run the relevant `review-orchestrator` checks against the PR and current
    branch state.
 2. If findings or required check failures remain, create or update a flow fix
    task, dispatch `task-implementer`, push the fix, and run review again.
+
+   **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`.
 3. Allow at most **three** 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

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/input-contract.schema.json

@@ -4,7 +4,10 @@
   "title": "FlowOrchestratorInput",
   "type": "object",
   "additionalProperties": false,
-  "required": ["request"],
+  "required": [
+    "request",
+    "completion_outcome"
+  ],
   "properties": {
     "request": {
       "type": "string",
@@ -21,13 +24,76 @@
     },
     "mode": {
       "type": "string",
-      "enum": ["init", "execute", "complete", "resume", "auto"],
+      "enum": [
+        "init",
+        "execute",
+        "complete",
+        "resume",
+        "auto"
+      ],
       "default": "auto"
     },
     "constraints": {
       "type": "array",
-      "items": { "type": "string" },
-      "default": []
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Advisory scope and policy for this run, one per string. Anything that decides where the work LANDS belongs in a typed property above, not here: nothing parses this array, so a misspelled constraint is silently dropped."
+    },
+    "base_branch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The branch the flow branch is cut from and merged back into. Typed rather than left to a constraint string because this is the field that decides WHERE the work lands: a fix aimed at a pull request's own head branch that merges to the repository default instead is a change nobody reviewed, reported as success. Absent, the orchestrator resolves the base itself and records it."
+    },
+    "completion_outcome": {
+      "type": "string",
+      "enum": [
+        "create-pr-and-merge",
+        "verified-handoff",
+        "keep-open"
+      ],
+      "description": "Answers the Phase 4 Completion Choice for a dispatched run, which has no user to ask. REQUIRED: an absent outcome used to mean 'ask', prescribed by the same section that says asking is how a dispatched run stalls on a prompt nobody reads \u2014 and it left the create-pr-and-merge conditional below unreachable by simply omitting the field. A dispatch that cannot name its outcome is BLOCKED, not questioned."
+    },
+    "operator_confirmed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "confirmed_by",
+        "confirmed_at",
+        "plan_digest"
+      ],
+      "description": "The human decision behind an outward-facing completion. Required by callers whose work merges third-party content \u2014 see review-pr-feedback --fix. What `plan_digest` is worth is stated on the field itself; do not infer a replay defence from its presence here.",
+      "properties": {
+        "confirmed_by": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confirmed_at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "plan_digest": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A record of WHICH plan the human said they read \u2014 not a control. Nothing in this tree computes or verifies a digest, and the schema constrains it only to a non-empty string, so an agent composing the dispatch chooses the value and a plan mutated after approval carries the same one. `operator_confirmed`'s PRESENCE is enforced; this field's VALUE is not. Making it a control means hashing the rendered plan and having the receiver recompute over what it got."
+        }
+      }
+    }
+  },
+  "if": {
+    "required": [
+      "completion_outcome"
+    ],
+    "properties": {
+      "completion_outcome": {
+        "const": "create-pr-and-merge"
+      }
     }
+  },
+  "then": {
+    "required": [
+      "operator_confirmed"
+    ]
   }
 }