rcf-lite 0.27.0 → 0.28.0

package/rcf/requirements/req-158.json

@@ -0,0 +1,13 @@
+{
+  "reqId": "REQ-158",
+  "prdId": "PRD-001",
+  "title": "Reports reach the owning repo",
+  "description": "A finding is filed on the repo that owns the code the finding is about: Stravica/rcf-lite for shelf blueprints and core, and the library-declared repo for library blueprints. Library owners declare their destination via an optional issues field on library.json; the consuming project does not guess. Applied blueprints without a declared destination fall back to derivation from the library git source when unambiguous, else route to the outbox and name the library publisher contact. Doctor lists any registered library missing a destination as a warn-only finding.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/requirements/req-159.json

@@ -0,0 +1,13 @@
+{
+  "reqId": "REQ-159",
+  "prdId": "PRD-001",
+  "title": "Consent-gated submission under the reporter identity",
+  "description": "Nothing is submitted without an explicit yes. When yes is given, issues are filed under the operator own GitHub login via the ambient gh CLI; the tool never asks for or stores a token, never calls the network for authentication, and never speaks for anyone but the operator. Labels are requested best-effort and per-repo label discovery drops names the destination does not carry; the title prefix and body fingerprint stay load-bearing for triage. Submit refuses without --yes unless a TTY operator confirms.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/requirements/req-160.json

@@ -0,0 +1,13 @@
+{
+  "reqId": "REQ-160",
+  "prdId": "PRD-001",
+  "title": "No path leaves the operator stuck",
+  "description": "Every failure mode of the submit path routes to a local bundle file with a one-line message that names the reason, the repo URL to paste into, and where the bundle was written. gh missing, gh not logged in, repo unreachable, viewerPermission NONE on a private repo, issues disabled, create or comment failure and unresolved destination all map to a bundle rather than a stall. Bundled entries are terminal (not re-asked) so the operator is never nagged about the same finding; a hand-driven re-submit is supported for one entry once access exists.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/requirements/req-161.json

@@ -0,0 +1,13 @@
+{
+  "reqId": "REQ-161",
+  "prdId": "PRD-001",
+  "title": "One ask per session, at a pause, never automatic",
+  "description": "The operator is asked at most once per session and only when the agent is genuinely idle: not in the middle of a fix and not on the same day the entry was recorded unless a blocker forces it. The quiet rule (15 minute age or queue complete or carried over or --ask-now) is configurable via quietMinutes in rcf/feedback-settings.json. The ask is offered by the harness hook on Stop and by RULE 17 in the managed block as the belt-and-braces fallback. rcf feedback opt-out silences the ask permanently for a project; RCF_FEEDBACK_ASK=0 silences it per user or per CI run; RCF_FEEDBACK_DISABLE=1 turns even the local log off.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/requirements/req-162.json

@@ -0,0 +1,13 @@
+{
+  "reqId": "REQ-162",
+  "prdId": "PRD-001",
+  "title": "Agents know when to log and when to ask",
+  "description": "RULE 17 in the managed instructions block tells every harness (Claude Code and Codex) when to run rcf feedback add, how to ask exactly once at a natural pause, and which of preview, submit --yes, defer and opt-out to run in each branch. The rule is static text (no versions, no dates) so the block hash moves once on the release that ships it, and it is loaded into CLAUDE.md and AGENTS.md by rcf init through the existing managed-block mechanism. It names all four verbs and the redaction posture so an agent under pace still follows the shape when the harness hook has not been trusted.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/requirements/req-163.json

@@ -0,0 +1,13 @@
+{
+  "createdAt": "2026-09-16T22:20:45Z",
+  "updatedAt": "2026-09-16T22:20:45Z",
+  "description": "Referee-guarantees docs page (how-it-works/what-the-referee-guarantees) promises that `rcf define validate` proves every reference in every document resolves, so a walked tree that passes has nothing pointing at nothing. The 0.27.0 walker checks the parent-id fields and the FBS / TS / EVAL / CN cross-links, but two ADR-schema-declared reference fields, supersededBy and relatedAdrs, are declared in the ADR schema without being walked: a bad target passes validate. This train closes the gap by walking both fields inside collectBrokenReferences, keeping the existing brokenReference error kind, and reporting the exact ADR file + field on failure. Chain: referee-guarantees docs claims C-7 and C-38 (audit at reviews/2026-09-15-docs-claims-audit/how-it-works__what-the-referee-guarantees.json). No schema change (the schema already declares both fields); rcf-lite behaviour widens, and any project whose ADRs have stale supersession pointers surfaces the defect the next time validate runs.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "reqId": "REQ-163",
+  "prdId": "PRD-001",
+  "title": "Referee guarantee: `rcf define validate` walks every schema-declared reference field on ADR (supersededBy, relatedAdrs) so the docs-page 'nothing points at nothing' claim holds",
+  "version": "0.1.0",
+  "status": "draft"
+}

package/rcf/requirements/req-164.json

@@ -0,0 +1,13 @@
+{
+  "createdAt": "2026-09-16T22:28:54Z",
+  "updatedAt": "2026-09-16T22:28:54Z",
+  "description": "Referee-guarantees docs page states without qualification that a requirement counts as covered only when every acceptance criterion beneath it has a resolving Test Case, and that a stub or stale pointer fails the coverage gate exactly as a missing test does when the displayed command (`rcf audit coverage`) is run. The 0.27.0 shipped default is shallow-any, so the plain command does not enforce that; strict is per-AC-strict but is opt-in via `--strict`. This train flips the shipped default: strict is the default, `--mode shallow-any` is the explicit opt-out for author-time exploration (prints gaps, exits 0), and the legacy `--strict` flag stays as a no-op alias so existing CI, blueprints and dogfood scripts stay green. `--mode shallow-any --strict` is a usage refusal (exit 2) so a scripted invocation cannot silently disagree with itself. CHANGELOG carries a migration note under [Unreleased]. Repo's own CI dogfood invocation is updated to the shipped default. Closes referee-guarantees docs claims C-11 and C-14 (audit at reviews/2026-09-15-docs-claims-audit/how-it-works__what-the-referee-guarantees.json).",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "reqId": "REQ-164",
+  "prdId": "PRD-001",
+  "title": "Referee guarantee: `rcf audit coverage` is strict-by-default; `--mode shallow-any` is the explicit opt-out; `--strict` remains a no-op alias",
+  "version": "0.1.0",
+  "status": "draft"
+}

package/rcf/requirements/req-165.json

@@ -0,0 +1,13 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "description": "Referee-guarantees docs page promises that `rcf build finalise` is the only path that writes verified, that a chain that says verified traces to an actual post-merge runtime check, and that the finalise gate refuses on the three per-AC verdicts the aggregator already emits: UI-BASELINE-UNMET (docs claim C-28; also covers a block-severity probe-pack failure, C-36), BROWSER-VERIFICATION-MISSING (C-29) and SCOPE-MISMATCH (C-30). The 0.27.0 finalise CLI only branched on MOCK-ONLY-DECLARED / BLOCKED-BY-DECLARATION and EVAL-MISSING / EVAL-BELOW-THRESHOLD; the three new verdicts were derived on the report but did not gate finalise. The manual override path (`rcf define update FBS.executionStatus=verified`) was accepted by the writer, defeating the C-22 promise. This train wires the three per-AC refusals in finalise (no ack path: the refusals are honest; fix the AC or its scope), gates the manual override behind `--acknowledge-verified-override` on `rcf define update` (per the escalation clause: existing WSD projects may still need the escape valve; the writer's default is now the documented behaviour), and adds a git default-branch precondition to finalise with `--allow-pre-merge` as the deliberate pre-merge dry-run opt-out. Closes referee-guarantees docs claims C-22 / C-26 / C-28 / C-29 / C-30 / C-36 (audit at reviews/2026-09-15-docs-claims-audit/how-it-works__what-the-referee-guarantees.json). C-33 (shipWithoutEval manifest field) remains open: the write path already exists (skips schema validation), but the rcf-schemas 0.6.2 manifest schema does not yet declare the field; the exact delta needed lands in the ship-without-eval.js comment and in the report for this dispatch. C-38 (per-check applicable:false in browserVerificationProbePackCheck) is also blocked on the rcf-schemas bump; source comments already flag it.",
+  "category": "functional",
+  "domain": "functional",
+  "priority": "must",
+  "reqId": "REQ-165",
+  "prdId": "PRD-001",
+  "title": "Referee guarantee: `rcf build finalise` refuses UI-BASELINE-UNMET / BROWSER-VERIFICATION-MISSING / SCOPE-MISMATCH; verified traces to a post-merge run; manual override is gated",
+  "version": "0.1.0",
+  "status": "draft"
+}

package/rcf/tacs/tac-4101-feedback-cli.json

@@ -0,0 +1,77 @@
+{
+  "tacId": "TAC-4101-feedback-cli",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback CLI verb family",
+  "purpose": "Own the rcf feedback core verb and its sub-dispatcher (add, list, preview, submit, defer, discard, opt-in, opt-out, hook, status), exposing the surface the agent, the operator and the harness hooks all call.",
+  "responsibilities": [
+    "Register feedback in bin/rcf.js CORE map alongside init, doctor, guidance, mcp, version",
+    "Parse and validate sub-verb flags and enums before touching store or network",
+    "Return the documented exit codes per sub-verb (0 success, 2 usage, 3 outcome with residual pending)",
+    "Export HELP text for the help-parity test and mirror the core verb help conventions",
+    "Route each sub-verb to store, redact, render, destination, gh, hook without any cross-module state"
+  ],
+  "internalStructure": "src/cli/feedback.js is a sub-dispatcher with a HELP export and one handler per sub-verb; each handler reads flags, calls into src/feedback/* pure modules, and prints the shaped result. Handlers never shell out directly; the gh call sits behind src/feedback/gh.js.",
+  "interfaces": [
+    {
+      "name": "feedbackMain",
+      "kind": "function",
+      "description": "Argv-driven main; matches the core-verb signature the top-level dispatcher expects."
+    },
+    {
+      "name": "HELP",
+      "kind": "constant",
+      "description": "Static help text asserted by the help-parity test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "TAC-4102-feedback-store",
+      "kind": "tac",
+      "tacId": "TAC-4102-feedback-store",
+      "description": "All state reads and writes."
+    },
+    {
+      "name": "TAC-4103-feedback-redact",
+      "kind": "tac",
+      "tacId": "TAC-4103-feedback-redact",
+      "description": "Preview and submit pipelines."
+    },
+    {
+      "name": "TAC-4104-feedback-fingerprint",
+      "kind": "tac",
+      "tacId": "TAC-4104-feedback-fingerprint",
+      "description": "Fingerprint per entry."
+    },
+    {
+      "name": "TAC-4105-feedback-render",
+      "kind": "tac",
+      "tacId": "TAC-4105-feedback-render",
+      "description": "Title, body and bundle rendering."
+    },
+    {
+      "name": "TAC-4106-feedback-destination",
+      "kind": "tac",
+      "tacId": "TAC-4106-feedback-destination",
+      "description": "Destination resolution."
+    },
+    {
+      "name": "TAC-4107-feedback-gh",
+      "kind": "tac",
+      "tacId": "TAC-4107-feedback-gh",
+      "description": "The single gh shell-out seam."
+    },
+    {
+      "name": "TAC-4108-feedback-hook",
+      "kind": "tac",
+      "tacId": "TAC-4108-feedback-hook",
+      "description": "Hook handler; called by hook sub-verb."
+    }
+  ],
+  "tradeoffs": "A single core verb keeps the surface easy to reference in RULE 17 and in docs; the cost is a moderately sized sub-dispatcher, matched by preflight and other multi-verb families already in the tree.",
+  "notes": "The verb is core, not grouped, because it spans discover-to-audit and is invoked from harness hooks; OLD_FLAT_MAP is untouched (no legacy form existed). Design section 9 decision: no MCP tool for feedback in v1 (rejected: an rcf_feedback_add MCP tool, adds a second code path to test before the first has users; add when an MCP-only harness appears).",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T14:14:36Z"
+}

package/rcf/tacs/tac-4102-feedback-store.json

@@ -0,0 +1,50 @@
+{
+  "tacId": "TAC-4102-feedback-store",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback local store",
+  "purpose": "Own the on-disk feedback log at .rcf/feedback/entries.jsonl (append-only, one JSON object per line, folded by id), the per-session ask ledger at .rcf/feedback/state.json, and the outbox bundle directory .rcf/feedback/outbox/. Contribute the gitignore entry so the store never rides a git push.",
+  "responsibilities": [
+    "Append entry and state lines atomically with no reader ever seeing a partial line",
+    "Fold entries.jsonl by id, last line wins, when returning current state",
+    "Export feedbackGitignoreEntry so managed-gitignore aggregation picks up the path on doctor --fix",
+    "Refuse a first write when the gitignore does not cover .rcf/feedback/ and --force is absent",
+    "Provide state helpers for asked-records, deferred-until-session, discarded, submitted and bundled transitions"
+  ],
+  "internalStructure": "src/feedback/store.js exposes readEntries(root), appendEntry(root, entry), appendState(root, transition) and readSettings(root); a small ensureGitignore(root, opts) enforces the pre-write check. Outbox writes go through a separate helper that computes the filename from the destination slug and the ISO timestamp.",
+  "interfaces": [
+    {
+      "name": "readEntries",
+      "kind": "function",
+      "description": "Load and fold the JSONL log to current-state entries."
+    },
+    {
+      "name": "appendEntry",
+      "kind": "function",
+      "description": "Append one entry object as a JSONL line."
+    },
+    {
+      "name": "appendState",
+      "kind": "function",
+      "description": "Append one state-transition line for an existing id."
+    },
+    {
+      "name": "feedbackGitignoreEntry",
+      "kind": "constant",
+      "description": "Managed-gitignore contribution consumed by src/setup/managed-gitignore.js."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "node:fs/promises",
+      "kind": "external",
+      "description": "Filesystem I/O; the store is deliberately synchronous where safe."
+    }
+  ],
+  "tradeoffs": "Append-only JSONL is trivial to write correctly and to inspect by eye; the cost is a fold on every read, which is negligible at the entry counts a single project will ever see.",
+  "notes": "Gitignored, not committed. Raw entries can hold what redaction removes; committing them would leak on the next push for a public project.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4103-feedback-redact.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-4103-feedback-redact",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback redactor",
+  "purpose": "Rule-based, deterministic redaction of any string that would leave the machine (issue title, body, evidence pointers). No LLM anywhere; the ledger of every replacement is what the operator sees on preview.",
+  "responsibilities": [
+    "Apply the eight redaction rules from design section 5 to title, body and evidence strings",
+    "Return a ledger of { rule, before, after, count } entries for the operator disclosure",
+    "Refuse on residual-secret matches (second pass) with a line pointer so the offending body is not sent",
+    "Ship a bundled allowlist of vendor hosts and honour the extension array on rcf/feedback-settings.json"
+  ],
+  "internalStructure": "src/feedback/redact.js is a pure module: redact(text, context) -> { text, ledger[] } plus small per-rule helpers. src/feedback/redact-allowlist.json ships the vendor host set; the extension array is merged at call time.",
+  "interfaces": [
+    {
+      "name": "redact",
+      "kind": "function",
+      "description": "Redact one string with the eight rules; return the redacted text and the ledger."
+    },
+    {
+      "name": "RedactionContext",
+      "kind": "type",
+      "description": "projectRoot, projectName, operatorName, gitRemote, allowHosts."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "node:crypto",
+      "kind": "external",
+      "description": "Entropy heuristic implementation for rule 5 (secret-looking strings)."
+    }
+  ],
+  "tradeoffs": "Rule-based redaction is testable with a fixture corpus and deterministic under review; the cost is that it will occasionally over-redact (a benign name that matches an entropy rule), which is what the disclosure ledger exists to catch.",
+  "notes": "The stored entry is never mutated by redaction; the rendered output is what leaves.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4104-feedback-fingerprint.json

@@ -0,0 +1,33 @@
+{
+  "tacId": "TAC-4104-feedback-fingerprint",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback fingerprint",
+  "purpose": "Deterministic 12-hex fingerprint per entry that keys the same-defect fold on issue create.",
+  "responsibilities": [
+    "Compute the first 12 hex characters of sha-256 over the canonical fingerprint input",
+    "Exclude blueprint version from the input so a defect across versions folds",
+    "Fall back to normalised-title tokens when the anchor is absent, and warn in preview"
+  ],
+  "internalStructure": "src/feedback/fingerprint.js is pure and tiny: fingerprint(entry) -> hex12 plus normaliseTitle(title) helper for the fallback.",
+  "interfaces": [
+    {
+      "name": "fingerprint",
+      "kind": "function",
+      "description": "Compute the entry fingerprint from its canonical input."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "node:crypto",
+      "kind": "external",
+      "description": "sha-256 for the fingerprint hash."
+    }
+  ],
+  "tradeoffs": "A tiny fingerprint (12 hex = 48 bits) risks a collision at very large corpuses; at the scale of a single blueprint tracker it is safe, and issues carry the full-anchor context in the body so a maintainer resolves a rare collision by hand.",
+  "notes": "The fingerprint appears twice in the body (visible line and HTML comment) so maintainer edits do not lose it.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4105-feedback-render.json

@@ -0,0 +1,45 @@
+{
+  "tacId": "TAC-4105-feedback-render",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback renderer",
+  "purpose": "Deterministic templates for issue title and body, the +1 comment body, and the outbox bundle file. The output is what preview shows and what leaves on submit.",
+  "responsibilities": [
+    "Render the issue title as \"[<effective-slug>] <title>\" for blueprints and \"[rcf-lite] <title>\" for core",
+    "Render the body with the Evidence and Environment tables, the visible fingerprint line and its HTML-comment twin",
+    "Render the outbox bundle header and one section per entry (title first, then body) so a paste is one-shot",
+    "Consume redacted strings and the redaction ledger; never re-run redaction itself"
+  ],
+  "internalStructure": "src/feedback/render.js exposes renderIssue(entry, redacted), renderComment(entry, redacted, deltaOnly), renderBundle(destinationInfo, entries). All output is UTF-8, LF line endings, ASCII hyphens only (register rule and fingerprint stability).",
+  "interfaces": [
+    {
+      "name": "renderIssue",
+      "kind": "function",
+      "description": "Return { title, body, labels[] } for a create call."
+    },
+    {
+      "name": "renderComment",
+      "kind": "function",
+      "description": "Return the comment body for a +1 add."
+    },
+    {
+      "name": "renderBundle",
+      "kind": "function",
+      "description": "Return the markdown bundle string for outbox files."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "TAC-4103-feedback-redact",
+      "kind": "tac",
+      "tacId": "TAC-4103-feedback-redact",
+      "description": "The renderer consumes redacted strings the caller supplies."
+    }
+  ],
+  "tradeoffs": "Static templates keep the shape reviewable by eye and byte-comparable in tests; the cost is that template drift requires golden updates, which is exactly the discipline the tests exist for.",
+  "notes": "The docs-site \"submit a blueprint idea\" form reuses these templates verbatim so triage sees one shape from both producers.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4106-feedback-destination.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-4106-feedback-destination",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback destination resolver",
+  "purpose": "Resolve a pending entry to its destination repo and visibility, using the library.json issues field, the rcf/blueprint-libraries.json snapshot, the manifest sourceRef derivation, and the shelf-and-core constant.",
+  "responsibilities": [
+    "Walk entry.target -> manifest.blueprints[] -> registry entry -> issuesRepo, with sourceRef derivation as fallback",
+    "Return a { repo, visibility, derived, reason } shape; unresolved carries a reason for the doctor row",
+    "Route --kind core and shelf blueprints to the constant sourced from package.json:bugs.url (a test pins the constant)",
+    "Report the doctor feedback-destinations warn row for every registered library without a resolvable destination"
+  ],
+  "internalStructure": "src/feedback/destination.js is a pure resolver; the constant lives at the top of the module and is exported for the test to compare against package.json.",
+  "interfaces": [
+    {
+      "name": "resolve",
+      "kind": "function",
+      "description": "Given an entry and the manifest+registry, return the destination shape."
+    },
+    {
+      "name": "CORE_REPO",
+      "kind": "constant",
+      "description": "The Stravica/rcf-lite constant; pinned to package.json:bugs.url in a test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "src/blueprint/library-registry.js",
+      "kind": "external",
+      "description": "RegistryEntry read for issuesRepo and issuesVisibility fields."
+    }
+  ],
+  "tradeoffs": "A declared destination on library.json requires library owners to author one field; the cost is a one-time PR per library, in exchange for correctness on every consuming project.",
+  "notes": "A library mirrored from a fork would have derivation pointing at the fork; the declared issues field is why derivation is only a fallback.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4107-feedback-gh.json

@@ -0,0 +1,43 @@
+{
+  "tacId": "TAC-4107-feedback-gh",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback gh adapter",
+  "purpose": "The single place that shells out to gh. Named seam via RCF_FEEDBACK_GH_MODULE so every test replaces gh with a fake that records calls.",
+  "responsibilities": [
+    "Provide ghLabelList, ghIssueSearch, ghIssueCreate, ghIssueComment, ghRepoView (viewerPermission, visibility, hasIssuesEnabled), ghAuthStatus",
+    "Never read GH_TOKEN or GITHUB_TOKEN; never spawn gh auth login; never mutate process.env",
+    "Return typed results, not raw shell output; errors carry the classified reason (network, 4xx, 5xx, ratelimit, notFound)"
+  ],
+  "internalStructure": "src/feedback/gh.js exports the interface; RCF_FEEDBACK_GH_MODULE names an alternative module (import() at test time) that exports the same signatures. This mirrors the verifier launchAgent override in src/verify/engine/launcher.js.",
+  "interfaces": [
+    {
+      "name": "ghIssueCreate",
+      "kind": "function",
+      "description": "Create one issue on a repo with title, body and labels; return { url, number }."
+    },
+    {
+      "name": "ghIssueSearch",
+      "kind": "function",
+      "description": "Search issues on a repo by body query; return matches."
+    },
+    {
+      "name": "ghIssueComment",
+      "kind": "function",
+      "description": "Comment on an issue; return { url }."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "gh",
+      "kind": "external",
+      "description": "The GitHub CLI; the tool never handles tokens itself."
+    }
+  ],
+  "tradeoffs": "gh is a dependency the reporter chooses to install; the cost is a fallback bundle path when gh is missing, which the design considers a feature rather than a bug.",
+  "notes": "A future MCP-only harness would call the CLI too; a native gh-lib port is not planned for v1.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4108-feedback-hook.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-4108-feedback-hook",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "Feedback harness hook",
+  "purpose": "The single hook handler for both Claude Code and Codex, exposing the quiet rule as a pure function and the per-harness output shape as a thin wrapper.",
+  "responsibilities": [
+    "Read harness JSON from stdin (session_id, cwd, hook_event_name, stop_hook_active, last_assistant_message) and never block longer than 1 second",
+    "Apply the quiet rule (design section 3.5) and return ask or silent",
+    "Emit the exit-2-plus-stderr shape for Claude Code and the JSON block shape for Codex",
+    "Install itself under .claude/settings.json and .codex/hooks.json via a mergeable installer that never clobbers other hooks",
+    "Report missing-hook and foreign-hook conditions to doctor and repair missing hooks under --fix"
+  ],
+  "internalStructure": "src/feedback/hook.js exports shouldAsk(state) -> \"ask\"|\"silent\" (pure) and emit(harness, decision, entries) (side-effect). src/setup/feedback-hooks.js merges the entries into .claude/settings.json and .codex/hooks.json; doctor reuses the installer helpers for the report.",
+  "interfaces": [
+    {
+      "name": "shouldAsk",
+      "kind": "function",
+      "description": "Pure decision on the quiet rule; unit-tested across the full table."
+    },
+    {
+      "name": "emit",
+      "kind": "function",
+      "description": "Per-harness output; exit code and shape."
+    },
+    {
+      "name": "installHooks",
+      "kind": "function",
+      "description": "Merge the hook entries into the two harness config files."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "TAC-4102-feedback-store",
+      "kind": "tac",
+      "tacId": "TAC-4102-feedback-store",
+      "description": "Read state and settings; write the asked ledger."
+    }
+  ],
+  "tradeoffs": "Two harness config files to maintain and one handler; the cost is small (one merge pattern per file) and the benefit is one implementation of the quiet rule for both harnesses.",
+  "notes": "The asked record is appended before the emit path, so a crash between emit and reply cannot cause a second ask.",
+  "createdAt": "2026-09-16T13:45:23.000Z",
+  "updatedAt": "2026-09-16T13:45:23.000Z"
+}

package/rcf/tacs/tac-4109-referee-validate-adr-crosslinks.json

@@ -0,0 +1,20 @@
+{
+  "createdAt": "2026-09-16T22:20:45Z",
+  "updatedAt": "2026-09-17T01:05:07Z",
+  "tacId": "TAC-4109-referee-validate-adr-crosslinks",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "referee-validate ADR cross-link walker",
+  "purpose": "Extend the load-then-invert walker's referential-integrity pass (`collectBrokenReferences` in `packages/rcf-lite/src/core/store/walker.js`) to walk the strong ADR cross-link the 0.27.0 walker skipped: `supersededBy` (single ADR id). A present target must resolve to a loaded ADR; a mismatch surfaces as a `brokenReference` error named to the ADR file, keyed by field. An absent or empty field is silent. The soft back-reference `relatedAdrs` is deliberately left unwalked at this phase (AC-16301-2 compatibility carry) so the ratified `rcf define blueprint supersede` workflow keeps working; tightening it is a schemas follow-up.",
+  "responsibilities": [
+    "Inside `collectBrokenReferences`, after the existing ADR->TAD parent check, walk `supersededBy` when it is a non-empty string and delegate to the existing `check` helper with expectedKind `adr` (AC-16301-1).",
+    "Leave `relatedAdrs` unwalked here (AC-16301-2 compatibility carry): the ratified `rcf define blueprint supersede` workflow writes a project ADR whose `relatedAdrs` lists both the applied blueprint ADR and the not-yet-on-disk incoming blueprint ADR, so walking would refuse the workflow between the supersede write and the closing re-add. Tightening moves to the schemas follow-up (value-narrow to applied ADR ids, or a workflow-aware exception on the supersede write path).",
+    "Reuse the existing `brokenReference` error shape (kind, documentId, filePath, field, rule) so downstream consumers of `formatErrors` need no change.",
+    "Ensure the widened check contributes to `tree.brokenIds` exactly the way the existing checks do."
+  ],
+  "internalStructure": "One additional call block appended to the existing ADR loop inside `collectBrokenReferences`, delegating `supersededBy` to the `check` helper. The `check` helper is unchanged. `supersededBy` is not required by the ADR schema, so an omitted or empty field never emits an error; the check runs only on a present target. `relatedAdrs` is intentionally not walked at this phase (see responsibilities and AC-16301-2).",
+  "interfaces": [],
+  "notes": "Existing WSD projects that carry stale `supersededBy` pointers will start failing validate on upgrade; that is the intended behaviour (the referee-guarantees docs page promises exactly this refusal). Failures name the ADR file and the field so the fix is a one-line edit or a `define update` write. `relatedAdrs` is untouched by this train and is picked up in the schemas follow-up."
+}

package/rcf/tacs/tac-4110-referee-coverage-mode-selector.json

@@ -0,0 +1,21 @@
+{
+  "createdAt": "2026-09-16T22:28:54Z",
+  "updatedAt": "2026-09-16T22:28:54Z",
+  "tacId": "TAC-4110-referee-coverage-mode-selector",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "coverage --mode selector",
+  "purpose": "Add an explicit `--mode <strict|shallow-any>` option to `rcf audit coverage` in `packages/rcf-lite/src/cli/coverage.js`, resolve the strictness in one place before invoking `computeCoverage`, and keep the legacy `--strict` flag as a no-op alias for the new default. The plain command runs strict-by-default; `--mode shallow-any` is the explicit opt-out; `--mode shallow-any --strict` is a usage refusal (exit 2).",
+  "responsibilities": [
+    "Extend OPTION_SPEC with `mode: { type: 'string' }` and keep `strict: { type: 'boolean' }` for backward compatibility (AC-16401-1, AC-16401-2).",
+    "Validate `--mode` against the enum {strict, shallow-any}; reject unknowns with exit 2 (AC-16401-3).",
+    "Refuse `--mode shallow-any --strict` with exit 2 and a usage message that names both flags (AC-16401-3).",
+    "Resolve strictness once: `strict = flags.mode === 'shallow-any' ? false : true`. Pass the resolved value into `computeCoverage` and the strict-gate exit-4 branch, and into the strict-only verification-integrity matrix (AC-16401-1, AC-16401-2).",
+    "Update the HELP block, the module-level comment, and the human-readable error messages so the flag family and its default are self-documenting."
+  ],
+  "internalStructure": "One-shot resolution in main(). No changes to `computeCoverage` or the query layer. The legacy `--strict` flag routes through the same resolver as absence-of-flag, so existing CI invocations (including the repo's own dogfood step) are byte-forward-compatible.",
+  "interfaces": [],
+  "notes": "The repo's own CI dogfood step in `.github/workflows/ci.yml` is updated to the shipped default (plain `rcf audit coverage`) so the referee-guarantees page and the CI match. Existing blueprints and downstream projects that still spell `--strict` keep working."
+}

package/rcf/tacs/tac-4111-referee-finalise-per-ac-refusals.json

@@ -0,0 +1,21 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "tacId": "TAC-4111-referee-finalise-per-ac-refusals",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "finalise per-AC refusals for UI-BASELINE-UNMET / BROWSER-VERIFICATION-MISSING / SCOPE-MISMATCH",
+  "purpose": "Add three refusal branches to `packages/rcf-lite/src/cli/finalise.js` that read `passLoaded.report.perAcVerdicts[]` after the existing MOCK-ONLY and EVAL branches and refuse promotion (exit 4) when any per-AC verdict matches one of {UI-BASELINE-UNMET, BROWSER-VERIFICATION-MISSING, SCOPE-MISMATCH}. Each refusal leaves the FBS at its current status, prints a stderr message that names the AC(s), the count and the referee-guarantees claim ids, and appends the `summariseReport` block for context. The three ingest helpers land in `packages/rcf-lite/src/finalise/ingest.js` as `findUiBaselineUnmetAcs` / `reportHasUiBaselineUnmet` and `findBrowserVerificationMissingAcs` / `reportHasBrowserVerificationMissing`; `findScopeMismatchAcs` / `reportHasScopeMismatch` already exist and are reused as-is. All three helpers and the finalise-side booleans are re-exported through `src/finalise/index.js`.",
+  "responsibilities": [
+    "Add findUiBaselineUnmetAcs and reportHasUiBaselineUnmet to ingest.js (AC-16501-1, AC-16501-3).",
+    "Add findBrowserVerificationMissingAcs and reportHasBrowserVerificationMissing to ingest.js (AC-16501-2).",
+    "Add three finalise refusal branches after the EVAL refusal branch, in the order UI-BASELINE-UNMET, BROWSER-VERIFICATION-MISSING, SCOPE-MISMATCH; each names the referee-guarantees claim ids in the stderr message so a downstream reader can trace the refusal to the docs promise it enforces (AC-16501-1, AC-16501-2, AC-16501-3).",
+    "Re-export the new helpers through src/finalise/index.js.",
+    "The refusals do NOT expose a --ship-without-* opt-out: the docs page names no sister opt-out for these three (unlike MOCK-ONLY / EVAL). If a project needs to ship anyway, the fix is on the tree (widen the TC, land the browser check, fix the baseline)."
+  ],
+  "internalStructure": "Three straight-line branches modelled on the existing MOCK-ONLY / EVAL refusal shape. Each reads perAcVerdicts, filters by verdict, prints a message, appends summariseReport, and returns 4. Graceful on the pre-0.7.0 report shape (no perAcVerdicts): the helpers return an empty array and the branches fall through to the next check.",
+  "interfaces": [],
+  "notes": "Behavioural addition, not a change: existing verify reports that never emit these verdicts are unaffected. Existing WSD projects whose verify layer already emits UI-BASELINE-UNMET / BROWSER-VERIFICATION-MISSING / SCOPE-MISMATCH will see finalise refuse where it previously silently promoted; that is the referee-guarantees claim holding."
+}

package/rcf/tacs/tac-4112-referee-finalise-verified-invariant.json

@@ -0,0 +1,22 @@
+{
+  "createdAt": "2026-09-16T22:38:04Z",
+  "updatedAt": "2026-09-16T22:38:04Z",
+  "tacId": "TAC-4112-referee-finalise-verified-invariant",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "draft",
+  "name": "finalise verified-invariant: writer refusal + merge-state precondition",
+  "purpose": "Gate the two paths that let the 0.27.0 chain say verified without an actual post-merge runtime check. (a) Refuse a define-update patch that writes FBS.executionStatus=verified unless the caller passes options.allowVerifiedOverride=true; the finalise CLI is the sole caller that sets that seam. The define-update CLI exposes the escape valve as --acknowledge-verified-override, matching the escalation clause on this train (existing WSD projects may still need a manual escape hatch for repair scenarios). (b) In `packages/rcf-lite/src/cli/finalise.js`, spawn a git rev-parse subprocess just before the executionStatus write and refuse promotion (exit 4) when the branch is not one of {main, master}. --allow-pre-merge is the deliberate pre-merge dry-run opt-out; the decision is logged on stdout so the operator sees it. Absent a git checkout the check degrades to a warn line rather than a hard fail.",
+  "responsibilities": [
+    "Add the FBS.executionStatus=verified refusal to updateDocument in `packages/rcf-lite/src/core/store/writer.js`, gated on options.allowVerifiedOverride (AC-16502-1, AC-16502-2).",
+    "Add --acknowledge-verified-override to the define-update CLI, threading options.allowVerifiedOverride through (AC-16502-1).",
+    "Wire the finalise CLI's own updateDocument call to pass options.allowVerifiedOverride:true (backward compatibility for the finalise happy path).",
+    "Add resolveGitBranch helper in finalise.js as a testable seam (deps.spawn) around child_process.spawn (AC-16502-3).",
+    "Add the branch-name refusal branch just before the executionStatus write; support --allow-pre-merge and degrade to a warn line when the branch cannot be resolved (AC-16502-3).",
+    "Update HELP for both CLIs so the flags and their intent are self-documenting."
+  ],
+  "internalStructure": "Writer refusal fires at the very top of the patch-apply path in updateDocument, before deep-merge and dot-path assignments run, so no partial state ever lands. The finalise-side branch check uses child_process.spawn (imported at module top) with the deps.spawn seam consumers can override in tests; the shape mirrors spawnVerify's own seam. The default-branch set is small and conventional ({main, master}) rather than reading the git remote's symbolic ref (which fails offline and adds a round-trip on every finalise).",
+  "interfaces": [],
+  "notes": "Behavioural addition, not a change on the finalise happy path (finalise passes the override flag through). Downstream projects that ran `rcf define update <fbs> --set executionStatus=verified` without --acknowledge-verified-override will see the write refused; the fix is either finalise or the new opt-out flag. Downstream projects whose finalise ran off a non-default branch will see the pre-merge refusal; --allow-pre-merge is the documented dry-run seam."
+}