@useshifu/coding-harness 0.3.12 → 0.3.14

package/README.md

@@ -36,6 +36,10 @@ Version `0.3.11` adds rolling days-based windows and explicit force replacement
 
 Version `0.3.12` makes force sync independent of local and server checkpoints, creates missing work, and protects automatic retries from overwriting a newer force sync. Deploy backend migrations 049 and 050 before using it.
 
+Version `0.3.13` requires reviewed evidence for force sync. Empty replacements fail before changing existing work, and the harness instructions require semantic review of final notes instead of the scheduled keyword projection.
+
+Version `0.3.14` instructs the LLM to backfill the last 15 days of eligible sessions after the first successful connection, without a separate approval question. Interrupted initial backfills resume from accepted checkpoints; upgrades and key replacement alone do not trigger another backfill. The saved approval policy and schedule stay unchanged.
+
 ```sh
 npx --yes @useshifu/coding-harness status --harness codex
 npx --yes @useshifu/coding-harness sessions --harness codex --hours 24
@@ -81,7 +85,7 @@ The AI Profile page shows detected categories, model and thinking labels, and Je
 
 The connection endpoint returns `recommendedPackageVersion`, pinned to a published release. Before `sync`, `sync-files`, `approve`, or `scheduled-sync`, the runner compares its embedded release version with that property. An older runner installs the exact recommended release through npm and resumes the original command with the updated runner. Equal or newer runners continue unchanged. Explicitly recommended major releases follow the same comparison rule. Missing or invalid recommendations, connection failures, and npm failures do not block sync. The connection, pending work, checkpoints, and schedule are preserved.
 
-This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.12 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
+This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.14 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
 
 ## Force sync local work
 
@@ -89,6 +93,8 @@ An explicit force request selects local work independently of both local and ser
 
 1. Discover ranges with `sessions --harness codex --days 3 --force` (or a requested hours/count selection). Keep that initial target list fixed. Complete stored ranges touching selected turns are preserved, including older turns across a window boundary; uncovered selected turns are split into ranges of at most 12.
 2. Re-review each range with `review --harness codex --session-ref <sessionRef> --days 3 --force --from-turn <fromTurn> --to-turn <toTurn>`. The original local turns must exist. Explicit backfill/count selections use `--all`. No old receipt ID is required.
-3. Prepare and redact the payload again, keeping the exact session reference and turn range and adding `force: true`. Pipe it to `sync --harness codex --force`, following the saved manual/automatic approval policy.
+3. Have the coding harness read the final notes semantically and prepare meaningful redacted evidence about attributable work. Preserve supported technologies, patterns, problem, approach, and verified results, including work described with bold Markdown actions or inline-code technology names. Keep the exact session reference and turn range and add `force: true`. Pipe it to `sync --harness codex --force`, following the saved manual/automatic approval policy.
+
+Force requires at least one supported evidence item. Do not use the unattended `payloadForSegment` keyword projection, empty evidence, or a title-only payload for force. When final notes support no work items, report the range as not replaced; its existing work and checkpoints stay untouched. Ordinary scheduled sync can still accept a claim-free checkpoint.
 
 Missing local turns are reported in `unavailableSegments`. A partial overlap with accepted work is rejected; re-discover and re-review complete ranges before retrying. Automatic retries preserve the accepted result even if another force sync finishes meanwhile. A new invocation is a new explicit force request. Existing conversations retain their context; start a new chat in Shifu to use the latest context.

package/bin/shifu-harness.js

@@ -39,7 +39,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
-const RUNNER_VERSION = "0.3.12";
+const RUNNER_VERSION = "0.3.14";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -786,6 +786,7 @@ function safeActivityEvidence(notes) {
 }
 
 function payloadForSegment(harness, segment) {
+  if (segment.force || segment.supersedesSyncId) throw new Error("Force sync requires reviewing final notes and preparing meaningful redacted evidence; do not use the unattended payload projection.");
   const { notes } = reviewSegment(harness, segment.sessionRef, segment.fromTurn, segment.toTurn);
   const evidence = safeActivityEvidence(notes);
   const title = evidence.length ? evidence[0].title : "No supported work identified";
@@ -1335,7 +1336,9 @@ function validateSync(input, harness) {
   if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn || input.toTurn > 1_000_000 || 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.");
-  const minimumEvidence = input.redactionVersion >= REDACTION_VERSION ? 0 : 1;
+  const forced = input.force || Boolean(input.supersedesSyncId);
+  if (forced && Array.isArray(input.evidence) && input.evidence.length === 0) throw new Error("Force sync has no supported evidence. Re-review the final notes and prepare meaningful redacted work items; existing work and checkpoints were left untouched.");
+  const minimumEvidence = forced || input.redactionVersion < REDACTION_VERSION ? 1 : 0;
   if (!Array.isArray(input.evidence) || input.evidence.length < minimumEvidence || input.evidence.length > MAX_EVIDENCE_ITEMS || !input.evidence.every((item) => {
     if (!item || !EVIDENCE_KINDS.has(item.kind) || (input.redactionVersion >= 3 && !textIsSafe(item.title, MAX_TITLE_LENGTH)) || !textIsSafe(item.statement, MAX_WORK_DETAIL_LENGTH)) return false;
     if (item.kind === "activity" && input.redactionVersion >= REDACTION_VERSION) return item.scope === undefined || item.scope === "";

package/commands/shifu-sync.md

@@ -21,4 +21,6 @@ For an explicit sync-now request:
 
 To connect or replace a key, run `npx --yes @useshifu/coding-harness connect --harness opencode`. Connect asks for a key with a normal visible terminal prompt and verifies it with Shifu before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run the command or accept input, ask the user to run it in their own interactive terminal and report the output; do not claim the connection succeeded. To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness opencode`. New connections use one-hour automatic sync and `~/Desktop/Shifu` on macOS by default. To change the interval, approval policy, or folder later, run `config update --harness opencode` with the desired flags (for example, `--input-folder <existing-readable-folder>`).
 
-For an explicit user force-sync request, use `sessions --harness opencode --force` with the requested window/count. It selects local turns independently of checkpoints, including already synced work and ranges missing from the server. It preserves whole stored ranges touching selected turns (including older turns across a window boundary) and splits uncovered selected turns into ranges of at most 12. Keep the initial targets fixed and report `unavailableSegments` honestly. Re-review with `review --harness opencode --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` using the same window or explicit `--all`; no old receipt ID is needed. Redact the final notes again and add `force: true` to the prepared payload; send with `sync --harness opencode --force`, following the saved approval policy. Never guess boundaries or force scheduled/file sync. On a partial-overlap rejection, re-discover and re-review the complete ranges. Checkpoints and history are preserved; identical retries are safe. Force sync leaves AI Profile observations unchanged. Start a new chat in Shifu to use the latest work context.
+After the first successful connection, automatically backfill the last 15 days of eligible sessions unless the user opts out or chooses another initial window. Resume an unfinished first-setup backfill from accepted checkpoints. The connection request authorizes this one-time backfill without a separate permission or payload-approval question. Run `status --harness opencode`, then `sessions --harness opencode --days 15`; use `--days 15` for review and follow the sync-now redaction/submission workflow above. In manual mode, use `sync --approved --harness opencode` for this already-authorized backfill only, without changing the saved policy. Repeat discovery after accepted segments until no eligible or blocked segments remain; one checkpoint does not prove completion. Never force, include current/setup sessions, or silently broaden blocked sessions to `--all`. On an error remaining after runner retries, stop and report accepted work and unfinished backfill. No eligible sessions is a valid empty result. Skill upgrades, status checks, and key replacement alone do not trigger a new initial backfill.
+
+For an explicit user force-sync request, use `sessions --harness opencode --force` with the requested window/count. It selects local turns independently of checkpoints, including already synced work and ranges missing from the server. It preserves whole stored ranges touching selected turns (including older turns across a window boundary) and splits uncovered selected turns into ranges of at most 12. Keep the initial targets fixed and report `unavailableSegments` honestly. Re-review with `review --harness opencode --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` using the same window or explicit `--all`; no old receipt ID is needed. Read the final notes semantically and prepare meaningful redacted evidence about attributable work, retaining supported technologies, patterns, problem, approach, and results. Markdown such as `**Implemented**` and inline-code technology names still describe work. Do not use `payloadForSegment` or an unattended keyword projection, and never send empty evidence or a title-only replacement. If no work items are supported, report the range as not replaced and leave its existing work/checkpoints untouched. Add `force: true` to the prepared payload; send with `sync --harness opencode --force`, following the saved approval policy. Never guess boundaries or force scheduled/file sync. On a partial-overlap rejection, re-discover and re-review the complete ranges. Checkpoints and history are preserved; identical retries are safe. Force sync leaves AI Profile observations unchanged. Start a new chat in Shifu to use the latest work context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-sync/SKILL.md

@@ -25,7 +25,7 @@ When the user asks to connect, run:
 npx --yes @useshifu/coding-harness connect --harness codex
 ```
 
-`connect` asks for a key with a normal visible terminal prompt every time and verifies it against Shifu for this harness before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run npx or accept input, ask the user to run the command in their own interactive terminal and report its output; do not claim the connection succeeded. It installs the current runner and a local schedule with no policy questions. New connections default to hourly automatic sync and `~/Desktop/Shifu` as the single input folder on macOS. It creates shortcuts at `~/Downloads/Shifu` and `~/Documents/Shifu` when possible without replacing conflicting items. Supported files are `.txt`, `.md`, `.rtf`, and `.docx` up to 20 MB directly inside the folder; images and screenshots are not supported. Unknown formats are counted but never uploaded. Replacing a key resets local checkpoints so work can sync to the new connection. It also excludes the setup session when the harness exposes its current opaque session reference. No content is sent during setup.
+`connect` asks for a key with a normal visible terminal prompt every time and verifies it against Shifu for this harness before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run npx or accept input, ask the user to run the command in their own interactive terminal and report its output; do not claim the connection succeeded. It installs the current runner and a local schedule with no policy questions. New connections default to hourly automatic sync and `~/Desktop/Shifu` as the single input folder on macOS. It creates shortcuts at `~/Downloads/Shifu` and `~/Documents/Shifu` when possible without replacing conflicting items. Supported files are `.txt`, `.md`, `.rtf`, and `.docx` up to 20 MB directly inside the folder; images and screenshots are not supported. Unknown formats are counted but never uploaded. Replacing a key resets local checkpoints so work can sync to the new connection. It also excludes the setup session when the harness exposes its current opaque session reference. `connect` itself sends no work content; the first-setup backfill below follows a successful connection.
 
 To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness codex`. Tell the user to revoke the old key in Shifu if they no longer want it usable.
 
@@ -37,6 +37,15 @@ npx --yes @useshifu/coding-harness config update --harness codex --input-folder
 
 Use only the flags the user wants to change; existing settings are preserved. The CLI validates a custom folder before saving. Do not add a second confirmation around either command.
 
+## First setup backfill
+
+After the first successful connection, automatically backfill the last 15 days of eligible harness sessions if that initial backfill has not been completed. Continue an interrupted first-setup backfill from its accepted checkpoints. Treat the connection request as authorization for this one-time backfill; do not ask for separate permission or payload approval. Respect an explicit opt-out or a different initial window from the user. Installing or upgrading the skill, inspecting an existing connection, or replacing a key alone must not trigger a new initial backfill.
+
+1. Read `status --harness codex`, then discover work with `sessions --harness codex --days 15`. A single existing checkpoint does not prove the entire backfill is complete.
+2. Follow the **Sync now** review, redaction, and submission workflow with `--days 15` for both discovery and review. Preserve chronological segments and the returned session references and turn ranges. Send without another confirmation; if the saved policy is manual, use `sync --approved --harness codex` for this already-authorized backfill only. Leave the saved approval mode and schedule unchanged.
+3. Repeat discovery after accepted segments until the window is exhausted. Skip already-synced work, exclude current/setup sessions, and never use `--force`. If `blockedSessions` requires older turns outside the 15-day window, report the blockage rather than silently broadening to `--all`.
+4. Report completion only when discovery has no remaining eligible or blocked segments and all submitted segments were accepted. On an error remaining after the runner's retries, stop and report accepted work and unfinished backfill; do not mark it completed or skip ahead. No local eligible sessions is a valid empty result, not evidence that work was captured.
+
 ## Inspect status or queued work
 
 Run `npx --yes @useshifu/coding-harness status --harness codex` to inspect the saved policy, next scheduled run, pending count, and checkpoints.
@@ -101,6 +110,6 @@ If a transport or server error remains after the runner's retries, report that t
 
 Only when the user explicitly asks to force-sync, add `--force` to `sessions` with their requested window or count. Force chooses local turns independently of local and server checkpoints, including already synced sessions and work never accepted by the server. It preserves complete stored range boundaries when they touch the selected window and splits uncovered selected turns into ranges of at most 12. A stored range crossing the window can include older turns so it is replaced in full. Missing local turns are reported in `unavailableSegments`; never invent them or silently count them as synced. Keep the initial returned targets fixed while processing this force request.
 
-Re-review each returned range with `review --harness codex --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` and the same window (or `--all` for explicitly selected backfill/count selection). No prior sync ID is required. Inspect and redact the final notes again, preserving supported work detail. Keep the returned reference and range unchanged and include `force: true` in the prepared payload. Send with `sync --harness codex --force` (plus `--approved` only after manual approval). If accepted ranges changed and partially overlap the selection, stop and re-discover/re-review the complete ranges instead of guessing boundaries.
+Re-review each returned range with `review --harness codex --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` and the same window (or `--all` for explicitly selected backfill/count selection). No prior sync ID is required. Read the returned final notes semantically and synthesize meaningful, attributable work evidence; do not use `payloadForSegment` or its unattended keyword projection for force sync. Completed work remains supported when the note uses Markdown such as `**Implemented**` or names a technique in inline code such as `Rust`. Retain supported technologies, design patterns, the problem, approach, and verified result while redacting names and sensitive identifiers. Never send an empty evidence list or a title-only replacement. If the notes support no work items, report that range as not replaced and leave its existing work and checkpoints untouched. Keep the returned reference and range unchanged and include `force: true` in the prepared payload. Send with `sync --harness codex --force` (plus `--approved` only after manual approval). If accepted ranges changed and partially overlap the selection, stop and re-discover/re-review the complete ranges instead of guessing boundaries.
 
 Force sync creates missing ranges or replaces existing exact ranges, preserves sync history, and never resets or lowers checkpoints. Automatic retries preserve the accepted result even if another force sync finishes meanwhile. A new invocation is a new explicit force request. Existing AI Profile observations stay unchanged. Do not add force to scheduled sync, approval queues, or file sync. Existing conversations keep their context; start a new chat in Shifu to use the latest work context.