@codeam/shared 2.75.8 → 2.75.9

package/dist/index.mjs

@@ -2592,6 +2592,9 @@ function normalizeGuardrailPolicy(raw) {
 var GUARDRAIL_CONFIGURE_COMMAND = "guardrail_configure";
 
 // src/packs/types.ts
+var PACK_FINDINGS_FILE = "REVIEW-FINDINGS.pack.json";
+var MAX_PACK_FINDINGS = 50;
+var PACK_HANDOFF_HEADING = "## Handoff";
 var PACK_START_COMMAND = "pack_start";
 var PACK_ACTION_COMMAND = "pack_action";
 var PACK_STATUS_COMMAND = "pack_status";
@@ -2611,6 +2614,8 @@ Method:
    - **Verification plan** \u2014 for each criterion, the level that proves it (unit / integration / manual) and why.
 3. Right-size: if the task is clearly too large for one pipeline run, narrow the criteria to a coherent first slice and record the rest under "Out of scope / next".
 
+4. Close with a \`## Handoff\` section: the criteria count, what you scoped out, and any assumption the Coder must know.
+
 Handoff bar: the spec file is committed; every acceptance criterion is testable as written; a competent implementer could start without asking you anything.`;
 var CODER_PROMPT = `# Role: Coder
 
@@ -2621,6 +2626,7 @@ Method:
 2. Test-first where it fits: write the test that proves a criterion, watch it fail, implement until it passes. Where strict test-first doesn't fit, still land tests alongside the change.
 3. Match the project's existing style, structure, and conventions. Simplest design that fully solves the problem \u2014 no speculative abstractions, no "while I'm here" changes.
 4. Run the project's tests / linters / build and make them pass.
+5. Close with a \`## Handoff\` section: which criteria are implemented (by number) and where their tests live, anything you consciously did NOT do, and what the Reviewer should look at first.
 
 Handoff bar: every acceptance criterion is implemented and covered by a test; the project's checks pass; the work is committed in focused commits.`;
 var REVIEWER_PROMPT = `# Role: Reviewer
@@ -2636,21 +2642,42 @@ Method:
    - **Conventions & naming** \u2014 matches the surrounding code; names say what things are.
    - **Safety** \u2014 no secrets, credentials, or debugging remnants in code, tests, or fixtures.
 3. Fix what is justified \u2014 smallest change that resolves the finding, keeping behavior. Re-run the checks after material fixes.
-4. Record your findings honestly in your closing summary: what you found, what you fixed, what you deliberately left, and what you could not verify.
-
-Handoff bar: checks pass on YOUR final commit; every fix is committed; your summary lists findings \u2192 resolutions (an empty findings list must say what you checked).`;
+4. Write your findings as DATA to \`REVIEW-FINDINGS.pack.json\` at the repo root \u2014 the next stage verifies them one by one, so what is not in this file does not get verified. Exact shape:
+   \`\`\`json
+   {
+     "findings": [
+       {
+         "id": "R1",
+         "severity": "blocker | major | minor | nit",
+         "title": "one line: what is wrong",
+         "detail": "why it matters and what you did about it",
+         "file": "src/path/to/file.ts",
+         "line": 42,
+         "resolution": "fixed | deferred | wont_fix | needs_verification",
+         "commit": "abcdef1234"
+       }
+     ],
+     "checked": ["what you audited when the list is empty: e.g. error paths of X, test coverage of Y"]
+   }
+   \`\`\`
+   Every finding you fixed says \`fixed\` with its commit; anything you deliberately left says \`deferred\` or \`wont_fix\` with the reason in \`detail\`; anything you could not verify says \`needs_verification\`. An empty \`findings\` array is a valid, honest result \u2014 then \`checked\` must say what you looked at. Commit this file with your stage.
+5. Close with a \`## Handoff\` section: what you found (counts by severity), what you fixed, what you deliberately left, and what the next stage must verify.
+
+Handoff bar: checks pass on YOUR final commit; every fix is committed; \`REVIEW-FINDINGS.pack.json\` is committed and lists every finding with its resolution (an empty list says what you checked).`;
 var QA_PROMPT = `# Role: QA
 
 You are the final gate. You verify the delivered work against the acceptance criteria as a whole \u2014 end to end, the way a demanding user would \u2014 and produce the run's closing report.
 
 Method:
 1. Read the task and \`SPEC.pack.md\` (when present). Your contract is the acceptance criteria; without a spec, derive them from the task.
-2. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.
-3. Run the project's full checks (tests, lint, types, build) one final time.
-4. Write \`QA-REPORT.pack.md\` at the repo root: per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each), the checks' results, anything not verifiable in this environment (stated plainly), and a short "ready to ship?" conclusion.
-5. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.
+2. Read \`REVIEW-FINDINGS.pack.json\` (when present \u2014 the Reviewer's structured findings, also summarized in your handoff input). Every finding there is an item on YOUR checklist: a \`fixed\` one must be verified fixed without regression; a \`deferred\`/\`wont_fix\` one must be judged acceptable or escalated; a \`needs_verification\` one is yours to settle.
+3. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.
+4. Run the project's full checks (tests, lint, types, build) one final time.
+5. Write \`QA-REPORT.pack.md\` at the repo root with two sections: **Acceptance criteria** \u2014 per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each); **Review findings** \u2014 per finding id, verdict (\u2705 verified fixed / \u26A0\uFE0F still open / \u274C regressed \u2014 with evidence). Then the checks' results, anything not verifiable in this environment (stated plainly), and a short "ready to ship?" conclusion.
+6. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.
+7. Close with a \`## Handoff\` section: the ship/no-ship conclusion, the failed or open items by id, and what you could not verify.
 
-Handoff bar: the report is committed; every verdict carries evidence; the conclusion is honest about anything unverified.`;
+Handoff bar: the report is committed; every verdict carries evidence; every finding id from the Reviewer appears in the report; the conclusion is honest about anything unverified.`;
 
 // src/packs/registry.ts
 var PACK_REGISTRY = {
@@ -2674,7 +2701,9 @@ var PACK_REGISTRY = {
         skillIds: ["code-review", "code-naming"],
         prompt: REVIEWER_PROMPT,
         // Review-only: approving clean with no change is success, not a stall.
-        requiresCommit: false
+        requiresCommit: false,
+        // Leaves REVIEW-FINDINGS.pack.json — the next stage gets a list, not prose.
+        producesFindings: true
       }
     ]
   },
@@ -2705,7 +2734,9 @@ var PACK_REGISTRY = {
         skillIds: ["code-review", "code-naming"],
         prompt: REVIEWER_PROMPT,
         // Review-only: approving clean with no change is success, not a stall.
-        requiresCommit: false
+        requiresCommit: false,
+        // Leaves REVIEW-FINDINGS.pack.json — the next stage gets a list, not prose.
+        producesFindings: true
       },
       {
         role: "qa",
@@ -2735,8 +2766,140 @@ You are ONE specialist role in a multi-role pipeline running on this repository.
 - **Never leave the tree broken.** Run the project's checks before finishing when the project has them; your stage ends with a working tree the next role can build on.
 - **Do not push, force-push, or touch remotes** \u2014 the pipeline works locally; publishing is the user's call at the end.
 - **Never read, edit, or commit anything under \`.codeam/\`** \u2014 that is the pipeline's own ledger, not project code.
-- **Finish decisively.** When your stage's job is done and committed, say so in 2-4 lines (what you did, what you verified, anything the next stage should know) and stop. Don't ask "should I continue?" \u2014 the pipeline advances automatically.
-- **If you are genuinely blocked** (contradictory requirements, missing access), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.`;
+- **Finish with a \`## Handoff\` section.** When your stage's job is done and committed, end your reply with a heading \`## Handoff\` followed by 2-6 lines: what you did, what you verified, anything the next stage must know. That section \u2014 not the rest of your reply \u2014 is what the next role receives. Don't ask "should I continue?" \u2014 the pipeline advances automatically.
+- **If you need the user's decision** (contradictory requirements, a real product choice), ask ONE clear question and end your reply with 2-4 numbered options on their own lines (\`1. \u2026\`), then stop. The pipeline pauses until they answer in this conversation; keep working in it once they do, and commit as usual.
+- **If you are genuinely blocked** (missing access, a broken environment you cannot fix), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.`;
+
+// src/packs/findings.ts
+var SEVERITIES = /* @__PURE__ */ new Set([
+  "blocker",
+  "major",
+  "minor",
+  "nit"
+]);
+var RESOLUTIONS = /* @__PURE__ */ new Set([
+  "fixed",
+  "deferred",
+  "wont_fix",
+  "needs_verification"
+]);
+var TITLE_MAX = 200;
+var DETAIL_MAX = 1200;
+function parsePackFindings(raw) {
+  const text = stripFence(raw).trim();
+  if (text.length === 0) return { ok: false, error: "findings file is empty" };
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    const salvaged = salvageJson(text);
+    if (salvaged === null) return { ok: false, error: "findings file is not valid JSON" };
+    data = salvaged;
+  }
+  const container = Array.isArray(data) ? { findings: data } : data;
+  if (!isRecord(container) || !Array.isArray(container.findings)) {
+    return { ok: false, error: 'findings file has no "findings" array' };
+  }
+  const findings = [];
+  let dropped = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of container.findings) {
+    const f = coerceFinding(entry, findings.length + 1);
+    if (!f) {
+      dropped += 1;
+      continue;
+    }
+    if (seen.has(f.id)) f.id = `${f.id}-${findings.length + 1}`;
+    seen.add(f.id);
+    findings.push(f);
+    if (findings.length >= MAX_PACK_FINDINGS) break;
+  }
+  const truncated = container.findings.length - dropped - findings.length;
+  const checked = Array.isArray(container.checked) ? container.checked.filter((c) => typeof c === "string" && c.trim().length > 0).slice(0, 20) : void 0;
+  const notes = [];
+  if (dropped > 0) notes.push(`${dropped} malformed entr${dropped === 1 ? "y" : "ies"} dropped`);
+  if (truncated > 0)
+    notes.push(`list truncated to ${MAX_PACK_FINDINGS} (${truncated} more in the file)`);
+  return {
+    ok: true,
+    value: {
+      findings,
+      ...checked && checked.length > 0 ? { checked } : {},
+      ...notes.length > 0 ? { note: notes.join("; ") } : {}
+    }
+  };
+}
+function coerceFinding(entry, ordinal) {
+  if (!isRecord(entry)) return null;
+  const title = str(entry.title) ?? str(entry.summary);
+  if (!title) return null;
+  const id = str(entry.id) ?? `R${ordinal}`;
+  const severityRaw = (str(entry.severity) ?? "").toLowerCase();
+  const resolutionRaw = (str(entry.resolution) ?? str(entry.status) ?? "").toLowerCase().replace(/[\s-]+/g, "_");
+  const line = typeof entry.line === "number" && Number.isFinite(entry.line) && entry.line > 0 ? Math.floor(entry.line) : void 0;
+  const detail = str(entry.detail) ?? str(entry.description);
+  const file = str(entry.file) ?? str(entry.path);
+  const commit = str(entry.commit);
+  return {
+    id: id.slice(0, 32),
+    severity: SEVERITIES.has(severityRaw) ? severityRaw : "major",
+    title: title.slice(0, TITLE_MAX),
+    ...detail ? { detail: detail.slice(0, DETAIL_MAX) } : {},
+    ...file ? { file: file.slice(0, 300) } : {},
+    ...line !== void 0 ? { line } : {},
+    resolution: RESOLUTIONS.has(resolutionRaw) ? resolutionRaw : "needs_verification",
+    ...commit && /^[0-9a-f]{7,40}$/i.test(commit) ? { commit: commit.slice(0, 10) } : {}
+  };
+}
+function extractHandoffSection(reply) {
+  const lines = reply.split("\n");
+  const want = PACK_HANDOFF_HEADING.replace(/^#+\s*/, "").toLowerCase();
+  let start = -1;
+  let level = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = lines[i].match(/^\s{0,3}(#{1,4})\s+(.+?)\s*#*\s*$/);
+    if (m && m[2].trim().toLowerCase().replace(/[:.]+$/, "") === want) {
+      start = i;
+      level = m[1].length;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^\s{0,3}(#{1,6})\s+/);
+    if (m && m[1].length <= level) break;
+    body.push(lines[i]);
+  }
+  const text = body.join("\n").trim();
+  return text.length > 0 ? text : null;
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(v) {
+  return typeof v === "string" && v.trim().length > 0 ? v.trim() : void 0;
+}
+function stripFence(raw) {
+  const m = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  return m ? m[1] : raw;
+}
+function salvageJson(text) {
+  for (const [open, close] of [
+    ["{", "}"],
+    ["[", "]"]
+  ]) {
+    const a = text.indexOf(open);
+    const b = text.lastIndexOf(close);
+    if (a >= 0 && b > a) {
+      try {
+        return JSON.parse(text.slice(a, b + 1));
+      } catch {
+      }
+    }
+  }
+  return null;
+}
 
 // src/api-url.ts
 var DEFAULT_API_BASE_URL = "https://api.codeagent-mobile.com";
@@ -2982,10 +3145,13 @@ export {
   MANAGED_AGENT_SUBTITLE,
   MANAGED_PROVIDER_DISPLAY_NAMES,
   MANAGED_PROVIDER_IDS,
+  MAX_PACK_FINDINGS,
   MODEL_CONTEXT_WINDOW,
   MODEL_PRICING,
   OBSERVER_BRIDGE_PORT,
   PACK_ACTION_COMMAND,
+  PACK_FINDINGS_FILE,
+  PACK_HANDOFF_HEADING,
   PACK_REGISTRY,
   PACK_START_COMMAND,
   PACK_STATUS_COMMAND,
@@ -3013,6 +3179,7 @@ export {
   clampHopBudget,
   classifyStack,
   detectedIntegrationsFromDeps,
+  extractHandoffSection,
   getAgent,
   getContextWindow,
   getEnabledAgents,
@@ -3036,6 +3203,7 @@ export {
   isSkillId,
   normalizeAgentId,
   normalizeGuardrailPolicy,
+  parsePackFindings,
   publicToInternal,
   recommendForDeps,
   renderToLines,