@useshifu/coding-harness 0.2.2 → 0.2.5

package/README.md

@@ -7,13 +7,13 @@ npx @useshifu/coding-harness install --harness codex
 npx @useshifu/coding-harness connect --harness codex
 ```
 
-`connect` and `sync` each ask for confirmation. The Codex connector has no lifecycle hooks and never uploads in the background. Claude Code and OpenCode time-window discovery are not available yet.
+`connect` and `sync` each ask for confirmation. The connector has no lifecycle hooks and never uploads in the background. Codex and OpenCode support local time-window discovery and review; Claude Code does not yet.
 
-When asked to sync, Codex discovers unsynced user turns from the last 24 hours by default. A user can choose 48 or 72 hours instead. Discovery reports only opaque session references, timestamps, and unsynced turn ranges; it does not send transcript content. `blockedSessions` lists recently changed sessions whose next unsynced turn is older than the chosen window. Those older contiguous backlogs are not silently included; the user can explicitly select a session and review it with `--all`.
+When asked to sync, Codex and OpenCode discover unsynced user turns from the last 24 hours by default. A user can choose 48 or 72 hours instead. Discovery reports only opaque session references, timestamps, and unsynced turn ranges; it does not send transcript content. `blockedSessions` lists recently changed sessions whose next unsynced turn is older than the chosen window. Those older contiguous backlogs are not silently included; the user can explicitly select a session and review it with `--all`.
 
 ```sh
-npx @useshifu/coding-harness sessions --harness codex --hours 24
-npx @useshifu/coding-harness review --harness codex --session-ref opaque-session-id
+npx @useshifu/coding-harness sessions --harness <codex|opencode> --hours 24
+npx @useshifu/coding-harness review --harness <codex|opencode> --session-ref opaque-session-id
 ```
 
 `review` reads the next contiguous segment of at most 12 unsynced turns locally. Pass the selected `--hours` value to `review` as well; `--all` is reserved for a specifically selected session's older backlog. It shows assistant final notes, candidate work items, and a draft that leaves required sync and work-item titles blank for the reviewer. Candidates are suggestions, not proof or guaranteed redaction. Candidate scope is left unset until a reviewer chooses the smallest supported level. If a segment has more than 64 candidates, rerun `sessions` and `review` with `--turns 1` to narrow it before syncing. Review each work title, detail, and area, prepare any verification, and preserve an item's `itemRef` when a later segment revises the same work. User-message records are omitted, but assistant notes may quote sensitive material. Nothing is uploaded by this command. Repeat discovery after each accepted segment to continue the delta.
@@ -26,4 +26,8 @@ printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"t
 
 The server stores each approved sync title and summary, plus every redacted work-item title and statement as a separate claim with its scope, optional area and item reference, cited verification, and source receipt. Uncited verification wording, standalone decisions, raw assistant notes, and transcripts are not retained as claim text. `area`, `itemRef`, and `verificationRefs` are optional; citing a verification item applies only to that work item and is displayed separately from its work statement. A decision becomes a claim only when it is included as an `evidence` item with `kind: "decision"`. At least one reviewed work item is required to advance a checkpoint. The complete cross-component contract is in [coding-session-sync-contract.md](../../docs/coding-session-sync-contract.md).
 
+## Review quality
+
+Write each sync as a concise technical record that will remain useful after the raw session is unavailable. Separate architecture, implementation, security controls, rollout, and user-facing work when they have distinct boundaries. Describe the mechanism, boundary, and material constraint for each item; state known limits plainly. Put material architecture, security, and rollout choices in `decision` evidence if they should become claims. Keep tests and operational checks in `verification`, citing them from the work item they support. Do not claim impact, ownership, or outcomes without direct support.
+
 The default API URL is `https://api.useshifu.com`. Override it during local or self-hosted use with `--api-url` on `connect`, or `SHIFU_API_URL`.

package/bin/shifu-harness.js

@@ -3,6 +3,7 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const { execFileSync } = require("node:child_process");
 const readline = require("node:readline/promises");
 const tty = require("node:tty");
 
@@ -50,6 +51,73 @@ function codexSessionsRoot() {
   return process.env.SHIFU_CODEX_SESSIONS_ROOT || path.join(os.homedir(), ".codex", "sessions");
 }
 
+function opencodeQuery(query) {
+  if (process.env.SHIFU_OPENCODE_DB && !process.env.SHIFU_OPENCODE_BIN) {
+    try {
+      const sqliteOutput = execFileSync("sqlite3", ["-json", process.env.SHIFU_OPENCODE_DB, query], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      return JSON.parse(sqliteOutput);
+    } catch {
+      throw new Error("Could not read OpenCode session metadata. Ensure the opencode command is installed and its local database is available.");
+    }
+  }
+  const temporary = path.join(os.tmpdir(), `shifu-opencode-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, "w");
+    execFileSync(process.env.SHIFU_OPENCODE_BIN || "opencode", ["db", query, "--format", "json"], {
+      stdio: ["ignore", fd, "pipe"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    fs.closeSync(fd);
+    fd = undefined;
+    return JSON.parse(fs.readFileSync(temporary, "utf8"));
+  } catch {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch {}
+      fd = undefined;
+    }
+    const dbPath = process.env.SHIFU_OPENCODE_DB || path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"), "opencode", "opencode.db");
+    if (fs.existsSync(dbPath)) {
+      try {
+        const sqliteOutput = execFileSync("sqlite3", ["-json", dbPath, query], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          maxBuffer: 64 * 1024 * 1024,
+        });
+        return JSON.parse(sqliteOutput);
+      } catch {}
+    }
+    throw new Error("Could not read OpenCode session metadata. Ensure the opencode command is installed and its local database is available.");
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch {}
+    }
+    try { fs.unlinkSync(temporary); } catch {}
+  }
+}
+
+function opencodeSessions(rows) {
+  const sessions = new Map();
+  for (const row of rows) {
+    if (typeof row.sessionRef !== "string" || !Number.isFinite(row.startedAt) || !Number.isFinite(row.updatedAt) || !Number.isFinite(row.turnAt)) continue;
+    const session = sessions.get(row.sessionRef) || { sessionRef: row.sessionRef, startedAt: new Date(row.startedAt).toISOString(), updatedAt: new Date(row.updatedAt).toISOString(), turnCount: 0, turnTimes: [] };
+    session.turnCount += 1;
+    session.turnTimes.push(new Date(row.turnAt).toISOString());
+    sessions.set(row.sessionRef, session);
+  }
+  return [...sessions.values()];
+}
+
+function localSessions(harness) {
+  if (harness === "codex") return sessionFiles(codexSessionsRoot()).map(codexSession).filter(Boolean);
+  if (harness === "opencode") return opencodeSessions(opencodeQuery("SELECT s.id AS sessionRef, s.time_created AS startedAt, s.time_updated AS updatedAt, m.time_created AS turnAt FROM session s JOIN message m ON m.session_id = s.id WHERE json_extract(m.data, '$.role') = 'user' ORDER BY s.time_updated, m.time_created"));
+  throw new Error("Session discovery is currently available for Codex and OpenCode only.");
+}
+
 function requireHarness(value) {
   if (!Object.hasOwn(HARNESS_NAMES, value)) throw new Error("Choose --harness codex, claude_code, or opencode.");
   return value;
@@ -203,6 +271,46 @@ function codexReview(file, fromTurn, toTurn) {
   return { sessionRef, turnCount: turn, notes };
 }
 
+function opencodeReview(sessionRef, fromTurn, toTurn) {
+  const rows = opencodeQuery(`SELECT m.id AS messageId, m.time_created AS createdAt, json_extract(m.data, '$.role') AS role, json_extract(m.data, '$.finish') AS finish, p.data AS part FROM message m LEFT JOIN part p ON p.message_id = m.id WHERE m.session_id = ${JSON.stringify(sessionRef)} ORDER BY m.time_created, p.id`);
+  const messages = new Map();
+  for (const row of rows) {
+    const message = messages.get(row.messageId) || { role: row.role, finish: row.finish, parts: [] };
+    if (typeof row.part === "string") {
+      try {
+        const part = JSON.parse(row.part);
+        if (part.type === "text" && typeof part.text === "string") message.parts.push(part.text);
+      } catch {}
+    }
+    messages.set(row.messageId, message);
+  }
+  let turn = 0;
+  const turnMessages = new Map();
+  for (const message of messages.values()) {
+    if (message.role === "user") {
+      turn += 1;
+      turnMessages.set(turn, []);
+      continue;
+    }
+    if (message.role === "assistant" && turn > 0) {
+      turnMessages.get(turn).push(message);
+    }
+  }
+  const notes = [];
+  for (const [t, msgs] of turnMessages.entries()) {
+    if (t < fromTurn || t > toTurn) continue;
+    let candidates = msgs.filter((m) => m.finish === "stop" || (m.finish && m.finish !== "tool-calls"));
+    if (candidates.length === 0) {
+      candidates = msgs.filter((m) => m.parts.length > 0).slice(-1);
+    }
+    for (const m of candidates) {
+      const note = m.parts.join("\n").trim();
+      if (note) notes.push({ turn: t, note });
+    }
+  }
+  return { sessionRef, turnCount: turn, notes };
+}
+
 function reviewCandidates(notes) {
   const candidates = [];
   const seen = new Set();
@@ -224,15 +332,12 @@ function reviewCandidates(notes) {
 }
 
 function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, selectedRef, includeOlder = false) {
-  if (harness !== "codex") throw new Error("Session discovery is currently available for Codex only.");
   if (![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
   const since = Date.now() - hours * 3_600_000;
   const state = readState(harness);
   const sessions = new Map();
-  for (const session of sessionFiles(codexSessionsRoot())
-    .map(codexSession)
-    .filter(Boolean)
+  for (const session of localSessions(harness)
     .filter((session) => selectedRef ? session.sessionRef === selectedRef : Date.parse(session.updatedAt) >= since)) {
     const existing = sessions.get(session.sessionRef);
     sessions.set(session.sessionRef, existing ? {
@@ -353,16 +458,31 @@ function removeCodexHooks() {
 function installDestination(harness) {
   if (harness === "codex") return path.join(os.homedir(), ".codex", "skills", "shifu-sync");
   if (harness === "claude_code") return path.join(os.homedir(), ".claude", "skills", "shifu-sync");
-  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "commands", "shifu-sync.md");
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "skills", "shifu-sync");
 }
 
 function install(harness) {
   copyRunner();
-  const destination = installDestination(harness);
   if (harness === "opencode") {
-    fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
-    fs.copyFileSync(path.join(__dirname, "..", "commands", "shifu-sync.md"), destination);
+    const configDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    const skillDest = path.join(configDir, "opencode", "skills", "shifu-sync");
+    fs.mkdirSync(skillDest, { recursive: true, mode: 0o700 });
+    const skillContent = fs.readFileSync(path.join(__dirname, "..", "skills", "shifu-sync", "SKILL.md"), "utf8")
+      .replaceAll('"codex"', '"opencode"')
+      .replaceAll("--harness codex", "--harness opencode")
+      .replaceAll("Codex", "OpenCode")
+      .replaceAll("npx @useshifu/coding-harness", `"${process.execPath}" "${installedRunnerPath()}"`);
+    fs.writeFileSync(path.join(skillDest, "SKILL.md"), skillContent, { mode: 0o600 });
+
+    const commandContent = fs.readFileSync(path.join(__dirname, "..", "commands", "shifu-sync.md"), "utf8")
+      .replaceAll("npx @useshifu/coding-harness", `"${process.execPath}" "${installedRunnerPath()}"`);
+    for (const folder of ["command", "commands"]) {
+      const commandDir = path.join(configDir, "opencode", folder);
+      fs.mkdirSync(commandDir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(path.join(commandDir, "shifu-sync.md"), commandContent, { mode: 0o600 });
+    }
   } else {
+    const destination = installDestination(harness);
     copyDirectory(path.join(__dirname, "..", "skills", "shifu-sync"), destination);
     const skill = path.join(destination, "SKILL.md");
     const content = fs.readFileSync(skill, "utf8")
@@ -479,51 +599,48 @@ function sessions(harness) {
 }
 
 function review(harness) {
-  if (harness !== "codex") throw new Error("Session review is currently available for Codex only.");
   readConfig(harness);
   const sessionRef = option("--session-ref");
-  if (typeof sessionRef !== "string" || sessionRef.length < 8) throw new Error("Provide an opaque Codex --session-ref from the sessions command.");
+  if (typeof sessionRef !== "string" || sessionRef.length < 8) throw new Error(`Provide an opaque ${HARNESS_NAMES[harness]} --session-ref from the sessions command.`);
   const state = readState(harness);
   const fromTurn = (state.sessions[sessionRef]?.lastSyncedTurn || 0) + 1;
-  const matchingFiles = sessionFiles(codexSessionsRoot())
-    .map((file) => ({ file, session: codexSession(file) }))
-    .filter(({ session }) => session?.sessionRef === sessionRef)
-    .sort((left, right) => right.session.turnCount - left.session.turnCount || right.session.updatedAt.localeCompare(left.session.updatedAt));
-  const selected = matchingFiles[0];
-  if (!selected) throw new Error("No local Codex session matches this reference.");
+  const selected = localSessions(harness).filter((session) => session.sessionRef === sessionRef)
+    .sort((left, right) => right.turnCount - left.turnCount || right.updatedAt.localeCompare(left.updatedAt))[0];
+  if (!selected) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches this reference.`);
   const hours = numberOption("--hours", 24);
   if (![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
-  if (!hasFlag("--all") && !(Date.parse(selected.session.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000)) {
+  if (!hasFlag("--all") && !(Date.parse(selected.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000)) {
     throw new Error("This session's next unsynced turn predates the selected window. Ask for this specific session and use --all to review its backlog.");
   }
   const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
-  const toTurn = Math.min(selected.session.turnCount, fromTurn + turns - 1);
-  if (fromTurn > toTurn) throw new Error("This Codex session has no unsynced turns to review.");
-  const { notes } = codexReview(selected.file, fromTurn, toTurn);
+  const toTurn = Math.min(selected.turnCount, fromTurn + turns - 1);
+  if (fromTurn > toTurn) throw new Error(`This ${HARNESS_NAMES[harness]} session has no unsynced turns to review.`);
+  const { notes } = harness === "codex" ? codexReview(sessionFiles(codexSessionsRoot()).map((file) => ({ file, session: codexSession(file) })).filter(({ session }) => session?.sessionRef === sessionRef).sort((left, right) => right.session.turnCount - left.session.turnCount)[0].file, fromTurn, toTurn) : opencodeReview(sessionRef, fromTurn, toTurn);
   const candidates = reviewCandidates(notes);
   console.log(JSON.stringify({
     sessionRef,
     fromTurn,
     toTurn,
-    oldestUnsyncedAt: selected.session.turnTimes[fromTurn - 1] || null,
+    oldestUnsyncedAt: selected.turnTimes[fromTurn - 1] || null,
     source: "Local assistant final notes for unsynced user turns. Candidates are suggestions, not verified or guaranteed redacted; inspect them before constructing a Shifu payload.",
     notes,
     candidates,
     draft: { title: null, summary: null, evidence: candidates.map((candidate) => ({ ...candidate, title: null })) },
     candidateOverflow: candidates.length > MAX_EVIDENCE_ITEMS,
-    remainingTurns: selected.session.turnCount - toTurn,
+    remainingTurns: selected.turnCount - toTurn,
   }, null, 2));
 }
 
 async function main() {
   const command = process.argv[2];
+  const subCommand = process.argv[3];
   const harness = requireHarness(option("--harness"));
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
   if (command === "sync") return sync(harness);
   if (command === "status") return status(harness);
-  if (command === "sessions") return sessions(harness);
+  if (command === "sessions" || command === "discover" || (command === "session" && (subCommand === "discover" || subCommand === "list" || !subCommand || subCommand.startsWith("-")))) return sessions(harness);
   if (command === "review") return review(harness);
   throw new Error("Use install, connect, status, sessions, review, or sync.");
 }
@@ -537,4 +654,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { codexReview, codexSession, configPath, finalAssistantNote, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, statePath, textIsSafe, unsyncedCodexSessions, validSyncReceipt, validateSync };
+module.exports = { codexReview, codexSession, configPath, finalAssistantNote, install, installDestination, localSessions, opencodeQuery, opencodeReview, opencodeSessions, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, statePath, textIsSafe, unsyncedCodexSessions, validSyncReceipt, validateSync };

package/commands/shifu-sync.md

@@ -2,10 +2,46 @@
 description: Prepare a reviewed, redacted incremental Shifu sync and ask for confirmation.
 ---
 
-Use the Shifu reviewed-sync process for the current OpenCode session. Never upload automatically or include raw transcript content. First explain what the unsynced incremental segment contains and show the exact JSON payload. Ask the user to confirm. Only after confirmation, pipe the reviewed payload to:
+Use the Shifu reviewed-sync process for OpenCode only after an explicit user request. Never upload automatically or include raw transcript content. Before acting, say whether you will connect or sync and ask for confirmation.
+
+For a sync request, use the time window the user names. If none is named, state that you will use the last 24 hours. The only supported windows are 24, 48, and 72 hours.
+
+1. Run `npx @useshifu/coding-harness sessions --harness opencode --hours <24|48|72>`.
+2. Use every returned opaque `sessionRef`, `fromTurn`, and `toTurn`. A segment contains at most 12 user turns.
+3. Do not upload a `blockedSessions` entry automatically. Its next unsynced turn predates the selected window. Only if the user specifically chooses that session, run discovery and review with `--session-ref <sessionRef> --all`.
+4. For each selected segment, run `npx @useshifu/coding-harness review --harness opencode --session-ref <sessionRef> --hours <24|48|72>`. Review returns local assistant notes and suggested candidates only. It never returns user prompts.
+5. If review reports more than 64 candidates, rerun discovery and review with `--turns 1`. Repeat discovery after every accepted segment until the selected pending delta is exhausted.
+6. Redact the reviewed assistant notes, show the exact JSON payload, and ask the user to confirm. Only after confirmation, pipe the payload to:
 
 ```sh
 npx @useshifu/coding-harness sync --harness opencode
 ```
 
-The payload must contain `harness`, an opaque `sessionRef`, a contiguous `fromTurn`/`toTurn` range of at most 12 turns, a concise redacted sync `title`, a redacted `summary`, 1–64 redacted `evidence` work items (`title`, `kind`, `statement`, `scope`), up to 16 redacted `verification` items, up to 16 redacted `decisions`, and `redactionVersion: 3`. Evidence describes the work itself; verification records how it was checked. Scope must be one of `unit`, `module`, `service`, `system`, or `product` and must be reviewed rather than guessed from the candidate. Replace names, paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions.
+The payload must contain `harness: "opencode"`, an opaque `sessionRef`, the returned contiguous `fromTurn`/`toTurn` range, a concise redacted sync `title`, a redacted `summary`, 1–64 redacted `evidence` work items (`title`, `kind`, `statement`, `scope`), up to 16 redacted `verification` items, up to 16 redacted `decisions`, and `redactionVersion: 3`. Evidence describes the work itself; verification records how it was checked. Scope must be one of `unit`, `module`, `service`, `system`, or `product` and must be reviewed rather than guessed from the candidate. Replace names, repository identifiers, file paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions. Never invent missing details or alter the returned turn range.
+
+Write a concise but useful durable technical record. Split architecture, implementation, security controls, configuration or rollout, and user-facing behaviour into separate evidence items when they have different boundaries. Each item should state the mechanism, responsible boundary, and material constraint. Record a material architecture, security, or rollout choice as `kind: "decision"` evidence when it should persist; do not treat the standalone `decisions` list as a durable work item. State known security limits plainly. Keep tests, builds, reviews, deployment checks, and other proof in `verification`, and cite relevant verification entries from evidence with `verificationRefs`. Use the smallest true scope and do not claim impact, ownership, or outcomes not supported by the reviewed work.
+
+Use this structure:
+
+```json
+{
+  "harness": "opencode",
+  "sessionRef": "opaque-session-id",
+  "fromTurn": 1,
+  "toTurn": 12,
+  "title": "Hardened connector checkpoints",
+  "summary": "Implemented a narrow change and checked the relevant behaviour.",
+  "evidence": [{"kind": "implementation", "title": "Added checkpoint recovery", "statement": "Implemented a focused connector change.", "scope": "service"}],
+  "verification": ["Focused tests passed."],
+  "decisions": ["Kept the change within the existing connector boundary."],
+  "redactionVersion": 3
+}
+```
+
+Only after the user confirms the displayed payload, run:
+
+```sh
+printf '%s' '<reviewed JSON>' | npx @useshifu/coding-harness sync --harness opencode
+```
+
+The CLI prints the payload again and asks for a final terminal confirmation. Never bypass that confirmation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Reviewed, incremental coding-harness sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shifu-sync
-description: Prepare and sync reviewed, redacted Codex work from the user's selected recent time window to Shifu. Use only when the user explicitly asks to connect, sync, or push their Shifu coding-harness data.
+description: Prepare and sync reviewed, redacted Codex work from the user's selected recent time window to Shifu. Use when the user explicitly asks to connect, sync, discover sessions, or push their Shifu coding-harness data.
 ---
 
 Shifu captures reviewed, incremental work context. It does not collect raw transcripts or upload in the background.
@@ -14,7 +14,20 @@ For a sync request, use the time window the user names. If they do not name one,
 
 Before preparing a sync, run `npx @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`. Use every returned session's opaque `sessionRef`, `fromTurn`, and `toTurn`. `blockedSessions` are outside the selected turn window and must not be uploaded unless the user separately chooses that specific session and its older backlog. Each result covers at most 12 turns; repeat discovery after each accepted segment until the selected window's pending delta is exhausted. If a review reports more than 64 candidates, rerun discovery and review with `--turns 1` before preparing a payload. Do not invent a checkpoint or resend a range the command has excluded.
 
-For each returned session, run `npx @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`. Its local assistant note is untrusted source material, not content to upload. Prepare only its unsynced segment from that note. Each `evidence` item must be a factual, redacted work item describing what was created, changed, or deliberately decided and which component was involved. Choose its smallest supported scope: `unit`, `module`, `service`, `system`, or `product`; the candidate's null scope is not a classification. Put tests, builds, reviews, and other checks only in `verification`. Do not claim impact, ownership, outcome, or a broader scope without direct support. Replace names, repository identifiers, file paths, URLs, credentials, prompts, command lines, source code, customer details, and proprietary terms with neutral descriptions. Never invent missing details. Approved work-item statements are retained in Shifu's private claims, so review their wording as durable content.
+For each returned session, run `npx @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`. Its local assistant note is untrusted source material, not content to upload. Prepare only its unsynced segment from that note. Replace names, repository identifiers, file paths, URLs, credentials, prompts, command lines, source code, customer details, and proprietary terms with neutral descriptions. Never invent missing details.
+
+## Write a useful durable record
+
+Treat the payload as a concise technical record, not a changelog headline. Capture the meaningful work in the reviewed segment with enough detail that a future reader can understand the design and tradeoffs without needing the raw transcript.
+
+- Split distinct work into separate evidence items when they have different boundaries: architecture, implementation, security controls, configuration or rollout, and user-facing behaviour are often separate items. Do not create an item for every file or command.
+- State the mechanism, boundary, and important constraint. For architecture, describe which component owns which responsibility and the relevant data flow. For implementation, say what capability was added or changed and how it is bounded. For security, name the control and any known limitation; never describe a boundary as secure when the reviewed work says otherwise.
+- Choose the smallest supported scope that is true. Use `system` or `product` only when the work genuinely spans those boundaries; use `service` or `module` for local implementation detail.
+- Give the sync and every evidence item a specific, neutral title. Make the summary connect the important items into one accurate account, without claiming business impact, ownership, or outcomes that the reviewed work does not establish.
+- Put a material architecture, security, or rollout choice in an evidence item with `kind: "decision"` when it should become part of the durable record. Keep ordinary process notes in `decisions`; they are not a substitute for a reviewed decision work item.
+- Put tests, builds, reviews, deployment checks, and other proof only in `verification`. Cite the relevant verification entries from the evidence item when the payload format supports `verificationRefs`.
+
+Use detail proportionate to the work: retain high-level design, low-level controls, and unresolved risks when they materially affect the result, while omitting routine implementation noise. Approved work-item titles and statements are retained in Shifu's private claims, so review their wording as durable content.
 
 Do not install or rely on lifecycle hooks or background reminders. A sync is always initiated by an explicit user request.