@useshifu/coding-harness 0.2.0 → 0.2.1

package/README.md

@@ -16,14 +16,14 @@ npx @useshifu/coding-harness sessions --harness codex --hours 24
 npx @useshifu/coding-harness review --harness codex --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 and all candidate work items; these 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 statement 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.
+`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.
 
 To submit a reviewed segment, pipe the exact payload to `sync`. The CLI prints it, asks again, and only then sends it to Shifu. Successful responses advance a local checkpoint; the server rejects out-of-order or changed retries.
 
 ```sh
-printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":8,"summary":"Implemented a focused change and checked the result.","evidence":[{"kind":"implementation","statement":"Implemented a focused connector change.","scope":"service","area":"connector","itemRef":"work_1","verificationRefs":[0]}],"verification":["Focused tests passed."],"decisions":[],"redactionVersion":2}' | npx @useshifu/coding-harness sync --harness codex
+printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":8,"title":"Hardened connector checkpoints","summary":"Implemented a focused change and checked the result.","evidence":[{"kind":"implementation","title":"Added checkpoint recovery","statement":"Implemented a focused connector change.","scope":"service","area":"connector","itemRef":"work_1","verificationRefs":[0]}],"verification":["Focused tests passed."],"decisions":[],"redactionVersion":3}' | npx @useshifu/coding-harness sync --harness codex
 ```
 
-The server stores each approved, redacted work-item statement as a separate claim with its scope, optional area and item reference, cited verification, and source receipt. Summary, 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).
+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).
 
 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

@@ -19,14 +19,16 @@ const UNSAFE_CODE_PATTERN = /\b(?:func|class|interface|struct|package|import|sel
 const CREDENTIAL_ASSIGNMENT_PATTERN = /\b(?:token|secret|password|api[_-]?key)\s*[:=]\s*\S+/i;
 const CLOUD_CREDENTIAL_PATTERN = /\bAKIA[0-9A-Z]{16}\b|AIza[0-9A-Za-z_-]{20,}/;
 const EVIDENCE_KINDS = new Set(["implementation", "decision"]);
-const EVIDENCE_FIELDS = new Set(["kind", "statement", "scope", "area", "itemRef", "verificationRefs"]);
-const SYNC_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "summary", "evidence", "verification", "decisions", "redactionVersion"]);
+const EVIDENCE_FIELDS = new Set(["kind", "title", "statement", "scope", "area", "itemRef", "verificationRefs"]);
+const SYNC_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "title", "summary", "evidence", "verification", "decisions", "redactionVersion"]);
 const SCOPE_LEVELS = new Set(["unit", "module", "service", "system", "product"]);
 const WORK_AREAS = new Set(["architecture", "api", "backend", "connector", "database", "documentation", "frontend", "performance", "security", "testing", "tooling"]);
 const ITEM_REF_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
 const MAX_EVIDENCE_ITEMS = 64;
 const MAX_SYNC_ITEMS = 16;
 const MAX_TURNS_PER_SEGMENT = 12;
+const MAX_TITLE_LENGTH = 160;
+const MAX_WORK_DETAIL_LENGTH = 600;
 
 function configRoot() {
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
@@ -207,9 +209,9 @@ function reviewCandidates(notes) {
   for (const [noteIndex, { turn, note }] of notes.entries()) {
     for (const [lineIndex, line] of note.split("\n").entries()) {
       const statement = line.trim().replace(/^[-*]\s+/, "");
-      const kind = /^(decided|chose|selected)\b/i.test(statement) ? "decision"
-        : /^(implemented|added|built|fixed|changed|created|completed)\b/i.test(statement) ? "implementation" : undefined;
-      if (!kind || !textIsSafe(statement, 240) || seen.has(`${kind}:${statement}`)) continue;
+      if (!textIsSafe(statement, MAX_WORK_DETAIL_LENGTH) || /\b(?:tests?|checks?|build|lint|review)\b.*\b(?:passed|pass|completed|succeeded)\.?$/i.test(statement)) continue;
+      const kind = /^(decided|chose|selected|kept|rejected)\b/i.test(statement) ? "decision" : "implementation";
+      if (seen.has(`${kind}:${statement}`)) continue;
       seen.add(`${kind}:${statement}`);
       const itemRef = `t${turn}_n${noteIndex + 1}_l${lineIndex + 1}`;
       const areas = [...WORK_AREAS].filter((area) => new RegExp(`\\b${area}\\b`, "i").test(statement));
@@ -395,9 +397,10 @@ function validateSync(input, harness) {
   if (!input || Object.keys(input).some((field) => !SYNC_FIELDS.has(field))) throw new Error("Remove unsupported fields from the reviewed sync payload.");
   if (!input || input.harness !== harness || typeof input.sessionRef !== "string" || !textIsSafe(input.sessionRef, 200) || input.sessionRef.length < 8) throw new Error("Add the current opaque sessionRef before syncing.");
   if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn || input.toTurn - input.fromTurn >= MAX_TURNS_PER_SEGMENT) throw new Error("Use a valid incremental range of at most 12 turns.");
+  if (input.redactionVersion === 3 && !textIsSafe(input.title, MAX_TITLE_LENGTH)) throw new Error("Add a concise, redacted title for this reviewed sync.");
   if (!textIsSafe(input.summary, 1200)) throw new Error("The summary is empty, too long, or contains sensitive content. Redact it before syncing.");
-  if (!Array.isArray(input.evidence) || input.evidence.length < 1 || input.evidence.length > MAX_EVIDENCE_ITEMS || !input.evidence.every((item) => item && EVIDENCE_KINDS.has(item.kind) && SCOPE_LEVELS.has(item.scope) && textIsSafe(item.statement, 240))) {
-    throw new Error(`evidence must contain 1-${MAX_EVIDENCE_ITEMS} redacted work items with kind, statement, and scope.`);
+  if (!Array.isArray(input.evidence) || input.evidence.length < 1 || input.evidence.length > MAX_EVIDENCE_ITEMS || !input.evidence.every((item) => item && EVIDENCE_KINDS.has(item.kind) && SCOPE_LEVELS.has(item.scope) && (input.redactionVersion !== 3 || textIsSafe(item.title, MAX_TITLE_LENGTH)) && textIsSafe(item.statement, MAX_WORK_DETAIL_LENGTH))) {
+	throw new Error(`evidence must contain 1-${MAX_EVIDENCE_ITEMS} redacted work items with title, detail, kind, and scope.`);
   }
   for (const field of ["verification", "decisions"]) {
     if (!Array.isArray(input[field]) || input[field].length > MAX_SYNC_ITEMS || !input[field].every((item) => textIsSafe(item, 240))) throw new Error(`${field} must contain at most ${MAX_SYNC_ITEMS} redacted statements.`);
@@ -411,7 +414,7 @@ function validateSync(input, harness) {
       item.verificationRefs.every((ref) => Number.isInteger(ref) && ref >= 0 && ref < input.verification.length))))) {
     throw new Error("Each work item must use a supported area, safe itemRef, and distinct indexes into verification.");
   }
-  if (input.redactionVersion !== 2) throw new Error("Use redactionVersion 2.");
+  if (input.redactionVersion !== 2 && input.redactionVersion !== 3) throw new Error("Use redactionVersion 3 for new reviewed syncs.");
 }
 
 function validSyncReceipt(receipt, input) {
@@ -507,6 +510,7 @@ function review(harness) {
     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,
   }, null, 2));

package/commands/shifu-sync.md

@@ -8,4 +8,4 @@ Use the Shifu reviewed-sync process for the current OpenCode session. Never uplo
 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 `summary`, 1–64 redacted `evidence` work items (`kind`, `statement`, `scope`), up to 16 redacted `verification` items, up to 16 redacted `decisions`, and `redactionVersion: 2`. 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`, 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.

package/package.json

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

package/skills/shifu-sync/SKILL.md

@@ -26,11 +26,12 @@ Use this structure:
   "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", "statement": "Implemented a focused connector change.", "scope": "service"}],
+  "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": 2
+  "redactionVersion": 3
 }
 ```