@sjawhar/pi-legion-envoy 5.28.0 → 5.29.0

package/README.md

@@ -71,9 +71,10 @@ at `dist/skills`. The manifest declares `omp.skills: ["dist/skills"]` alongside
 `<plugin root>/skills` or from directories a manifest's `omp.skills` array names, and this
 package ships skills at `dist/skills` (not the plugin root itself), so the field is required
 for every session — including a headless Legion controller — to see the Legion skills at all.
-The tarball also ships `agents/`, the task agents Legion's prompts dispatch (`oracle`, the
-reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`, and `deep-worker`,
-which writes the implementer's code), which Oh My Pi discovers under any extension package root:
+The tarball also ships `agents/`, the task agents Legion's prompts dispatch (`oracle`; the
+reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`; `deep-worker`,
+which writes the implementer's code; and the planner's checks, `plan-gap-analyst` before it drafts
+and `plan-reviewer` after), which Oh My Pi discovers under any extension package root:
 an installed plugin in a pane, the explicit `--extension` root in a Sandbox pod. Each declares its
 model as a role the operator maps (`docs/kubernetes.md`, "Model roles"). The skills those agents and the
 role prompts load (the pair's rubrics, the implementer's `ce-simplify-code`) ship in

package/agents/plan-gap-analyst.md

@@ -0,0 +1,52 @@
+---
+name: plan-gap-analyst
+description: |
+  Pre-planning gap analyst. Read-only. Use before drafting a plan: finds the hidden requirements,
+  ambiguities, and missing machine-checkable acceptance criteria an issue leaves unsaid, each with
+  what the plan must answer.
+# @oracle is the deployment's `oracle` model role; the Go daemon's boot gate refuses to start unless the operator's settings give
+# this agent a model, through modelRoles.oracle or a task.agentModelOverrides entry for it (docs/kubernetes.md, Operator configuration).
+model: ["@oracle"]
+tools: read, glob, grep, todo
+# The planner waits for the analysis before it drafts; without this, Oh My Pi runs a task agent in
+# the background whenever async jobs are enabled.
+blocking: true
+color: yellow
+---
+
+You read an issue before its plan exists and find what the issue leaves unsaid that would derail
+the plan. You advise the planner; the planner owns the plan.
+
+## What you look for
+
+1. **Hidden requirements.** What the change needs but the issue does not state: a caller, contract,
+   migration, configuration, document, or consumer the change reaches; a behaviour the existing
+   code promises that the change must keep.
+2. **Ambiguities.** A sentence with two readings that lead to different work. Name both readings
+   and what each would cost.
+3. **Acceptance a machine cannot check.** A criterion with no command, test, or request whose
+   expected output decides it, or a requirement with no criterion at all.
+
+Read the code and the repository's own documentation before you call something a gap. A gap the
+issue, the code, or the documentation already answers is not a finding.
+
+## What a finding contains
+
+- **The gap**, quoting the issue's words where it has them.
+- **The evidence**: the file and line, or the issue text, that shows it.
+- **What the plan must answer**: the question or decision the plan has to settle and, for an
+  acceptance gap, a check a machine could run. Say whether the code settles it or only the
+  issue's owner can (a product choice).
+
+Report the findings that change the plan, the most work-changing first. Style, edge cases the plan
+can settle in passing, and the design you would have chosen are not findings. When nothing changes
+the plan, say so in one line.
+
+## Constraints
+
+- **Read-only: you analyse; you do not implement.** Your file tools are read-only; do not ask for
+  others or route edits through other means. Your session also carries the Dispatch and Envoy
+  tools: read with them if you need to, but write nothing through them — no issue, comment, ask,
+  message, suggestion or document edit, and nothing sent or published.
+- Cite what you read. Anything you did not read is an assumption and is written as one.
+- Do not write the plan.

package/agents/plan-reviewer.md

@@ -0,0 +1,61 @@
+---
+name: plan-reviewer
+description: |
+  Plan executability reviewer. Read-only. Use after drafting a plan: checks that it can be carried
+  out as written, approves when in doubt, and names at most three blocking issues, each with its
+  evidence.
+# @review is the deployment's `review` model role; the Go daemon's boot gate refuses to start unless the operator's settings give
+# this agent a model, through modelRoles.review or a task.agentModelOverrides entry for it (docs/kubernetes.md, Operator configuration).
+model: ["@review"]
+tools: read, glob, grep, todo
+# The planner waits for each verdict before it revises or proceeds; without this, Oh My Pi runs a
+# task agent in the background whenever async jobs are enabled.
+blocking: true
+color: magenta
+---
+
+You answer one question: can a capable engineer who has only this plan and the repository carry
+it out without getting stuck? You find blockers, not improvements. You advise the planner; the
+planner owns the plan.
+
+## What you check
+
+1. **References.** The files, functions, commands, and skills the plan names exist and hold what
+   the plan says. Read them; do not assume.
+2. **A place to start.** Every task says where the work is and what changes, in an order that can
+   be followed.
+3. **Contradictions.** No two steps contradict each other, and no step contradicts the issue's
+   acceptance criteria.
+4. **Runnable checks.** Every acceptance criterion names the surface and the exact command that
+   decides it.
+
+You do not judge whether the approach is the best one, style, naming, edge cases the engineer can
+settle during the work, or anything you would simply do differently.
+
+## Verdict
+
+Approve when in doubt. A plan that is mostly clear is good enough. Reject only for a blocker: a
+reference that does not exist or does not hold what the plan says (read to confirm), a task with
+nowhere to start, a contradiction, or a criterion nothing can check.
+
+A rejection names at most three blocking issues, the most severe first. Each gives:
+
+- **The issue**: the exact task, step, or criterion.
+- **The evidence**: the file and line you read, or the plan's own words.
+- **What must change** for it to pass.
+
+A revised plan is read again in full and judged fresh: an issue the revision resolved is not
+raised again, and a second round is no place for requests that would not have blocked the first.
+
+## Output
+
+The first line is the verdict alone: `approved` or `rejected`. Then one or two sentences on why.
+On `rejected`, the numbered blocking issues. Nothing else.
+
+## Constraints
+
+- **Read-only: you review; you do not implement.** Your file tools are read-only; do not ask for
+  others or route edits through other means. Your session also carries the Dispatch and Envoy
+  tools: read with them if you need to, but write nothing through them — no issue, comment, ask,
+  message, suggestion or document edit, and nothing sent or published.
+- Do not rewrite the plan.

package/dist/envoy.js

@@ -30477,6 +30477,8 @@ var EnvelopeSchema = exports_external.object({
 // ../contracts/src/handoff-schema.ts
 var HANDOFF_SCHEMA_VERSION = 1;
 var HANDOFF_PHASES = ["architect", "plan", "implement", "test", "review"];
+var PLAN_REVIEW_MAX_ROUNDS = 3;
+var PLAN_REVIEW_VERDICTS = ["approved", "rejected", "failed"];
 var isoTimestamp = exports_external.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
 var handoffPhase = exports_external.enum(HANDOFF_PHASES);
 var nonEmpty = exports_external.string().trim().min(1);
@@ -30513,6 +30515,16 @@ var requiredSkillsSchema = exports_external.object({
   test: exports_external.array(exports_external.string()).optional(),
   review: exports_external.array(exports_external.string()).optional()
 }).passthrough().optional();
+var gapAnalysisSchema = exports_external.object({
+  findings: exports_external.array(exports_external.object({ finding: exports_external.string(), answer: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
+var planReviewSchema = exports_external.object({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number(),
+  remainingIssues: exports_external.array(exports_external.object({ issue: exports_external.string(), evidence: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
 var planSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("plan"),
   taskCount: exports_external.number().optional(),
@@ -30520,7 +30532,9 @@ var planSchema = baseHandoffSchema.extend({
   routingHints: routingHintsSchema,
   concerns: exports_external.array(exports_external.string()).optional(),
   workflowRecommendation: exports_external.string().optional(),
-  requiredSkills: requiredSkillsSchema
+  requiredSkills: requiredSkillsSchema,
+  gapAnalysis: gapAnalysisSchema,
+  planReview: planReviewSchema
 });
 var implementSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("implement"),
@@ -30560,13 +30574,60 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: exports_external.enum(["approved", "changes_requested"]).optional(),
   keyFindings: exports_external.array(exports_external.object({ severity: exports_external.string(), file: exports_external.string(), description: exports_external.string() }).passthrough()).optional()
 });
-var nonEmptySkillList = exports_external.array(exports_external.string().trim().min(1)).min(1);
+var nonEmptySkillList = exports_external.array(nonEmpty).min(1);
+var recorded = (shape, whatToRecord) => exports_external.object(shape, {
+  error: (issue2) => issue2.input === undefined ? `missing \u2014 record ${whatToRecord}` : undefined
+}).passthrough();
+var gapAnalysisWriteSchema = recorded({
+  findings: exports_external.array(exports_external.object({ finding: nonEmpty, answer: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the gap analyst's `findings`, each with how the plan answers it (`[]` when it found none), or its failed call's `error`").refine((analysis) => analysis.findings === undefined !== (analysis.error === undefined), {
+  message: "record exactly one of `findings` or the failed call's `error`"
+});
+var planReviewWriteSchema = recorded({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number().int().min(1).max(PLAN_REVIEW_MAX_ROUNDS),
+  remainingIssues: exports_external.array(exports_external.object({ issue: nonEmpty, evidence: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the plan review's `verdict` and `rounds`, with `remainingIssues` when it was rejected or `error` when a review's call failed").superRefine((review, ctx) => {
+  const remaining = review.remainingIssues?.length ?? 0;
+  if (review.verdict === "rejected" && remaining === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "a rejected review records the blocking issues its last round named"
+    });
+  }
+  if (review.verdict === "rejected" && review.rounds < PLAN_REVIEW_MAX_ROUNDS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["rounds"],
+      message: `a review still rejecting after ${review.rounds} of ${PLAN_REVIEW_MAX_ROUNDS} rounds is revised and reviewed again, not recorded`
+    });
+  }
+  if (review.verdict === "approved" && remaining > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "an approved review leaves no blocking issue standing"
+    });
+  }
+  if (review.verdict === "failed" !== (review.error !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["error"],
+      message: "a failed review records its call's error, and only a failed review does"
+    });
+  }
+});
 var planWriteSchema = planSchema.extend({
   requiredSkills: exports_external.object({
     implement: nonEmptySkillList,
     test: nonEmptySkillList,
     review: nonEmptySkillList
-  }).passthrough()
+  }).passthrough(),
+  gapAnalysis: gapAnalysisWriteSchema,
+  planReview: planReviewWriteSchema
 });
 var phaseHandoffSchema = exports_external.discriminatedUnion("phase", [
   architectSchema,
@@ -35400,9 +35461,9 @@ function resolveEnvoySession(sessionFile) {
     const parent = `${directory}.jsonl`;
     if (parent === candidate)
       break;
-    const recorded = sessions.get(parent);
-    if (recorded !== undefined)
-      return recorded;
+    const recorded2 = sessions.get(parent);
+    if (recorded2 !== undefined)
+      return recorded2;
     if (path2.dirname(directory) === directory)
       break;
     candidate = parent;

package/dist/legion.js

@@ -30646,6 +30646,8 @@ var EnvelopeSchema = exports_external.object({
 // ../contracts/src/handoff-schema.ts
 var HANDOFF_SCHEMA_VERSION = 1;
 var HANDOFF_PHASES = ["architect", "plan", "implement", "test", "review"];
+var PLAN_REVIEW_MAX_ROUNDS = 3;
+var PLAN_REVIEW_VERDICTS = ["approved", "rejected", "failed"];
 var isoTimestamp = exports_external.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
 var handoffPhase = exports_external.enum(HANDOFF_PHASES);
 var nonEmpty = exports_external.string().trim().min(1);
@@ -30682,6 +30684,16 @@ var requiredSkillsSchema = exports_external.object({
   test: exports_external.array(exports_external.string()).optional(),
   review: exports_external.array(exports_external.string()).optional()
 }).passthrough().optional();
+var gapAnalysisSchema = exports_external.object({
+  findings: exports_external.array(exports_external.object({ finding: exports_external.string(), answer: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
+var planReviewSchema = exports_external.object({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number(),
+  remainingIssues: exports_external.array(exports_external.object({ issue: exports_external.string(), evidence: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
 var planSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("plan"),
   taskCount: exports_external.number().optional(),
@@ -30689,7 +30701,9 @@ var planSchema = baseHandoffSchema.extend({
   routingHints: routingHintsSchema,
   concerns: exports_external.array(exports_external.string()).optional(),
   workflowRecommendation: exports_external.string().optional(),
-  requiredSkills: requiredSkillsSchema
+  requiredSkills: requiredSkillsSchema,
+  gapAnalysis: gapAnalysisSchema,
+  planReview: planReviewSchema
 });
 var implementSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("implement"),
@@ -30729,13 +30743,60 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: exports_external.enum(["approved", "changes_requested"]).optional(),
   keyFindings: exports_external.array(exports_external.object({ severity: exports_external.string(), file: exports_external.string(), description: exports_external.string() }).passthrough()).optional()
 });
-var nonEmptySkillList = exports_external.array(exports_external.string().trim().min(1)).min(1);
+var nonEmptySkillList = exports_external.array(nonEmpty).min(1);
+var recorded = (shape, whatToRecord) => exports_external.object(shape, {
+  error: (issue2) => issue2.input === undefined ? `missing \u2014 record ${whatToRecord}` : undefined
+}).passthrough();
+var gapAnalysisWriteSchema = recorded({
+  findings: exports_external.array(exports_external.object({ finding: nonEmpty, answer: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the gap analyst's `findings`, each with how the plan answers it (`[]` when it found none), or its failed call's `error`").refine((analysis) => analysis.findings === undefined !== (analysis.error === undefined), {
+  message: "record exactly one of `findings` or the failed call's `error`"
+});
+var planReviewWriteSchema = recorded({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number().int().min(1).max(PLAN_REVIEW_MAX_ROUNDS),
+  remainingIssues: exports_external.array(exports_external.object({ issue: nonEmpty, evidence: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the plan review's `verdict` and `rounds`, with `remainingIssues` when it was rejected or `error` when a review's call failed").superRefine((review, ctx) => {
+  const remaining = review.remainingIssues?.length ?? 0;
+  if (review.verdict === "rejected" && remaining === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "a rejected review records the blocking issues its last round named"
+    });
+  }
+  if (review.verdict === "rejected" && review.rounds < PLAN_REVIEW_MAX_ROUNDS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["rounds"],
+      message: `a review still rejecting after ${review.rounds} of ${PLAN_REVIEW_MAX_ROUNDS} rounds is revised and reviewed again, not recorded`
+    });
+  }
+  if (review.verdict === "approved" && remaining > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "an approved review leaves no blocking issue standing"
+    });
+  }
+  if (review.verdict === "failed" !== (review.error !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["error"],
+      message: "a failed review records its call's error, and only a failed review does"
+    });
+  }
+});
 var planWriteSchema = planSchema.extend({
   requiredSkills: exports_external.object({
     implement: nonEmptySkillList,
     test: nonEmptySkillList,
     review: nonEmptySkillList
-  }).passthrough()
+  }).passthrough(),
+  gapAnalysis: gapAnalysisWriteSchema,
+  planReview: planReviewWriteSchema
 });
 var phaseHandoffSchema = exports_external.discriminatedUnion("phase", [
   architectSchema,
@@ -33611,7 +33672,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.28.0",
+  version: "5.29.0",
   type: "module",
   omp: {
     extensions: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "5.28.0",
+  "version": "5.29.0",
   "type": "module",
   "omp": {
     "extensions": [