@sjawhar/opencode-legion-envoy 3.17.0 → 3.18.0

package/dist/src/server.js

@@ -14363,6 +14363,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);
@@ -14399,6 +14401,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(),
@@ -14406,7 +14418,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"),
@@ -14446,13 +14460,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/AGENTS.md

@@ -16,7 +16,7 @@ event intake, process lifecycle, credentials, and role delivery.
 | `legion-retro/` | the implementer, at retro | the pre-merge retrospective and its Dispatch message |
 | `legion-worker/` | planner, implementer, tester, reviewer, merger | the phase contracts: handoffs, GitHub identity, PR body and READY discipline, the merge-gate order |
 | `thermonuclear-code-quality/` | the `thermonuclear-code-quality` agent | the maintainability rubric of the reviewer's pair |
-| `thermonuclear-deep-review/` | the `thermonuclear-deep-review` agent | the security and correctness rubric of the reviewer's pair |
+| `thermonuclear-deep-review/` | the `thermonuclear-deep-review` agent, and the reviewer (the Security Guidelines) | the correctness rubric of the reviewer's pair, with its tagged, diff-triggered Security Guidelines and the attack on the PR body's claims |
 
 The owning skill above is where each contract is defined; a role prompt that needs a contract from its own seat points there or restates only its own step. This file lists and does not restate.
 A Legion prompt (a skill here, a role prompt, or an agent definition in `packages/pi-envoy/agents/`) names a task agent only as `task(agent="<name>")` and a skill it tells the model to load only as `skill://<name>`. Those are the two forms the Go daemon's boot gate and `legion probe-image` resolve through Oh My Pi, refusing by name one it cannot find; a dispatch or a load written any other way goes unchecked. An agent or skill Legion's prompts name is shipped here or in `packages/pi-envoy/agents/`, unless Oh My Pi bundles it.

package/skills/envoy/SKILL.md

@@ -45,7 +45,7 @@ Envoy renders an annotated delivery before its source summary and complete paylo
 
 ```text
 envoy:
-  to: you (01a0…)
+  to: you (ses_example_recipient)
   from: 01a0bbbb-cccc-7ddd-eeee-0123456789ab (Reviewer)
   at: "2026-09-07T04:41:12Z"
   id: agent-message-2

package/skills/legion-retro/SKILL.md

@@ -65,7 +65,13 @@ before step 3. The design gate is not a substitute for review and retro.
 ## Durable outputs
 
 Write the integrated learning as one or more discoverable documents under `docs/solutions/`.
-Organize by reusable topic rather than by pull request. Each document uses this front matter:
+Organize by reusable topic rather than by pull request. Search `docs/solutions/` for the topic
+first: when a document already states the rule, update it in place (sharpen the rule, add this
+issue and pull request to `related_issues`) rather than writing a sibling; when the new learning
+replaces an old document, set the old one's `status: superseded` and add
+`superseded_by: docs/solutions/<path>.md`. Open each document with the rule in a few imperative
+lines; the incident that taught it goes in an Evidence section below, never in the rule. Each
+document uses this front matter:
 
 ```yaml
 ---

package/skills/legion-worker/SKILL.md

@@ -287,7 +287,7 @@ rather than creating a replacement bookmark or PR.
 
 ## PR body, review, and the merge gate
 
-The implementer writes the pull request body in the READY format when it opens the pull request,
+The implementer writes the pull request body from the template when it opens the pull request,
 and every later phase edits its own lines of the live body rather than replacing it. Each proof
 (the implementer's `E2E (implementer)` line and `proof` array, the tester's `E2E (tester)` line
 and `proof` array) is the changed behaviour exercised on a production-like surface, recorded as

package/skills/legion-worker/references/merge-gate.md

@@ -71,14 +71,17 @@ completion leaves the issue in reviewing until you finish.
   First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
   "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
   in READY (an empty output is quoted as `no file changes above the approved head`); then the same
-  with `'~docs/solutions'` appended, which must print nothing. The merger always posts
-  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` (the shape
-  `packages/pi-envoy/roles/merger.md` defines), its summary, and the PR body's gate facts as a
-  `dispatch_message` on the issue. When the `Legion addressing` line names a merge queue, it also
-  publishes the same packet there with `envoy_publish`; a 404 means the Dispatch message remains
-  the durable notice and the merger stays idle. The READY packet names both the implementer's and
-  tester's `E2E` lines; a missing one is reported to the architect instead of published. Legion
-  never merges.
+  with `'~docs/solutions'` appended, which must print nothing. *The READY packet*: the merger
+  always posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+  (the shape `packages/pi-envoy/roles/merger.md` defines), then the PR body's `Outcome:` line and
+  its `Not proven / risk:` value — every bullet under that label joined with `; ` on the one
+  READY line, or `none` — quoted from the `## For the reviewer` block at that same head (or one
+  line saying the body carries no brief — the packet still publishes), then the `--summary`
+  output and the PR body's gate facts, as a `dispatch_message` on the issue. When the `Legion
+  addressing` line names a merge queue, it also publishes the same packet there with
+  `envoy_publish`; a 404 means the Dispatch message remains the durable notice and the merger
+  stays idle. The READY packet names both the implementer's and tester's `E2E` lines; a missing
+  one is reported to the architect instead of published. Legion never merges.
 
 ## After the human merge
 

package/skills/legion-worker/references/pr-body.md

@@ -4,12 +4,24 @@ Part of `skill://legion-worker`. Read it before you write or edit any line of th
 body, put a `proof` array in a handoff, verify another phase's proof, or run the simplify pass.
 Every path it cites is in sjawhar/legion.
 
-## The READY format
+## The pull request body template
 
-The implementer writes the PR body in the READY format from the moment the PR opens, and every
+The implementer writes the PR body from this template from the moment the PR opens, and every
 later phase keeps it current rather than replacing it:
 
 ```
+## For the reviewer
+
+**Outcome:** <one sentence a user of this repository would recognise: what someone can now do, or what stops going wrong>
+**Why:** <the problem, one or two sentences, ending with the Dispatch key in parentheses — the key only, never a URL>
+**Change:**
+- <two to five bullets, each one behaviour a user or operator meets, never a file name>
+**Look at first:** <one to three `path:line` places where a wrong decision would hurt> (the reviewer writes this line)
+**Proven by:** <the `E2E (implementer)` line's surface and run, one line>
+**Not proven / risk:**
+- <one line per claim recorded as unproven before READY>, or the single word `none` (the reviewer writes this line; `none` is invalid while such a claim stands)
+**Size:** <files changed, +added/−removed>
+
 ## Verification
 
 **CI:** `Tests` run <run-id> — jobs lint, typecheck, test all success at <head-sha>; `PR Title` run <run-id> — job pr-title success at <head-sha>.
@@ -28,10 +40,10 @@ left open <thread URL> — newest reply by <login> is not its opener's or the Le
 <verdict>. (omitted entirely on a docs-only PR — there is no code for either pass, so neither runs)
 
 **E2E (implementer):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
-Negative control: <deliberately broken input> → <refusal or failure observed>.
+Negative control: <deliberately broken input or call> → <refusal or failure observed>.
 
 **E2E (tester):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
-Negative control: <deliberately broken input> → <refusal or failure observed>.
+Negative control: <deliberately broken input or call> → <refusal or failure observed>.
 Verified the implementer's proof by <re-running its command | driving the same surface independently>.
 
 **Production:** <what was checked in production, how, what was observed> — merge commit <sha>.
@@ -42,11 +54,27 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
 ```
 
+## The brief for the human
+
+`## For the reviewer` is written for the person who merges; `## Verification` below it stays the
+ledger the reviewer and merger check against GitHub. The implementer writes `Outcome`, `Why`,
+`Change`, `Proven by`, and `Size` when the pull request opens, and keeps them true after every
+push; `Outcome` is a sentence a user of the repository would recognise, never "fix bug" or a file
+name, and `Why` ends with the Dispatch key, never a URL. The reviewer writes `Look at first` and
+`Not proven / risk` at each round, into the live body (`legion gh -- api
+repos/{owner}/{repo}/pulls/{number} --jq .body`, edit, then `--method PATCH ... -F body=@body.md`);
+`Not proven / risk` copies every claim recorded as unproven before READY — the tester's
+`failures`, the reviewer's own review, any proof-check comment already on the pull request —
+word for word, and `none` is a finding while one stands. The merger quotes `Outcome` and
+`Not proven / risk` from the body at the published head in the READY packet
+(*The READY packet* in `skill://legion-worker/references/merge-gate.md`); a stale `Outcome` that no
+longer describes the diff is a finding against the implementer, not a line the merger rewrites.
+
 ## What a proof is
 
 **A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
 as the exact command or run id, what was observed, the head SHA, and one negative control —
-a deliberately broken input and the refusal or failure observed. The surface is
+a deliberately broken input or call and the refusal or failure observed. The surface is
 **production-like** — the repository's real-process test harness and fixtures, a sandbox
 repository, a real browser, a devN stack, staging, or a local stack with real migrations, one that
 has the resource the change touches — and each `E2E` line carries a **link** to that run,

package/skills/thermonuclear-deep-review/SKILL.md

@@ -56,6 +56,32 @@ The codebase might gate features behind feature flags or internal-only checks. D
 ## Intended Breakage Guidelines
 If a high-risk effect is an intentional, well-constrained change, do not report it as a defect. Report it when the scope or consequences appear unclear, including when a safeguard or feature gate is removed.
 
+## Claims in the PR body
+
+A safety or correctness claim written in a PR body is a claim like any other, and the only reader who catches a wrong one is the reader told to ATTACK it. Verifying reviewers read the code against the claim and pass; that is what they are for. Attack the body's claims, not only its diff.
+
+Two shapes to attack first:
+
+- **Neutralization ORDER, not coverage.** Any pipeline that sanitizes and then edits can create what it sanitized. The test is not "did it neutralize everything" but "can any later pass CREATE what was being neutralized".
+- **A severity resting on a third party's formatting is a dependency, not a mitigation.** Rate it as the bet it is, and fix rather than disclose.
+
+## Security Guidelines
+
+For each row whose surface the diff touches, answer with a file:line citation. End your report with one `Security:` line: each touched row's tag and its answer with file:line, or `Security: no sensitive surface in this diff.` when the diff touches none.
+
+| Tag | If the diff touches… | Answer, with file:line |
+| --- | --- | --- |
+| `authz` | an authorization or refusal check, or a new route, command, or tool | who may call it, who may not, where the diff enforces that, and what the unauthorized caller gets |
+| `secret` | a token, grant, secret file, credential helper, or its lifetime | what widened: who can read it, for how long, in which process |
+| `untrusted-input` | a subprocess, argv, path, template, or query built from text an outside party controls (an issue body, a PR comment, a webhook payload, model output) | the boundary that neutralizes it, and whether any later pass can re-create what was neutralized (order, not coverage) |
+| `prompt` | a prompt that embeds untrusted text into an agent's instructions | what delimits the untrusted region, and what the agent may do if it obeys that text (OWASP LLM01 prompt injection, LLM06 excessive agency) |
+| `supply-chain` | a dependency, lockfile, base image, or GitHub Action | the version, the pin (a digest or a SHA checked against its tag), and the permissions the workflow runs with |
+| `sandbox` | a sandbox or pod manifest, a capability, or a network policy | which isolation property changed, and against whom |
+| `agent-def` | an agent definition, skill, role prompt, `.omp/` config, or `AGENTS.md` | whether this diff can steer its own reviewers, and why this edit is trustworthy anyway |
+| `transport` | TLS/certificate verification, a signature, HMAC, or randomness source, or an unbounded read/write sized by untrusted input | what changed, the check or bound it relies on, and the ASVS V11/V12 identifier it maps to |
+
+Cite an OWASP ASVS v5.0.0 identifier where one applies (`v5.0.0-1.2.5` style). A security finding with no stated exploit path is not a finding: call it hardening and rank it Minor. A security finding that states an exploit path is always its own finding at its real priority, never folded into hardening. Report at most two hardening items, ranked, and fold the rest into one hardening paragraph. Start each security finding with its row's tag, `Security[<tag>]:`, so it can be told from the others and counted by row.
+
 ## Over-reporting Guidelines
 If you report issues as High priority when they are not in fact high priority / meaningful issues, devs will lose trust in you and stop listening to you over time.
 Never misreport priority or importance. Trace issues end to end and report only what the evidence supports.