rcf-lite 0.27.0 → 0.28.0

package/rcf/test-suites/ts-203.json

@@ -0,0 +1,38 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "purpose": "Cover AC-16502-1 (writer refuses executionStatus=verified without allowVerifiedOverride, C-22), AC-16502-2 (writer accepts when allowVerifiedOverride:true, C-22 opt-out seam), and AC-16502-3 (finalise refuses on a non-default branch, --allow-pre-merge is the opt-out, C-26). AC-16502-1 and AC-16502-2 drive the writer directly through updateDocument; AC-16502-3 drives the finalise CLI end-to-end with a spawn seam that returns the branch name.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-16502-1",
+    "AC-16502-2",
+    "AC-16502-3"
+  ],
+  "id": "TS-203",
+  "usId": "US-16502",
+  "title": "finalise verified-invariant: writer refusal and merge-state precondition",
+  "testCases": [
+    {
+      "id": "TC-203-writer-refuses-manual-verified",
+      "acId": "AC-16502-1",
+      "description": "Fresh project via initProject with FBS-001 at complete; call updateDocument with sets=[{path:'executionStatus', value:'verified'}] and options={}; assert result is RcfError kind='usage' matching /verified is written only by the finalise gate/; FBS on disk still at complete.",
+      "status": "pending",
+      "testPointer": "test/cli/finalise-referee-refusals.test.js::define update FBS.executionStatus=verified is refused without --acknowledge-verified-override (referee-guarantees C-22)"
+    },
+    {
+      "id": "TC-203-writer-accepts-with-override",
+      "acId": "AC-16502-2",
+      "description": "Same scaffold; call updateDocument with options={allowVerifiedOverride:true}; assert result carries an id and FBS on disk reads status verified.",
+      "status": "pending",
+      "testPointer": "test/cli/finalise-referee-refusals.test.js::define update FBS.executionStatus=verified proceeds with allowVerifiedOverride:true (finalise seam, C-22 opt-out)"
+    },
+    {
+      "id": "TC-203-merge-state-refusal-and-opt-out",
+      "acId": "AC-16502-3",
+      "description": "Fresh scaffold with a stub verify subprocess and a spawn seam that returns 'feature/x' as the git branch. First invocation: rcf build finalise <fbs> --url ...; assert exit 4 and stderr matches /git working tree is on branch 'feature\\/x'/. Second invocation: add --allow-pre-merge; assert exit 0, FBS at verified, and stdout matches /Referee-guarantees claim C-26 records the pre-merge decision here/.",
+      "status": "pending",
+      "testPointer": "test/cli/finalise-referee-refusals.test.js::finalise refuses promotion when git is not on a default branch (referee-guarantees C-26)"
+    }
+  ],
+  "status": "approved"
+}

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

@@ -0,0 +1,60 @@
+{
+  "usId": "US-15501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-155",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Agent records a finding with one command",
+  "asA": "agent that has just seen a blueprint or rcf-lite misbehave",
+  "iWant": "to record the finding with a single rcf feedback add call whose flags cover kind, target, anchor, symptom class, severity, title, body and evidence pointers, and to be told nothing was sent",
+  "soThat": "a finding is captured at the moment I see it, without any user-facing interruption and without any network traffic",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15501-1",
+      "description": "rcf feedback add with the required flags (--kind, --target, --anchor, --class, --severity, --title, --body or --body-file, --evidence at least once, optional --harness and --ask-now) writes exactly one JSONL line to .rcf/feedback/entries.jsonl, stamps environment (harness, rcf-lite version, node version, platform) on the entry, prints \"recorded <id> (<n> pending). Nothing sent.\" on stdout, and exits 0. No network syscall is made (assertable by a stubbed submit path and by absence of gh calls).",
+      "given": "a fixture project whose .gitignore covers .rcf/feedback/",
+      "when": "the agent runs rcf feedback add with every required flag",
+      "then": "entries.jsonl has one line whose fields match the flags and the environment stamp; stdout carries the \"recorded\" line; exit code is 0; the network seam has not been touched",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15501-2",
+      "description": "rcf feedback add refuses when the project .gitignore does not cover .rcf/feedback/ and no --force flag is passed. The error names the missing gitignore entry and points at rcf doctor --fix. Exit code is 2. No file is created under .rcf/feedback/.",
+      "given": "a fixture project whose .gitignore lacks the .rcf/feedback/ entry",
+      "when": "the agent runs rcf feedback add without --force",
+      "then": "the command exits 2, stderr names the missing gitignore entry and the rcf doctor --fix remedy, and .rcf/feedback/ is not created",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15501-3",
+      "description": "Ruling R1 (Dave 2026-09-16): --kind blueprint exits 3 ONLY when the target is absent from rcf/manifest.json:blueprints[] (unknown target). A KNOWN blueprint whose registered library carries no resolvable feedback destination (no issuesRepo and no derivable github sourceRef) is exit 0 with the entry stamped destination: unresolved; slice 4 writes the bundle at submit time (design section 7 case 5 wins). In both cases the entry is recorded; stdout carries the recorded line. On the exit-3 branch stderr carries \"destination unresolved: <target>\"; on the exit-0 unresolved branch stderr carries a one-line note naming the library.",
+      "given": "a fixture project whose manifest carries no matching blueprint (exit 3), and a second project whose manifest holds a blueprint from a library with no issuesRepo (exit 0)",
+      "when": "the agent runs rcf feedback add --kind blueprint --target <ref> ... against each",
+      "then": "the unknown-target invocation writes the entry with destination.reason=unresolved, exit code 3, stderr names the target; the known-target-no-destination invocation writes the entry with destination.reason=unresolved, exit code 0, stderr names the library",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15501-4",
+      "description": "Symptom class must be one of the closed enum (docs-mismatch, validate-fails, apply-fails, internal-contradiction, stale-citation, missing-scenario, verb-error, verb-hang, wrong-output, other). Any other value exits 2 with a usage error naming the enum. Severity must be one of blocker, major, minor. Title is capped at 120 chars, body at 8 KB (either --body or --body-file); over-cap inputs exit 2 with a size error.",
+      "given": "a fixture project whose gitignore is set up correctly",
+      "when": "the agent runs rcf feedback add with an invalid class or severity, an oversize title, or an oversize body",
+      "then": "each invalid invocation exits 2, stderr names the specific violation and the enum or size limit; no entry is written",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15501-5",
+      "description": "When --kind blueprint is passed and the target resolves to a known blueprint in rcf/manifest.json:blueprints[], the recorded entry additionally stamps blueprintVersion, libraryPrefix, libraryRef and resolvedSha (or tarballSha256 when the pin is a tarball) on target, sourced from the manifest record and the matching rcf/blueprint-libraries.json registry entry. Core entries (kind core) carry none of these fields. A shelf blueprint (no libraryPrefix on the manifest record) carries blueprintVersion and resolvedSha but leaves libraryPrefix and libraryRef unset.",
+      "given": "a fixture project with three applied blueprints: one shelf, one library (git pin) and one library (tarball pin), plus one core entry",
+      "when": "the agent runs rcf feedback add --kind blueprint for each blueprint target and --kind core for the core entry",
+      "then": "each blueprint entry carries the expected blueprint-specific stamps sourced from manifest + registry (shelf omits libraryPrefix and libraryRef; git-pin carries resolvedSha; tarball-pin carries tarballSha256); the core entry carries none of the four fields",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

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

@@ -0,0 +1,33 @@
+{
+  "usId": "US-15502",
+  "prdId": "PRD-001",
+  "reqId": "REQ-155",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator lists and inspects what has been recorded",
+  "asA": "operator who wants to see what the agent has logged this session",
+  "iWant": "to run rcf feedback list (and rcf feedback status) to see pending entries and their state without triggering any submission",
+  "soThat": "I can decide by hand what to do with the log, and doctor can report the same counts on demand",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15502-1",
+      "description": "rcf feedback list prints one line per pending entry (id, target, symptom class, severity, one-line title) sorted by recordedAt ascending; --all includes submitted, deferred, discarded, bundled entries with their status column; --json emits a stable machine-readable shape. Neither invocation touches the network or writes to entries.jsonl.",
+      "given": "a fixture project with three entries of mixed status",
+      "when": "the operator runs rcf feedback list and then rcf feedback list --all --json",
+      "then": "default output shows only pending entries in order; --all includes every state; --json parses to an array whose length equals total entries; no file mutation, no network calls",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15502-2",
+      "description": "rcf feedback status prints counts by status, the opt-out state (from rcf/feedback-settings.json or RCF_FEEDBACK_ASK env), a destination table for every applied blueprint (rows: target, resolved repo or unresolved with reason, visibility hint), and gh availability (present, authed, absent, unknown). --json emits the same as machine-readable object. The status shape is the one the SessionStart hook and doctor both consume.",
+      "given": "a fixture project with several blueprints applied and gh present",
+      "when": "the operator runs rcf feedback status --json",
+      "then": "the JSON carries counts, optOut boolean, destinations[] with target/repo/visibility, and gh { present, authed } fields; the text form prints the same as a readable summary",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

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

@@ -0,0 +1,33 @@
+{
+  "usId": "US-15503",
+  "prdId": "PRD-001",
+  "reqId": "REQ-155",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator defers or discards recorded findings",
+  "asA": "operator who has decided not to submit some findings",
+  "iWant": "to mark the pending batch deferred for this session, or discard specific entries entirely, without any network activity",
+  "soThat": "a \"not now\" or \"never for this one\" answer is honoured immediately and the state is durable across the next boot",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15503-1",
+      "description": "rcf feedback defer appends a state line for every currently pending entry stamping status: deferredUntilSession with the current sessionId; the entries stay in the log so the next session sees them; the current session-end hook does not re-ask. Exit 0. Nothing is sent.",
+      "given": "a fixture project with two pending entries and a known sessionId",
+      "when": "the operator runs rcf feedback defer",
+      "then": "entries.jsonl grows by two lines each carrying the deferred status and sessionId; a folded read shows both entries at status deferredUntilSession; no network call was made",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15503-2",
+      "description": "rcf feedback discard <id> marks only the named entries discarded (kept in the log for 30 days, then pruned on the next add). --all discards every pending entry. Discarded entries are excluded from list default output, hidden from the SessionStart carry-over count, and never appear in a submit or bundle. Exit 0.",
+      "given": "a fixture project with three pending entries",
+      "when": "the operator runs rcf feedback discard fb-<a> fb-<b> then rcf feedback list",
+      "then": "the two named entries are folded to status discarded; list shows only the remaining entry; the next add older than 30 days prunes them",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

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

@@ -0,0 +1,51 @@
+{
+  "usId": "US-15601",
+  "prdId": "PRD-001",
+  "reqId": "REQ-156",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator sees the exact issue text and what was stripped before consenting",
+  "asA": "operator being asked to submit findings",
+  "iWant": "rcf feedback preview to print the exact rendered issue title and body, the destination repo and its visibility, and a redaction ledger that lists every rule-triggered replacement so I can see what was stripped",
+  "soThat": "my yes is informed and nothing surprising leaves the machine",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15601-1",
+      "description": "rcf feedback preview renders each pending entry as the title and body that would be filed on GitHub (using src/feedback/render.js templates from section 4.3 of the design), lists the destination repo and its declared visibility (public, private, or unresolved), and prints the redaction ledger as diff-style lines (\"- before  + after\") with the rule name. --json emits the same as a machine-readable object per entry. No network calls. The kv-secret rule (design section 5 rule 5) is driven by the shared SECRET_KEY_VOCABULARY constant exported from src/feedback/redact.js (design amendment R3a) so the first-pass redactor, the residual safeguard pass and the rule-9 URL-credential scanner cover exactly the same open vocabulary of key stems (secret, token, password, passwd, passphrase, pw, pwd, pass, key, apikey/api_key/api-key, privatekey/private_key/private-key, accesskey/access_key/access-key, clientsecret/client_secret/client-secret, bearer, credential/credentials/cred/creds, session, cookie, signature, sig, salt; hash carries a 16+-value length guard); the match is right-bounded at a word edge so `keyword` and `authors` do not fold but `dbpassword` still does. Design amendment R4 (round 5) extends the rule-5 pass so a vocabulary key labelling a value-shape token of 8+ chars with any separator (markdown table pipes, whitespace runs, tabs, hyphens, arrows, HTML numeric entities, or the prose bridges is / was / set to) also folds, with a mixed-classes gate on the value that keeps ordinary prose (`the password is required`, `the password field is required`) intact.",
+      "given": "a fixture project with one entry whose body contains an absolute path, an email, a non-allowlisted hostname, a token-shaped string, a private IPv4 (10.0.5.7), an em-dash, an oversize body block, an operator name that matches a seeded rcf/.identity/profile.md ## Name line, AND at least one shortname-key secret (`pw=`), one URL-embedded credential (a Slack webhook path), one markdown-table row with a vocabulary key and a mixed-class value (`| password | Sup3rSecretV@lue!! |`) and one prose bridge (`the password Sup3rSecretV@lue1234 is bad`)",
+      "when": "the operator runs rcf feedback preview --json",
+      "then": "the JSON output carries titleRendered, bodyRendered, destination { repo, visibility }, and ledger[] entries whose rule names include project-root, absolute-path, email, hostname, secret-token, private-ip, operator-identity, size-shape and url-credential; the rendered body contains none of the original secret substrings (including the shortname-key value, the webhook path segment, the markdown-table value and the prose-bridge value), none of the private IP, none of the operator-name tokens, no em-dash, and is at most 8 KB",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15601-2",
+      "description": "When a body still matches a rule-5 secret pattern on the second redaction pass, preview marks the entry as \"residual secret at line N\" and submit refuses that entry. Other pending entries are unaffected. The exact refusing line is shown to the operator so the agent can rewrite the body.",
+      "given": "a fixture project with two entries, one containing a token that survives the first pass through obfuscation and one clean",
+      "when": "the operator runs rcf feedback preview then rcf feedback submit --yes",
+      "then": "the tainted entry is shown with the residual-secret line; submit does not send the tainted entry; the clean entry is submitted (or fallbacks to bundle if that path applies); exit code is 3 while any residual-secret entry is still pending",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15601-3",
+      "description": "The stored entries.jsonl body is never mutated by preview. A byte-for-byte comparison of entries.jsonl before and after preview is identical; the redaction lives only in the rendered output.",
+      "given": "a fixture project with entries whose bodies contain redactable content",
+      "when": "the operator runs rcf feedback preview repeatedly",
+      "then": "a sha-256 of entries.jsonl before and after each preview run matches",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15601-4",
+      "description": "After rendering and normalising the fully assembled issue body (and, for the bundle path, each bundle file), a final whole-text residual-secret pass runs findResidualSecrets over the whole text with multiline patterns. Any hit means the entry stays pending (preview marks it refused-residual and submit refuses that entry with exit 3) and no create/comment/bundle-write occurs for it. The safeguard is defence-in-depth: it catches multiline shapes (e.g. an em-dash-delimited PEM block that survives per-field redaction of a slice-2-style body) that a per-line scan could not see. The safeguard shares the SECRET_KEY_VOCABULARY constant with the first-pass redactor and the rule-9 URL-credential scanner (design amendment R3a), so a shortname-key value (`pw=...`, `pwd=...`) or a webhook-path shape (`/services/<token>`, `/api/webhooks/<token>`, `/bot<token>/method`) that reappears after per-field normalisation is caught by the same set the first pass used.",
+      "given": "a fixture project with an entry whose body assembles into a rendered issue body containing a shape a per-line residual scan would miss (a multiline PEM block or a token buried inside a longer identifier)",
+      "when": "the operator runs rcf feedback preview then rcf feedback submit --yes",
+      "then": "preview surfaces the residual line and the tainted entry stays pending; submit exits 3 without a create/comment for that entry and without writing a bundle whose text carries the residual shape",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-17T00:36:18Z"
+}

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

@@ -0,0 +1,42 @@
+{
+  "usId": "US-15701",
+  "prdId": "PRD-001",
+  "reqId": "REQ-157",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The same finding from many reporters folds into one issue",
+  "asA": "blueprint maintainer receiving reports",
+  "iWant": "ten reporters hitting the same defect on the same anchor to land as one issue with nine +1 comments carrying their environments, not ten separate issues",
+  "soThat": "triage is cheap and duplicate storms do not swamp the tracker",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15701-1",
+      "description": "fingerprint(entry) returns the first 12 hex chars of sha-256 over \"<kind>|<targetKey>|<anchor>|<symptomClass>\" where targetKey is the effective slug for blueprints (no version) or the verb path for core, anchor is upper-cased or \"-\" when absent, and symptomClass is one of the closed enum. Same fingerprint across two entries whose blueprint versions differ; different fingerprint when the anchor or class differs.",
+      "given": "a fixture corpus of five entries: same-defect different-version, same-defect different-anchor, same-defect different-class, missing-anchor pair (title-only fallback), and one clean",
+      "when": "fingerprint() is called on each entry",
+      "then": "the versioned pair yields identical fingerprints; the anchor and class variants yield different fingerprints; the missing-anchor pair uses the \"<kind>|<targetKey>|<symptomClass>|<normalisedTitle>\" fallback (first eight tokens, punctuation and stop-words stripped, lower-case)",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-15701-2",
+      "description": "On submit, per pending entry, gh search issues is called for the destination repo with query \"rcf-feedback-fingerprint: <fp>\", --match body, --state open, --limit 5. Exactly one hit: gh issue comment on that number, comment body carries \"+1 from another reporter\" plus the Environment table and the redacted body only when it differs from the original by more than the environment lines. Zero hits: gh issue create. More than one hit: comment on the lowest number and mention the others.",
+      "given": "a fake gh module (via RCF_FEEDBACK_GH_MODULE) whose search stub yields zero, one and two hits in three sequential invocations, and one pending entry per case",
+      "when": "rcf feedback submit --yes runs three times",
+      "then": "the zero-hit case calls gh issue create; the one-hit case calls gh issue comment on the returned number; the two-hit case calls gh issue comment on the smaller number and includes \"also see #<other>\" in the comment body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15701-3",
+      "description": "When gh search issues is unavailable or errors (rate-limit, GHES search off, non-zero exit), submit falls through to gh issue create for that entry and the state line stamps dedupe: unchecked. Closed issues are never matched; if --state closed search finds an issue with the same fingerprint the created new issue body carries \"previously reported and closed as #<n>\".",
+      "given": "a fake gh module whose search stub throws for one call and returns a closed match for the next",
+      "when": "rcf feedback submit --yes runs twice with one pending entry each",
+      "then": "the first entry is created with dedupe: unchecked in state; the second is created with a body reference to the previously closed issue number",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

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"
+}