@mrciphersmith/keryx 0.2.71 → 0.2.72

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

@@ -4,11 +4,25 @@
   "title": "Job Orchestrator Input Contract",
   "description": "Defines all input parameters required to run job-orchestrator. This is the top-level entry point for the AI implementation pipeline.",
   "type": "object",
-  "required": ["issue", "codebase", "automation"],
+  "required": ["intent", "codebase", "automation"],
+  "allOf": [
+    {
+      "if": { "properties": { "intent": { "enum": ["implement", "analyze"] } } },
+      "then": {
+        "required": ["issue"],
+        "description": "implement and analyze start from an issue, so one is required. review and custom have no issue and never did — requiring it unconditionally made two of the four intents unrepresentable."
+      }
+    }
+  ],
   "properties": {
+    "intent": {
+      "type": "string",
+      "enum": ["implement", "analyze", "review", "custom"],
+      "description": "What the job is for. Selects the plan (SKILL.md 1.1) and decides whether `issue` is required."
+    },
     "issue": {
       "type": "object",
-      "description": "GitHub issue identification. Provide EITHER url OR repo+number.",
+      "description": "GitHub issue identification. Required for the implement and analyze intents. Provide EITHER url OR repo+number.",
       "properties": {
         "url": {
           "type": "string",
@@ -52,8 +66,7 @@
         },
         "base_branch": {
           "type": "string",
-          "default": "develop-2",
-          "description": "Base branch to create feature branch from"
+          "description": "Base branch to create the feature branch from. NO DEFAULT, deliberately: SKILL.md 0.2 auto-detects the repository's own default branch and asks the operator to confirm it. The value shipped here used to be `develop-2`, a branch from an unrelated project, which a caller that omitted the field would silently have inherited."
         },
         "additional_codebases": {
           "type": "array",
@@ -86,43 +99,40 @@
         "skip_confirmation": {
           "type": "boolean",
           "const": true,
-          "description": "Must be true — sub-agents run without confirmation"
+          "description": "Must be true — DISPATCHED SUB-AGENTS run without per-dispatch confirmation. It does not govern the Phase 0.4 operator gate ('Proceed?'), which is a question to the human and is controlled by `plan_approval`. The two were read as contradictory only because they shared a name."
         },
         "max_review_iterations": {
           "type": "integer",
           "minimum": 1,
           "maximum": 3,
-          "default": 2,
-          "description": "Max review → fix iterations"
+          "default": 3,
+          "description": "Max review → fix iterations. Three: the same bound `task-implementer`, `flow-orchestrator` and SKILL.md 2.7 carry, pinned across all of them by src/gdskills/round-bound.test.ts. The default was 2 here, which made the contract disagree with the skill it validates."
+        },
+        "plan_approval": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show the execution plan and ask the operator to approve or adjust before Phase 2 (SKILL.md 1.3). This is the automation switch for an operator question; `skip_confirmation` is not."
         },
         "auto_create_pr": {
           "type": "boolean",
           "default": false,
           "description": "Auto-create draft PR without asking user (default: ask)"
         },
-        "reviewers": {
+        "review_flags": {
           "type": "array",
-          "items": {
-            "type": "string",
-            "enum": [
-              "code-ai-review",
-              "code-boss-review",
-              "code-style-review",
-              "code-mobx-store-review"
-            ]
-          },
-          "default": ["code-ai-review", "code-boss-review", "code-style-review"],
-          "description": "Review skills to always run"
+          "items": { "type": "string" },
+          "description": "Reviewer selection passed straight to `review-orchestrator` (for example [\"--backend\", \"--security\"]). Omit to let it auto-detect from the diff. This replaces the former `reviewers`/`conditional_reviewers` pair, which named individual review skills for a hand-dispatch path SKILL.md 2.6 no longer takes: reviewers are selected by flag and gated by `keryx review stack`, not listed here."
         },
-        "conditional_reviewers": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          },
-          "default": {
-            "code-mobx-store-review": "*.store.ts"
-          },
-          "description": "Review skills to run conditionally: {skill_name: file_glob_pattern}"
+        "convention_reviewers": {
+          "type": "string",
+          "default": "ask",
+          "description": "Optional project-convention reviewers: \"ask\" (prompt the operator), \"all\", \"none\", or a comma-separated list of skill names."
+        },
+        "verification_mode": {
+          "type": "string",
+          "enum": ["off", "annotate", "filter"],
+          "default": "annotate",
+          "description": "Passed to `review-orchestrator` and to `keryx review ingest --verification-mode`. `annotate` records verifier verdicts without removing findings."
         },
         "run_final_checks": {
           "type": "boolean",

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

@@ -12,28 +12,35 @@
      ↓
 [Orchestrator] → loads SKILL.md, follows this checklist
      ↓
-Phase 0: Context collection, intent determination, plan building
+Phase 0: keryx job list --json → resume or start; collect context; confirm
      ↓
-Phase 1: [job-documenter sub-agent] → initialize .metaproject/jobs/<job-name>/ + README + plan
+Phase 1: keryx job init --name <slug> --intent <intent> --project <path>
      ↓
-Phase 2: Execute plan dynamically:
+Phase 2: Execute plan, bracketing every step with keryx job step:
      ↓
      ├─ [issue-analyzer sub-agent] → JSON analysis result
      ├─ git worktree add → feature branch (NEVER git checkout -b)
-     ├─ FOR EACH wave → [wave-executor sub-agent] → compact WAVE_DONE summary
-     ├─ Load review skills → findings
-     ├─ IF findings → [task-implementer sub-agent (fix)] → re-review (max 2x)
-     ├─ npm run lint && type-check && test
-     └─ [job-documenter] → document each step result
+     ├─ FOR EACH wave → [tests-creator × tasks] then [task-implementer × tasks]
+     ├─ [code-verifier sub-agent] → quality gate
+     ├─ keryx review start → [review-orchestrator sub-agent] → keryx review ingest
+     ├─ IF blocker/major → [task-implementer (fix)] → next managed round (max 3)
+     ├─ keryx review complete --finding … --disposition … --evidence …
+     └─ keryx job document → each step's artifact recorded in the package
      ↓
-Phase 3: [job-documenter] → finalize → final report
+Phase 3: keryx job complete <job-name> → final report
      ↓
 (Optional) gh pr create --draft
 ```
 
+Every sub-agent dispatch uses `subagent_type: "general-purpose"`.
+
 ## Phase 0: Context Collection (Guard Clause)
 
-Before starting, determine intent and collect context:
+0. **Check for an unfinished job first:**
+   ```bash
+   keryx job list --json          # phase != COMPLETION means unfinished
+   keryx job status <name> --json # next_step is where to resume
+   ```
 
 1. **Determine intent** from user request:
    - "Implement issue" → `implement` (full cycle)
@@ -47,9 +54,9 @@ Before starting, determine intent and collect context:
    ○ Type the full absolute path to your project
    ```
 
-3. **Base branch** → ask to confirm (no default).
+3. **Base branch** → auto-detect, present, ask to confirm. No hardcoded default.
 
-4. **Job name** → auto-generate + confirm:
+4. **Job name** → auto-generate + confirm. Must match `^[a-z0-9-]+$`:
    - `issue-<N>--<slug>` for implement
    - `analysis--issue-<N>` for analyze
    - `review--<slug>` for review
@@ -59,28 +66,37 @@ Before starting, determine intent and collect context:
    - `implement`: Create PR? (default: yes)
    - `analyze`: nothing (ask about implementation after analysis)
 
-6. **Show summary and ask for confirmation** before starting.
+6. **Show summary and ask for confirmation** before starting. This operator gate is
+   not governed by `skip_confirmation`, which covers sub-agent dispatch only.
 
-## Phase 1: Initialize Documentation
+## Phase 1: Create the Job Package
 
-Dispatch `job-documenter` sub-agent with `ACTION: init`.
-
-Write initial `state.json` to `.metaproject/jobs/<job-name>/state.json` after job docs are initialized.
+```bash
+keryx job init --name <job-name> --intent implement|analyze|review|custom --project <project_dir>
+keryx job status <job-name>     # confirm the plan, phase and first open step
+```
 
-Verify `DOCUMENTER_RESULT.status == "success"`.
+`keryx job` is the only writer of `state.json`, and it validates every write against
+the registered contract `job-orchestrator-state`. Never hand-write the file.
 
 ## Phase 2: Execute Plan
 
-Execute plan steps sequentially. After each step:
-1. Collect result
-2. Send to `job-documenter` (ACTION: add-document)
-3. Update README (ACTION: update-readme)
-4. Update `state.json` with step completion
-5. Mark step as completed
+Execute plan steps in order. For each step:
+
+```bash
+keryx job step <job-name> <step-id> --status in-progress    # counts a retry on re-entry
+# … run the step …
+keryx job document <job-name> --type <analysis|implementation-report|review|verification-report> --file <path>
+keryx job status <job-name>                                  # the job index
+keryx job step <job-name> <step-id> --status completed
+```
+
+A conditional step whose trigger did not fire is closed too:
+`keryx job step <job-name> <step-id> --status skipped --reason "<why>"`.
 
 ### Step: ANALYZE
 
-Read `skills/issue-analyzer/orchestrator-prompt.md`, fill in parameters:
+Read `skills/gdskills/orchestration/issue-analyzer/orchestrator-prompt.md`, fill in parameters:
 
 ```
 ISSUE_URL: <url>   (or ISSUE_REPO + ISSUE_NUMBER)
@@ -92,7 +108,7 @@ SEARCH_DEPTH: focused (default)
 Launch Task(issue-analyzer). Parse JSON result — extract tasks and dependency_order.
 
 For `analyze` intent: show result, ask "Implement? (yes/no)".
-- yes → extend plan: prepare → implement → review → fix → checks → report → pr
+- yes → create a second package: `keryx job init --name <name>-impl --intent implement …`
 - no → Phase 3
 
 ### Step: PREPARE — Create Feature Branch
@@ -102,62 +118,78 @@ For `analyze` intent: show result, ask "Implement? (yes/no)".
 ```bash
 git -C <project_dir> fetch origin <base_branch>
 git -C <project_dir> worktree add ../<branch-slug> -b feature/<branch-slug> origin/<base_branch>
-npm install --prefix <worktree_path>
+# then install with the DETECTED package manager — never hardcode npm
 ```
 
-All subsequent operations ONLY in worktree directory.
+All subsequent operations ONLY in the worktree directory.
 
-### Step: IMPLEMENT — Wave Isolation
+### Step: TESTS-CREATOR + IMPLEMENT — Waves
 
 ```
-WAVES = topological_sort_into_waves(dependency_order, task_dependencies)
+WAVES = dependency_order from ANALYSIS_RESULT (already topologically sorted)
 
 FOR wave_index, wave_tasks in enumerate(WAVES):
-  1. Dispatch single Agent("wave-executor") with all tasks in this wave
-     (see skills/job-orchestrator/SKILL.md step 2.4.1 for full prompt template)
-  2. Receive compact WAVE_RESULT:
-       STATUS: WAVE_DONE | WAVE_PARTIAL | WAVE_FAILED
-       Commits: [hash msg, ...]
-       Tests: N passed, M failed
-       Tasks: task-1 ✅, task-2 ✅
-  3. Decision:
-       WAVE_DONE    → continue to next wave
-       WAVE_PARTIAL → log concerns (read result files if needed), continue
-       WAVE_FAILED  → STOP, read result files for failed tasks, ask user
-
-Do NOT dispatch task-implementers directly — always via wave-executor.
-Context budget rule: orchestrator only accumulates compact wave summaries,
-never raw task-implementer output.
+  1. Dispatch one tests-creator per task, in a SINGLE turn (parallel). Wait for all.
+     Load skill: skills/gdskills/quality/tests-creator/SKILL.md
+  2. Parallel safety check: tasks sharing a target_file run sequentially.
+  3. Dispatch one task-implementer per task, in a SINGLE turn (parallel). Wait for all.
+     Load skill: skills/gdskills/orchestration/task-implementer/SKILL.md
+  4. Read each STATUS line:
+       all DONE               → next wave
+       any DONE_WITH_CONCERNS → record concerns, continue
+       any BLOCKED            → STOP, read the result file, resolve or ask the user
+
+There is no wave-executor agent. Instruct every dispatched agent to write full
+detail to <JOBS_ROOT>/<job-name>/results/<task_id>.json and return only a compact
+summary — context grows with what agents RETURN.
 ```
 
-Document result in job-documenter.
+Record with `keryx job document --type implementation-report`.
 
-### Step: REVIEW — Run Reviewers
+### Step: VERIFY — Quality Gate
 
-```
-REVIEWERS = ["code-ai-review", "code-boss-review", "code-style-review"]
-IF *.store.ts modified: add "code-mobx-store-review"
+Dispatch `code-verifier` (`skills/gdskills/orchestration/code-verifier/SKILL.md`) with
+`codebase_path`, `base_branch`, `scope: changed`. Record with
+`keryx job document --type verification-report`.
+
+### Step: REVIEW — One Managed Round
 
-FOR reviewer in REVIEWERS:
-  Load skill → execute → collect findings as JSON
+```bash
+keryx review budget  --spent <usd> --outstanding <subagents in flight>   # STOP on non-zero exit
+keryx review start   --target branch --ref <feature-branch> --head "$(git rev-parse HEAD)"
+keryx review comments collect --repo <owner/repo> --pr <n> --sha <head-sha> --round <n> --out <file>
+keryx review scope        --ref "$BASE_SHA" --json > scope.json
+keryx review blast-radius --ref "$BASE_SHA" --json > blast-radius.json    # KEEP BOTH
+keryx review stack --json                                                # which reviewers apply
+keryx review tier  --scope <scope> --diff-lines <n> --json                # model per dispatch
+# dispatch review-orchestrator (skills/gdskills/review/review-orchestrator/SKILL.md);
+# it runs review-verifier in Wave C and emits the ```json keryx:findings``` block
+keryx review ingest --report <report.md> --ref <feature-branch> --head <sha> \
+  --scope scope.json --blast-radius blast-radius.json \
+  --verifications <file> --refuted <file> --outstanding <n>
 ```
 
-Document result.
+`--blast-radius` is required on any round that dispatched `review-regression`; an
+ingest carrying a scope-B finding without it is refused. Severities are
+`blocker|major|minor|info`. Record with `keryx job document --type review`.
 
-### Step: FIX — Review-Fix Loop (max 2 iterations)
+### Step: FIX — Review-Fix Loop (max 3 iterations)
 
-If CRITICAL or WARNING findings exist:
+If `blocker` or `major` findings exist:
 1. Group by file
-2. Launch task-implementer (task_type: "fix") with review findings JSON
-3. Re-run reviewers
-4. Recount findings
-
-### Step: CHECKS — Final Verification
+2. Launch task-implementer (`task_type: "fix"`) with the findings
+3. Run the sanity check — verify commits were made
+4. Run the NEXT managed round (the whole REVIEW sequence above, `is_fix_round: true`)
+5. Disposition every finding of the previous round:
+   ```bash
+   keryx review complete <review-id> --finding F-001 --disposition acted-on --evidence "<commit>"
+   ```
+6. STUCK CHECK — break on a repeated finding identity or an identical report, even
+   with iterations left. `keryx review loop --flow <id>` detects it from the record.
 
+After the LAST round only:
 ```bash
-npm run lint
-npm run type-check
-npm test
+keryx review comments reply --repo <owner/repo> --pr <n> --outcomes <file> --sha <sha> --final
 ```
 
 ### Step: REPORT — Generate Final Report
@@ -174,6 +206,6 @@ gh pr create --title "<title>" --body "..." --base <base> --head <head> --draft
 
 ## Phase 3: Completion
 
-1. Dispatch `job-documenter` with `ACTION: finalize`
-2. Update `state.json` with `phase: "COMPLETION"`
-3. Tell user what was accomplished + documentation path + PR URL (if created)
+1. Close every remaining step: `keryx job step <job-name> <step-id> --status completed|skipped --reason "<why>"`
+2. `keryx job complete <job-name>` — refused while any step is open or failed, and it names them
+3. Tell the user what was accomplished, the package path, and the PR URL (if created)

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/output-contract.schema.json

@@ -22,15 +22,19 @@
             "type": "string",
             "enum": [
               "Summary",
+              "Analysis",
               "Tasks",
               "Review Results",
               "Unresolved Issues",
               "Final Checks",
+              "Skill Updates",
+              "Metrics",
+              "Execution Metrics",
               "Changes Summary",
               "PR Proposal"
             ]
           },
-          "description": "Sections in the report"
+          "description": "Sections in the report. The enum matches the template in SKILL.md 2.9 — it was closed at seven values and excluded two sections the skill instructs the orchestrator to emit, so a conforming report was unrepresentable."
         }
       }
     },
@@ -47,10 +51,13 @@
             "branch_name": { "type": "string" },
             "tasks_completed": { "type": "integer" },
             "tasks_total": { "type": "integer" },
-            "review_iterations": { "type": "integer" },
+            "review_rounds": {
+              "type": "integer",
+              "description": "Managed review rounds run — each one has a package under .metaproject/reviews/."
+            },
             "final_status": {
               "type": "string",
-              "enum": ["READY FOR PR", "HAS WARNINGS", "HAS ISSUES", "FAILED"]
+              "enum": ["READY FOR PR", "HAS WARNINGS", "HAS ISSUES", "ANALYSIS ONLY", "FAILED"]
             }
           }
         },
@@ -69,16 +76,31 @@
         },
         "review_results": {
           "type": "array",
+          "description": "Per-reviewer counts, in the canonical severity vocabulary of review-finding.schema.json. The old critical/warning/info triple could not be populated from findings the reviewers actually produce.",
           "items": {
             "type": "object",
             "properties": {
               "reviewer": { "type": "string" },
-              "critical": { "type": "integer" },
-              "warning": { "type": "integer" },
+              "review_id": { "type": "string", "description": "The managed review package this round was ingested into." },
+              "blocker": { "type": "integer" },
+              "major": { "type": "integer" },
+              "minor": { "type": "integer" },
               "info": { "type": "integer" }
             }
           }
         },
+        "dispositions": {
+          "type": "object",
+          "description": "Terminal disposition counts recorded by `keryx review complete`. `unknown` above zero means findings were closed without anyone writing down what happened to them.",
+          "properties": {
+            "unknown": { "type": "integer" },
+            "acted-on": { "type": "integer" },
+            "dismissed-incorrect": { "type": "integer" },
+            "dismissed-wont-fix": { "type": "integer" },
+            "dismissed-out-of-scope": { "type": "integer" },
+            "dismissed-deprioritised": { "type": "integer" }
+          }
+        },
         "final_checks": {
           "type": "object",
           "properties": {

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

@@ -137,7 +137,7 @@
               "reviewer": {
                 "type": "string",
                 "description": "Which review skill found this",
-                "examples": ["code-ai-review", "code-boss-review", "code-style-review"]
+                "examples": ["code-ai-review", "code-learned-review", "code-style-review"]
               }
             }
           },

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

@@ -42,7 +42,7 @@ This skill focuses on:
 This skill does NOT duplicate:
 - MobX store-specific patterns → covered by code-mobx-store-review
 - Naming/formatting/import organization → covered by code-style-review
-- Architecture opinions and persona-specific insights → covered by code-b091-review
+- Architecture opinions and persona-specific insights → covered by code-learned-review
 
 ## Главное правило: скоуп ревью
 
@@ -180,7 +180,7 @@ This skill covers **general AI code quality review** following `code-review-ai-a
 |---------|-----------|-------------|
 | Types, safety, architecture, readability, performance, tests | ✅ YES | — |
 | MobX store internals (actions, computed, reactions, async) | ⚠️ surface-level only | `code-mobx-store-review` for deep store analysis |
-| b091-style direct feedback, logic-layer enforcement | ❌ NO | `code-b091-review` |
+| Review against this project's own learned conventions | ❌ NO | `code-learned-review` |
 | Pure style/naming/pattern audit | ❌ NO | `code-style-review` |
 
 ---