rcf-lite 0.26.0 → 0.28.0

package/rcf/user-stories/us-15801.json

@@ -0,0 +1,42 @@
+{
+  "usId": "US-15801",
+  "prdId": "PRD-001",
+  "reqId": "REQ-158",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Library owner declares where feedback issues go",
+  "asA": "library owner shipping a blueprint library",
+  "iWant": "to name the reports destination in one field on library.json, snapshotted into the consuming project registry on library add, so every project using my library files reports on my repo",
+  "soThat": "I hear about defects on my library without every consuming project having to be told separately",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15801-1",
+      "description": "library.json accepts an optional issues object with { repo: \"OWNER/REPO\" (host-qualified HOST/OWNER/REPO permitted for GHES), visibility: \"public\" | \"private\" }. Absence is valid; the presence-with-shape is schema-checked (documented in docs/library-authoring.md field table). On rcf library add the value is snapshotted onto the registry entry as issuesRepo and issuesVisibility, alongside publisher. rcf library refresh re-snapshots.",
+      "given": "a fixture library.json with { issues: { repo: \"wsd-team-dev/rcf-lite-blueprints\", visibility: \"private\" } }",
+      "when": "rcf library add is run against the fixture",
+      "then": "rcf/blueprint-libraries.json:entries[] for the library carries issuesRepo and issuesVisibility with the exact values; the review-on-add card prints \"Feedback destination: wsd-team-dev/rcf-lite-blueprints (private)\"",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15801-2",
+      "description": "The destination resolver (src/feedback/destination.js) walks: entry.target -> rcf/manifest.json:blueprints[] -> if libraryPrefix present, the registry entry issuesRepo; absent on the entry, derives from the library sourceRef when it parses as git+https://github.com/OWNER/REPO(.git)#ref (marked derived: true); otherwise unresolved. Shelf blueprints (no libraryPrefix) and --kind core route to a constant read from package.json:bugs.url (Stravica/rcf-lite).",
+      "given": "a fixture with three applied blueprints: one shelf, one library with explicit issues, one library with a github git source and no issues",
+      "when": "destination.resolve() is called for each",
+      "then": "the shelf entry resolves to Stravica/rcf-lite; the explicit-issues library resolves to its declared repo, derived false; the git-source library resolves to the OWNER/REPO parsed from the URL, derived true; a fourth library with no issues and no github source is returned as unresolved",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15801-3",
+      "description": "rcf doctor gains a warn-only check feedback-destinations that lists every registered library without a resolvable destination (no issues field and no derivable git source) and every applied blueprint whose destination the resolver returns unresolved. --fix does not touch destinations; the fix is for the library owner or the consuming operator.",
+      "given": "a fixture with two registered libraries: one with issues, one with neither issues nor a github source",
+      "when": "rcf doctor is run",
+      "then": "doctor output carries one feedback-destinations warn row naming the second library, --fix is not offered on that row, exit code stays 0",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/user-stories/us-15802.json

@@ -0,0 +1,33 @@
+{
+  "usId": "US-15802",
+  "prdId": "PRD-001",
+  "reqId": "REQ-158",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Findings on shelf blueprints and on rcf-lite itself go to rcf-lite",
+  "asA": "operator whose agent has logged a finding on a shelf blueprint or on rcf-lite core",
+  "iWant": "those findings routed to Stravica/rcf-lite by default without any per-project configuration",
+  "soThat": "reports about shelf content and core verbs reach the maintainers who own them",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15802-1",
+      "description": "A pending entry with kind blueprint and a target that resolves in the manifest without a libraryPrefix (a shelf blueprint) has destination.repo Stravica/rcf-lite on preview and submit. The constant is sourced from packages/rcf-lite/package.json:bugs.url so a rename ripples through one file. A test pins the constant to the current package.json value.",
+      "given": "a fixture project applying application-forms-wizard (shelf blueprint) with one pending entry",
+      "when": "rcf feedback preview is run",
+      "then": "the rendered destination row is \"Stravica/rcf-lite (public)\"; a unit test asserts the constant equals bugs.url from package.json",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15802-2",
+      "description": "A pending entry with kind core (target is a verb path like \"define validate\" or \"docs\") has destination.repo Stravica/rcf-lite regardless of any library manifest content; the entry cannot be routed to a library repo even if a library declares the verb name as a target.",
+      "given": "a fixture with a library declaring \"define validate\" as a target and one pending core entry",
+      "when": "rcf feedback preview is run",
+      "then": "the destination.repo is Stravica/rcf-lite for the core entry; the library declaration is ignored for kind core; a warning is not emitted (this is by design)",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/user-stories/us-15901.json

@@ -0,0 +1,33 @@
+{
+  "usId": "US-15901",
+  "prdId": "PRD-001",
+  "reqId": "REQ-159",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator yes files issues under the reporter GitHub login",
+  "asA": "operator saying yes to the ask",
+  "iWant": "the tool to call gh under my ambient login and file each pending entry as a GitHub issue or +1 comment, mark each entry submitted with the URL, and print the URLs so the agent can relay them",
+  "soThat": "reports are visibly mine, with no relay in between and no token handling in the tool",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15901-1",
+      "description": "rcf feedback submit --yes runs section-7 preflight, section-6 dedupe search, then gh issue create or gh issue comment per entry (through src/feedback/gh.js, or its RCF_FEEDBACK_GH_MODULE stand-in). Each entry state line records status submitted with issueUrl and dedupe (new|comment|unchecked). Stdout prints one line per entry: \"<id> -> <url> (<dedupe>)\". Exit 0 when every entry ended submitted or bundled; exit 3 when any entry stayed pending (residual secret).",
+      "given": "a fixture project with two pending entries and a fake gh module whose create returns an issue URL and whose search returns zero hits",
+      "when": "the operator runs rcf feedback submit --yes",
+      "then": "both entries fold to status submitted with the returned URL and dedupe new; stdout carries two \"<id> -> <url> (new)\" lines; entries.jsonl is not rewritten (only appended)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15901-2",
+      "description": "rcf feedback submit without --yes refuses on a non-TTY (exit 2, stderr names the --yes requirement); on a TTY it prompts once and only proceeds on a y answer. The tool never reads GH_TOKEN or GITHUB_TOKEN itself, never asks for a token, and never spawns gh auth login. A test asserts the process env passed to gh is a copy without any TOKEN mutation.",
+      "given": "a fixture project with one pending entry, run under a non-TTY child process",
+      "when": "rcf feedback submit is run without --yes",
+      "then": "exit code 2, stderr names --yes as required; no gh invocation is made; process.env passed through to the fake gh has no synthesised TOKEN key",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/user-stories/us-15902.json

@@ -0,0 +1,51 @@
+{
+  "usId": "US-15902",
+  "prdId": "PRD-001",
+  "reqId": "REQ-159",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Labels are applied where the reporter may set them",
+  "asA": "maintainer triaging inbound issues",
+  "iWant": "rcf-feedback plus severity:<...> plus area:<...> labels applied by the tool when the destination repo carries them and the reporter has push or triage access",
+  "soThat": "triage queues sort correctly for reporters who have the right, while outside reporters on a public repo still land readable issues (title prefix and body fingerprint remain the load-bearing handles).",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15902-1",
+      "description": "Before create, the tool calls gh label list --json name on the destination repo and intersects the requested labels (\"rcf-feedback\", \"severity:<sev>\", \"area:<blueprint|core>\") with the returned set. Missing labels are dropped from the create call and recorded on the entry state as droppedLabels[] and in the preview ledger.",
+      "given": "a fake gh module whose label list returns { rcf-feedback, severity:major } but not area:blueprint",
+      "when": "submit --yes is run with one pending major-severity blueprint entry",
+      "then": "gh issue create is called with labels rcf-feedback, severity:major only; the entry state carries droppedLabels: [\"area:blueprint\"]",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15902-2",
+      "description": "scripts/bootstrap-feedback-labels.mjs is a one-shot script a repo admin runs to create the six labels in one destination repo: rcf-feedback, severity:blocker, severity:major, severity:minor, area:blueprint, area:core. Idempotent: existing labels are left alone; missing ones are created via gh label create. The script is a maintainer aid, not called from init or doctor.",
+      "given": "a fake gh module in the script fixture whose label list starts empty",
+      "when": "the script is run once, then again",
+      "then": "first run creates six labels via gh label create; second run makes zero create calls; exit 0 on both",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15902-3",
+      "description": "The rendered issue title always carries the prefix (\"[<effective-slug>] \" for blueprints, \"[rcf-lite] \" for core) and the body always carries the visible rcf-feedback-fingerprint: <fp> line plus the HTML-comment twin. Both are load-bearing triage handles when labels are missing or dropped.",
+      "given": "render() is called on a blueprint and a core entry",
+      "when": "the rendered title and body are compared to templates",
+      "then": "blueprint titles start with \"[<slug>] \"; core titles start with \"[rcf-lite] \"; each body carries the fingerprint on its own line and inside an HTML comment (fingerprint appears twice on purpose)",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15902-4",
+      "description": "The six-label catalogue (rcf-feedback, severity:blocker, severity:major, severity:minor, area:blueprint, area:core) is exported as a single frozen constant from src/feedback/labels.js (FEEDBACK_LABELS or equivalent). Both scripts/bootstrap-feedback-labels.mjs and the submit-time label pre-check import that constant and refuse to hard-code any of the six names locally. A grep test asserts no string literal for a catalogue label name appears outside src/feedback/labels.js, its own tests, and the bootstrap script that imports it.",
+      "given": "a fresh clone of the repo",
+      "when": "the grep test enumerates string literals for each of the six label names across src/, scripts/, bin/",
+      "then": "every hit is either inside src/feedback/labels.js, a test file that imports the constant, or the bootstrap script; there is no bare string literal for any of the six names elsewhere",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/user-stories/us-16001.json

@@ -0,0 +1,51 @@
+{
+  "usId": "US-16001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-160",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "No gh, no login or no access still gives the operator a bundle and a URL",
+  "asA": "operator without gh installed, not logged in, or without access to a private destination repo",
+  "iWant": "submit to write a bundle file with the exact issue text and print the file path and the destination issues/new URL in one line",
+  "soThat": "I can paste or email the report even when the tool cannot file it on my behalf, and I am not asked about the same entries again next session",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16001-1",
+      "description": "Preflight order (per destination): gh on PATH -> gh auth status non-zero -> gh repo view viewerPermission NONE on a private repo -> gh repo view hasIssuesEnabled false. The first failure routes to a bundle for that destination without any further gh call. The bundle path <cwd>/.rcf/feedback/outbox/<ISO-timestamp>-<repo-slug>.md is printed on its own line next to the destination issues/new URL. Each failure kind maps to a distinct one-line message (naming gh, naming \"run gh auth login\", naming private-access with the library contact, naming issues-disabled).",
+      "given": "four fixture cases: gh missing on PATH; gh present but auth status non-zero; repo private with viewerPermission NONE; repo with hasIssuesEnabled false",
+      "when": "submit --yes is run once per case with one pending entry",
+      "then": "each run writes the bundle under outbox with the expected filename shape and prints the URL and path on one line together; entry state is bundled with outboxPath; exit code 0",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16001-2",
+      "description": "If create or comment fails after the label pre-check (network 4xx or 5xx, abuse rate limit, unexpected label rejection), submit retries once without labels and, on a second failure, bundles that entry only. Other entries continue. Exit code is 0 when every entry ended submitted or bundled, and 3 when a residual secret leaves one entry pending.",
+      "given": "a fake gh module whose issue create throws with a 429-shaped error on the first two calls and succeeds on the third",
+      "when": "submit --yes runs with three pending entries",
+      "then": "the first entry retries once, then bundles; the second retries once, then bundles; the third submits; exit 0; two bundle files exist and the third entry is submitted",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16001-3",
+      "description": "Bundled entries are terminal for the ask loop: rcf feedback list default (pending) does not show them, the SessionStart hook does not count them into the carry-over ask, and the Stop hook does not re-ask about them. rcf feedback submit <id> re-attempts one bundled entry by hand and moves it to submitted on success.",
+      "given": "a fixture with two bundled entries and one pending entry",
+      "when": "the Stop hook decision function is invoked and rcf feedback list default is called",
+      "then": "Stop asks only about the pending entry, list shows only the pending entry, list --all shows the bundled entries with status bundled; submit fb-<id-of-bundle> retries just that one",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16001-4",
+      "description": "When submit encounters an entry whose destination cannot be resolved (library without an issues field and no derivable git source, so destination.resolve() returned unresolved), the entry is written to the bundle at .rcf/feedback/outbox/<ISO-timestamp>-unresolved.md, the publisher contact from the registry entry (if present) is printed on the same line as the outbox path, no gh call is made for that entry, and exit code stays 0. The entry state folds to bundled with outboxPath.",
+      "given": "a fixture project with one applied library whose registry entry carries neither issuesRepo nor a derivable github git source but does carry publisher.contact, and one pending blueprint entry against that library",
+      "when": "submit --yes is run",
+      "then": "the outbox file exists with the unresolved-slug filename, stdout carries the publisher.contact on the same line as the outbox path, no gh invocation was made, entry state is bundled, exit code is 0",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/user-stories/us-16101.json

@@ -0,0 +1,42 @@
+{
+  "usId": "US-16101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-161",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator is asked once, at a pause, with the exact preview text, and never nagged",
+  "asA": "operator in the middle of getting work done",
+  "iWant": "the ask to arrive at a natural pause (queue complete, an entry older than 15 minutes, a carried-over entry, or a --ask-now blocker), for the ask to carry the exact preview text and destination, and for me never to be asked twice in one session",
+  "soThat": "the ask is welcome rather than an interruption",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16101-1",
+      "description": "The quiet rule in src/feedback/hook.js returns \"ask\" on stop when ALL hold: not opted out (rcf/feedback-settings.json ask true and RCF_FEEDBACK_ASK unset or 1); at least one pending entry; state.json has no asked record for the incoming session_id; stop_hook_active is false; and one of: an entry carries askNow; the newest pending entry is older than quietMinutes (default 15) minutes; the queue-state cache reports complete or nothing actionable; the entry was carried over. Otherwise returns \"silent\". A table test walks every named row.",
+      "given": "a fixture state file and a table of pending/asked/optOut/stopHookActive/age/queueState/carriedOver/askNow rows",
+      "when": "shouldAsk(input) is called on each row",
+      "then": "every row returns the expected verdict; the asked record is appended to state.json before the emit path in the wrapper (assertable at the caller by observing state mutation before hook stdout is produced)",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16101-2",
+      "description": "On Claude Code (--harness claude-code default when CLAUDECODE is set), the stop hook exits 2 with the reason text on stderr. The reason names the exact next-step verbs (\"rcf feedback preview\", \"rcf feedback submit --yes\", \"rcf feedback defer\", \"rcf feedback opt-out\") and says \"Do not ask again this session.\" On Codex (--harness codex), the hook emits stdout JSON { \"decision\": \"block\", \"reason\": \"<same text>\" } with exit 0. Both branches append the asked record to state.json exactly once per session_id.",
+      "given": "a fixture project with one pending entry, and two mock harness JSON inputs on stdin (Claude Code and Codex shapes)",
+      "when": "rcf feedback hook stop --harness claude-code and --harness codex are run",
+      "then": "Claude Code run: exit code 2, stderr carries the four verb names and the \"do not ask again this session\" clause; Codex run: exit 0, stdout parses to { decision: \"block\", reason: ... } with the same clause; state.json in both cases gained exactly one asked record for the input session_id",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16101-3",
+      "description": "A second stop invocation with the same session_id is silent (no exit-2, no JSON block emission, exit 0) even when new pending entries arrive after the first ask. A new session_id resets the ledger and asks again per the quiet rule.",
+      "given": "a fixture state.json with one asked record, one further pending entry added after the ask",
+      "when": "rcf feedback hook stop is run twice with the same session_id and then once with a fresh session_id",
+      "then": "the two same-session calls are silent (exit 0, no reason emitted); the fresh-session call re-emits the ask per the quiet rule",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/user-stories/us-16102.json

@@ -0,0 +1,33 @@
+{
+  "usId": "US-16102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-161",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator silences the ask for this project",
+  "asA": "operator who does not want to be asked about feedback on this project",
+  "iWant": "a one-command opt-out that writes rcf/feedback-settings.json:ask false (checked in), and an env variable that silences the ask per user without touching the file",
+  "soThat": "a shared project silences the ask for everyone, and a CI or per-user preference silences it locally",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16102-1",
+      "description": "rcf feedback opt-out writes rcf/feedback-settings.json with { settingsVersion: 1, ask: false, redaction: { allowHosts: [] }, quietMinutes: 15 } (merging with any prior file). rcf feedback opt-in restores ask true. The hook shouldAsk returns silent when ask is false. rcf feedback add, preview and submit keep working under ask: false (hand-driven flow).",
+      "given": "a fresh fixture project",
+      "when": "rcf feedback opt-out then rcf feedback hook stop with one pending entry, then rcf feedback preview",
+      "then": "the settings file contains ask: false; the hook exits 0 silently; preview still renders the entry",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16102-2",
+      "description": "RCF_FEEDBACK_ASK=0 forces silent on the hook regardless of file setting. RCF_FEEDBACK_DISABLE=1 makes rcf feedback add a no-op that prints \"feedback disabled by env\" (no file write, no exit-2). Precedence order: env DISABLE > env ASK=0 > file ask false > file ask true.",
+      "given": "a fixture project with ask true in the file, plus each env variable in turn",
+      "when": "rcf feedback add and rcf feedback hook stop are run under each precedence combination",
+      "then": "env DISABLE suppresses add entirely; env ASK=0 keeps add working but silences the hook; file ask false silences the hook and add still works",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/user-stories/us-16103.json

@@ -0,0 +1,42 @@
+{
+  "usId": "US-16103",
+  "prdId": "PRD-001",
+  "reqId": "REQ-161",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "A carried-over batch is offered next session",
+  "asA": "operator whose session ended before the ask fired",
+  "iWant": "the SessionEnd hook to flush a bundle idempotently and the SessionStart hook of the next session to inject a one-line context reminder that pending entries exist",
+  "soThat": "a crash or /clear does not lose findings and the next session's first pause carries the ask",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16103-1",
+      "description": "rcf feedback hook session-end writes the outbox bundle for any pending entries under 1 second (the shared Claude Code SessionEnd budget is 1.5s) and is byte-idempotent (same content hash means no rewrite). Codex SessionEnd runs the same handler; output is discarded either way.",
+      "given": "a fixture with two pending entries and a stubbed clock so the elapsed time is measurable",
+      "when": "rcf feedback hook session-end is run twice back-to-back",
+      "then": "the first run writes one bundle file under outbox; the second run runs to completion in under 1 second without rewriting the same-hash file; both exit 0",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16103-2",
+      "description": "rcf feedback hook session-start with pending entries and a new sessionId prints one plain line to stdout on Claude Code (\"rcf feedback: <n> unsubmitted entr(y|ies) carried over from an earlier session; ask the operator once at a natural pause (RULE 17).\") and the Codex-shaped equivalent under --harness codex. The line is what the harness injects as context; it never blocks. If SessionStart on Codex cannot inject context (verified at build time against the current Codex reference), the fallback in RULE 17 (\"check rcf feedback status at session start\") is what carries the same posture.",
+      "given": "a fixture with two pending entries carried over from a prior sessionId",
+      "when": "rcf feedback hook session-start is run under each harness",
+      "then": "the Claude Code stdout matches the exact wording above; the Codex JSON matches the reference shape currently accepted for SessionStart context; both return exit 0; state.json is not mutated (asked is set on Stop, not on session-start)",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16103-3",
+      "description": "rcf feedback defer means \"not now, ask again next session\" (design 3.1). Entries in status deferredUntilSession whose stored sessionId is not the current one are requeued to pending on the SessionStart hook AND on the Stop hook (belt to the SessionStart braces, so the flow works when only Stop is installed). The requeue appends one state-transition line per entry with status pending and no sessionId field, so fold-by-id preserves the entry's prior sessionId and the carry-over gate in both hooks (pending.sessionId !== currentSessionId) fires naturally in the new session. Entries recorded or last deferred under the current sessionId are not re-transitioned (idempotent per session; deferring twice in one session is a no-op on the second call).",
+      "given": "a fixture with one pending entry deferred in session A (entries.jsonl carries the deferredUntilSession line with sessionId A)",
+      "when": "rcf feedback hook session-start --harness claude-code is run with session_id B, then rcf feedback hook stop --harness claude-code is run with the same session_id B",
+      "then": "SessionStart appends one { status: pending } transition (no sessionId field) so the entry returns to pending with its sessionId still A; the carry-over line prints to stdout naming the count and RULE 17; the following Stop exits 2 with the ask on stderr and appends exactly one asked record for session B; a second SessionStart in session B is a no-op (no new transition, silent stdout); a further SessionStart in a fresh session_id C after a Stop-only path (no SessionStart wired) still requeues on the Stop hook so the ask fires there",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-17T03:30:00Z"
+}

package/rcf/user-stories/us-16104.json

@@ -0,0 +1,42 @@
+{
+  "usId": "US-16104",
+  "prdId": "PRD-001",
+  "reqId": "REQ-161",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf init installs the feedback hooks and rcf doctor keeps them honest",
+  "asA": "operator running rcf init on a project",
+  "iWant": "the feedback Stop / SessionEnd / SessionStart hook entries merged into .claude/settings.json and .codex/hooks.json (with --no-feedback-hooks to skip), and rcf doctor to report missing-hook (fixable with --fix) and foreign-hook (refused) so the harness config stays honest across clones",
+  "soThat": "every clone gets the same ask behaviour without a per-developer setup step, and drift is surfaced instead of quietly diverging",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16104-1",
+      "description": "rcf init merges three feedback hook entries into .claude/settings.json (Stop -> \"npx rcf-lite feedback hook stop --harness claude-code\" timeout 10; SessionEnd -> \"... hook session-end ...\" timeout 5; SessionStart matcher \"startup|resume\" -> \"... hook session-start ...\") and three matching entries into .codex/hooks.json (in the Codex schema for the same events). Merge discipline mirrors writeMcpConfig: parse, refuse on invalid JSON with the same message shape as .mcp.json, never clobber other hooks, add ours only if an entry whose command contains \"rcf feedback hook\" is absent. The \"npx rcf-lite\" prefix is replaced by binPath when init was called with --bin-path, mirroring the .mcp.json entry pattern.",
+      "given": "a fresh fixture project with no .claude/settings.json and no .codex/hooks.json",
+      "when": "rcf init is run without --no-feedback-hooks",
+      "then": "both files contain the three feedback hook entries in the right shape; a second rcf init on the same tree is byte-idempotent; a pre-existing settings.json with an unrelated hook is preserved and the feedback entries are added alongside it",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16104-2",
+      "description": "rcf init --no-feedback-hooks writes neither .claude/settings.json nor .codex/hooks.json feedback entries and prints the instruction-only fallback line once (RULE 17 still applies). --no-feedback-hooks composes with --no-playwright-mcp and other init skips without interaction.",
+      "given": "a fresh fixture project",
+      "when": "rcf init --no-feedback-hooks is run",
+      "then": "no feedback hook entry is present in either config file; init exits 0; the one-line instruction fallback appears in stdout",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16104-3",
+      "description": "rcf doctor --check feedback-hooks reports missing-hook (fixable) per hook per file when an expected entry is absent, and foreign-hook (refused, hand-repair message) when an entry whose command contains \"rcf feedback hook\" is present with different flags than the current install shape. rcf doctor --fix adds the missing entries and touches nothing else. A clean tree reports no findings and doctor stays exit 0.",
+      "given": "three fixture projects: one missing all feedback hook entries; one with a foreign entry (same command, wrong flags); one clean",
+      "when": "rcf doctor --check feedback-hooks --fix is run against each",
+      "then": "the missing-entries project ends with the entries present (added only); the foreign-entry project keeps the foreign entry, reports the foreign-hook message and exits non-zero; the clean project makes no writes and exits 0",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T14:07:38.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/user-stories/us-16201.json

@@ -0,0 +1,33 @@
+{
+  "usId": "US-16201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-162",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "RULE 17 tells every agent when to log and when to ask",
+  "asA": "harness (Claude Code or Codex) that reads the managed instructions block",
+  "iWant": "a static RULE 17 in guidance/managed/agent-instructions-block.md that names rcf feedback add for logging, describes the one-ask-per-session posture (harness hook or operator wrap-up as trigger, preview then submit --yes or defer or opt-out), and states the redaction posture",
+  "soThat": "an agent under pace still follows the shape when the harness hooks are not trusted, and the same rule serves both harnesses",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16201-1",
+      "description": "guidance/managed/agent-instructions-block.md gains RULE 17 with the wording specified in design section 3.4. pnpm run build:managed regenerates the block hash and harness-template.md so rcf doctor doctor-agent-instructions and gen-managed-artefacts stay byte-consistent. The wording is static (no version numbers, no dates) and names all four verbs (preview, submit --yes, defer, opt-out). A byte-exact template test loads the shipped block and asserts the RULE 17 slice is byte-for-byte identical to the design-section-3.4 fixture stored in test/fixtures/managed/rule-17.md, so a wording drift on ship is caught.",
+      "given": "a fixture repository state with RULE 17 not yet added",
+      "when": "the change is applied, pnpm run build:managed is run, and rcf doctor is run",
+      "then": "RULE 17 appears in the block file exactly as specified; the hash file changes on this release; doctor doctor-agent-instructions reports clean; a byte-exact template test asserts the RULE 17 slice of the block matches test/fixtures/managed/rule-17.md byte-for-byte",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16201-2",
+      "description": "rcf init writes CLAUDE.md and AGENTS.md with the regenerated block (RULE 17 included). The existing managed-block installation path (writeAgentInstructions) is the only touch-point; no init-time flag is added for RULE 17.",
+      "given": "a fresh fixture project",
+      "when": "rcf init is run",
+      "then": "CLAUDE.md and AGENTS.md both contain the RULE 17 block text between the managed-block markers; the block outside the markers is untouched",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/user-stories/us-16301.json

@@ -0,0 +1,36 @@
+{
+  "createdAt": "2026-09-16T22:20:45Z",
+  "updatedAt": "2026-09-16T22:20:45Z",
+  "asA": "beta reader relying on the referee-guarantees page to know what `rcf define validate` proves",
+  "iWant": "a broken ADR supersededBy pointer to be reported as a brokenReference the same way a broken parent link is, and the soft `relatedAdrs` back-reference to stay silent so the ratified blueprint-supersede workflow is not broken",
+  "soThat": "the docs-page promise that every reference in every document resolves is enforced on the strong chain-of-decisions reference (supersededBy), while the soft see-also field stays a schemas follow-up (either value-narrowed or workflow-aware)",
+  "usId": "US-16301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-163",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "US-16301: define validate walks ADR supersededBy; relatedAdrs stays a schemas follow-up (compatibility carry)",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16301-1",
+      "description": "An ADR whose supersededBy names an id with no file on disk (or an id that resolves to a non-ADR kind) surfaces as a brokenReference error naming the ADR file and the field `supersededBy`, and the corresponding target id joins tree.brokenIds. A supersededBy field that is absent or empty is silent.",
+      "given": "an initialised RCF project with adr-001.json whose supersededBy is set to a non-existent id ADR-999",
+      "when": "walkTree runs (as invoked by `rcf define validate`)",
+      "then": "errors contain a brokenReference with documentId ADR-001 and field supersededBy naming ADR-999, and tree.brokenIds contains ADR-999",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16301-2",
+      "description": "An ADR whose relatedAdrs contains an id with no file on disk stays SILENT under walkTree: the ratified `rcf define blueprint supersede` workflow writes a project ADR whose relatedAdrs lists both the applied blueprint ADR (on disk) and the incoming blueprint ADR (not yet on disk; the incoming add is the closing step of option 3). Walking relatedAdrs would refuse that workflow between the supersede write and the re-add; the compatibility carry keeps the soft back-reference unchecked here. Tightening this is a schemas follow-up (value-narrow to applied ADR ids, or a workflow-aware exception on the supersede write path).",
+      "given": "an initialised RCF project with adr-001.json whose relatedAdrs is set to [ADR-777] (a non-existent id, mirroring the transient state between supersede and re-add)",
+      "when": "walkTree runs (as invoked by `rcf define validate`)",
+      "then": "no brokenReference error targets the relatedAdrs field on ADR-001",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [
+    "TAC-4109-referee-validate-adr-crosslinks"
+  ]
+}

package/rcf/user-stories/us-16401.json

@@ -0,0 +1,45 @@
+{
+  "createdAt": "2026-09-16T22:28:54Z",
+  "updatedAt": "2026-09-16T22:28:54Z",
+  "asA": "beta reader who typed the command from the referee-guarantees page",
+  "iWant": "`rcf audit coverage` with no flag to fail the gate on a stub or missing test, and `--mode shallow-any` to be the documented escape valve",
+  "soThat": "the docs promise 'a stub or stale pointer fails the gate exactly as a missing test does' holds by construction, and my existing `--strict` invocations do not need rewriting",
+  "usId": "US-16401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-164",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "US-16401: strict-by-default coverage with a shallow-any opt-out and a legacy --strict alias",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16401-1",
+      "description": "The plain `rcf audit coverage` command runs strict (per-AC) mode. On a tree whose ACs are not all covered by resolving TCs, it prints the table and exits 4; on a fully covered tree it exits 0. The default is the same as the legacy `--strict` invocation.",
+      "given": "an initialised RCF project with a scaffold AC-101-1 that has no covering TC",
+      "when": "`rcf audit coverage` is invoked with no strictness flag",
+      "then": "the exit code is 4",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16401-2",
+      "description": "`--mode shallow-any` reports gaps and exits 0. The output's Coverage-mode line reads `shallow-any` and the table renders the same shape as strict mode; the exit code is 0 even on uncovered ACs.",
+      "given": "the same scaffold as AC-16401-1",
+      "when": "`rcf audit coverage --mode shallow-any` is invoked",
+      "then": "the exit code is 0 and the output includes 'Coverage mode: shallow-any'",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16401-3",
+      "description": "Conflicting flags exit 2 with a usage message. Passing `--mode shallow-any --strict` (in either order) is refused before running the audit; the error names both flags. `--mode` with an unknown value (e.g. `lenient`) also exits 2 with a usage message.",
+      "given": "an initialised RCF project",
+      "when": "`rcf audit coverage --mode shallow-any --strict` is invoked",
+      "then": "the exit code is 2 and stderr matches /--mode shallow-any conflicts with --strict/",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [
+    "TAC-4110-referee-coverage-mode-selector"
+  ]
+}

package/rcf/user-stories/us-16501.json

@@ -0,0 +1,45 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "asA": "beta reader trusting the referee-guarantees page's finalise refusal list",
+  "iWant": "`rcf build finalise` to refuse promotion when the verify report carries UI-BASELINE-UNMET, BROWSER-VERIFICATION-MISSING or SCOPE-MISMATCH on any AC",
+  "soThat": "a UI baseline violation, a missing browser check on a UI-bearing FBS, a bound TC narrower than its AC scope, or a block-severity probe-pack failure all fail the gate the same way the mock-only and EVAL refusals already do",
+  "usId": "US-16501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-165",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "US-16501: finalise refuses on UI-BASELINE-UNMET, BROWSER-VERIFICATION-MISSING and SCOPE-MISMATCH",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16501-1",
+      "description": "On a verify PASS (exit 0, ship authority) whose report carries at least one per-AC UI-BASELINE-UNMET verdict, `rcf build finalise` exits 4 and leaves the FBS at 'complete'. The stderr message names the AC(s), the count of UI-BASELINE-UNMET verdicts, and the referee-guarantees claim ids C-28 and C-36 (a block-severity probe-pack failure aggregates into UI-BASELINE-UNMET, so the same branch closes both).",
+      "given": "an FBS at status 'complete' and a stub verify subprocess whose report writes verdictAuthority='ship' and perAcVerdicts includes {acId, verdict: 'UI-BASELINE-UNMET'}",
+      "when": "`rcf build finalise <fbsId> --url ...` is invoked",
+      "then": "the exit code is 4, the FBS on disk stays at 'complete', and stderr matches /UI-BASELINE-UNMET/ and /Referee-guarantees claims C-28 and C-36/",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16501-2",
+      "description": "Same shape for BROWSER-VERIFICATION-MISSING: a UI-bearing FBS with no browserVerification[] record aggregates into a per-AC verdict that finalise refuses. Exit 4, FBS at 'complete', stderr names C-29.",
+      "given": "the same scaffold with perAcVerdicts = [{acId, verdict: 'BROWSER-VERIFICATION-MISSING'}]",
+      "when": "`rcf build finalise <fbsId> --url ...` is invoked",
+      "then": "the exit code is 4 and stderr matches /BROWSER-VERIFICATION-MISSING/ and /Referee-guarantees claim C-29/",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-16501-3",
+      "description": "Same shape for SCOPE-MISMATCH (NV-BL-GATE-01): a bound TC narrower than its AC scope aggregates into a per-AC SCOPE-MISMATCH verdict that finalise refuses. Exit 4, FBS at 'complete', stderr names C-30.",
+      "given": "the same scaffold with perAcVerdicts = [{acId, verdict: 'SCOPE-MISMATCH'}]",
+      "when": "`rcf build finalise <fbsId> --url ...` is invoked",
+      "then": "the exit code is 4 and stderr matches /SCOPE-MISMATCH/ and /Referee-guarantees claim C-30/",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4111-referee-finalise-per-ac-refusals"
+  ]
+}

package/rcf/user-stories/us-16502.json

@@ -0,0 +1,45 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "asA": "beta reader trusting the referee-guarantees page's verified-invariant promise",
+  "iWant": "`rcf define update` to refuse writing FBS.executionStatus=verified by default, and `rcf build finalise` to refuse promotion when the git working tree is not on a default trunk",
+  "soThat": "a chain that says verified traces to an actual post-merge runtime check by construction, and a mid-branch dev-loop finalise cannot stamp verified without the operator's deliberate opt-out",
+  "usId": "US-16502",
+  "prdId": "PRD-001",
+  "reqId": "REQ-165",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "US-16502: finalise is the only path to verified, and it fires only on a default trunk",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-16502-1",
+      "description": "The writer refuses a define-update patch that sets FBS.executionStatus=verified when `options.allowVerifiedOverride` is not true. The refusal is an RcfError with kind='usage' whose message names the finalise gate and the --acknowledge-verified-override escape flag; the FBS on disk stays unchanged.",
+      "given": "an FBS at status 'complete' loaded through walkTree",
+      "when": "updateDocument is called with sets = [{path:'executionStatus', value:'verified'}] and options = {}",
+      "then": "the result is an RcfError with kind='usage' matching /verified is written only by the finalise gate/, and the FBS file on disk still reads status 'complete'",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16502-2",
+      "description": "Passing `options.allowVerifiedOverride: true` (the seam that finalise and `rcf define update --acknowledge-verified-override` both use) writes the value: the returned shape carries the doc id and the FBS on disk reads status 'verified'.",
+      "given": "the same scaffold as AC-16502-1",
+      "when": "updateDocument is called with the same sets and options = {allowVerifiedOverride: true}",
+      "then": "the result carries an id and the FBS file on disk reads status 'verified'",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-16502-3",
+      "description": "`rcf build finalise` refuses promotion when the git working tree is not on a default trunk (main or master). Exit 4, FBS at 'complete', stderr names the branch and the referee-guarantees claim C-26. --allow-pre-merge is the deliberate opt-out: on a non-default branch it promotes and logs the pre-merge decision on stdout including the C-26 claim id.",
+      "given": "the same scaffold with a spawn seam that returns 'feature/x' as the current branch",
+      "when": "`rcf build finalise <fbsId> --url ...` is invoked",
+      "then": "the exit code is 4 and stderr matches /git working tree is on branch 'feature\\/x'/; with --allow-pre-merge appended the exit code is 0 and stdout matches /Referee-guarantees claim C-26 records the pre-merge decision here/",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4112-referee-finalise-verified-invariant"
+  ]
+}