rcf-lite 0.27.0 → 0.28.0

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

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.27.0"
+latest: "0.28.0"
 releases:
+  - version: "0.28.0"
+    date: "2026-09-17"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.0 lands two referee-facing trains together. The rcf feedback verb family lets an agent record what a blueprint or rcf-lite did that contradicts its own docs, fails, or forces a workaround, and after one operator yes at a natural pause files each finding as a GitHub issue under the operator's own gh login, or writes a pastable outbox bundle when gh is not available."
+      - "The referee-guarantees train tightens the three sentences the docs page makes about rcf define validate, rcf audit coverage and rcf build finalise: validate now walks ADR supersededBy, coverage is strict by default with --mode shallow-any as the deliberate opt-out, and finalise refuses on the three per-AC verdicts, gates the manual verified override behind --acknowledge-verified-override, and adds a merge-state precondition with --allow-pre-merge as the deliberate pre-merge dry-run opt-out."
+      - "rcf init merges three hook entries into .claude/settings.json and .codex/hooks.json so the feedback ask fires once per session at idle; RULE 17 lands in the managed instructions block as the belt-and-braces path. Coverage-strict-by-default is the single migration surface: run rcf audit coverage --mode shallow-any when the intent is a printed gap report rather than a gate."
+    minAgentAction: rerun-init
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.27.0"
     date: "2026-09-11"
     breaking: false

package/src/blueprint/library-loader.js

@@ -59,6 +59,18 @@ const LIBRARY_VERSION_KNOWN = 1;
  * @property {string} [contact]
  */
 
+/**
+ * @typedef {object} LibraryIssuesField
+ * @property {string} repo          OWNER/REPO on github.com; HOST/OWNER/REPO permitted for GHES
+ * @property {'public' | 'private'} visibility  advisory; the tool re-checks live on submit
+ *
+ * The library owner names where feedback reports on this library are
+ * filed (design 3.3, ADR-4104). Absence is valid; the consuming
+ * project's `rcf doctor feedback-destinations` warns until the field
+ * lands. Snapshotted onto the registry entry as `issuesRepo` and
+ * `issuesVisibility` on `library add`.
+ */
+
 /**
  * @typedef {object} LoadedLibrary
  * @property {number} libraryVersion
@@ -69,6 +81,7 @@ const LIBRARY_VERSION_KNOWN = 1;
  * @property {LibraryBands} bands
  * @property {LibraryBlueprintEntry[]} blueprints
  * @property {string} [notes]
+ * @property {LibraryIssuesField} [issues]
  * @property {string} root              absolute path to the library root
  */
 
@@ -128,6 +141,7 @@ export async function loadLibrary(libraryRoot, opts = {}) {
     bands: normaliseBands(doc.bands),
     blueprints: doc.blueprints.map((b) => ({ slug: b.slug, path: b.path })),
     ...(typeof doc.notes === 'string' ? { notes: doc.notes } : {}),
+    ...(doc.issues ? { issues: normaliseIssues(doc.issues) } : {}),
     root,
   };
 
@@ -203,9 +217,43 @@ function validateManifestShape(doc, metaPath) {
   if (doc.notes !== undefined && typeof doc.notes !== 'string') {
     return rcfError({ kind: 'validation', message: 'library.json: notes must be a string when present', filePath: metaPath });
   }
+  if (doc.issues !== undefined) {
+    const err = validateIssuesField(doc.issues, metaPath);
+    if (err) return err;
+  }
   return null;
 }
 
+/**
+ * Validate the optional `issues` object (design 3.3, AC-15801-1). Refuses
+ * a present-but-shapeless value so a typo does not silently disable
+ * feedback routing. `repo` accepts `OWNER/REPO` on github.com and a
+ * host-qualified `HOST/OWNER/REPO` for GHES; `visibility` is one of
+ * `public` or `private`.
+ */
+function validateIssuesField(issues, metaPath) {
+  if (typeof issues !== 'object' || issues === null || Array.isArray(issues)) {
+    return rcfError({ kind: 'validation', message: 'library.json: issues must be an object with { repo, visibility } when present', filePath: metaPath });
+  }
+  if (typeof issues.repo !== 'string' || issues.repo.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: issues.repo is required (OWNER/REPO or HOST/OWNER/REPO)', filePath: metaPath });
+  }
+  if (!/^([A-Za-z0-9.-]+\/)?[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(issues.repo)) {
+    return rcfError({ kind: 'validation', message: `library.json: issues.repo '${issues.repo}' must be OWNER/REPO on github.com or HOST/OWNER/REPO for GHES`, filePath: metaPath });
+  }
+  if (issues.visibility !== undefined && issues.visibility !== 'public' && issues.visibility !== 'private') {
+    return rcfError({ kind: 'validation', message: `library.json: issues.visibility '${issues.visibility}' must be 'public' or 'private' when present`, filePath: metaPath });
+  }
+  return null;
+}
+
+function normaliseIssues(issues) {
+  return {
+    repo: issues.repo,
+    visibility: issues.visibility === 'private' ? 'private' : 'public',
+  };
+}
+
 function validateBands(bands, metaPath) {
   if (typeof bands !== 'object' || bands === null) {
     return rcfError({ kind: 'validation', message: 'library.json: bands object is required', filePath: metaPath });

package/src/blueprint/library-registry.js

@@ -47,6 +47,8 @@ const CORE_BAND_RESERVATIONS_PATH = join(here, '..', '..', 'data', 'core-band-re
  * @property {'operator'} reviewedBy
  * @property {{ tier: 'local' | 'git' | 'tarball', shaVerifiedAt?: string, tarballSha256?: string }} provenance
  * @property {string} cachePath
+ * @property {string} [issuesRepo]         OWNER/REPO from the library's issues field (design 3.3, ADR-4104)
+ * @property {'public' | 'private'} [issuesVisibility]  library-declared visibility, advisory
  */
 
 /**
@@ -336,6 +338,17 @@ function validateRegistryShape(doc, path) {
     if (entry.sourceKind === 'local' && entry.resolvedSha !== undefined) {
       return rcfError({ kind: 'validation', message: `library registry: libraries[${i}] sourceKind=local must not carry a resolvedSha`, filePath: path });
     }
+    if (entry.issuesRepo !== undefined) {
+      if (typeof entry.issuesRepo !== 'string' || entry.issuesRepo.length === 0) {
+        return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesRepo must be a non-empty string when present`, filePath: path });
+      }
+      if (!/^([A-Za-z0-9.-]+\/)?[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(entry.issuesRepo)) {
+        return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesRepo '${entry.issuesRepo}' must be OWNER/REPO on github.com or HOST/OWNER/REPO for GHES`, filePath: path });
+      }
+    }
+    if (entry.issuesVisibility !== undefined && entry.issuesVisibility !== 'public' && entry.issuesVisibility !== 'private') {
+      return rcfError({ kind: 'validation', message: `library registry: libraries[${i}].issuesVisibility '${entry.issuesVisibility}' must be 'public' or 'private' when present`, filePath: path });
+    }
   }
   return null;
 }

package/src/browser-verify/pack-runner.js

@@ -139,20 +139,15 @@ export async function runProbePacksForFbs({
           checkAppliesDetail = `appliesTo threw: ${err.message}`;
         }
         if (!checkApplicable) {
-          // Spec section 5.5 says the residual cure records
-          // applicable: false at the check level. rcf-schemas 0.6.1
-          // (browserVerificationProbePackCheck) closes the schema and
-          // still requires a verdict enum, so the manifest write path
-          // refuses a check that carries `applicable: false` alone.
-          // Until the schema minor promotes an `applicable` field at
-          // the check level (follow-up rcf-schemas bump), emit
-          // `verdict: 'skipped'` with a detail naming the applicability
-          // gate. Semantically the aggregate verdict still treats this
-          // as neither pass nor fail (skipped does not raise `highest`).
+          // Spec section 5.5 residual cure: record `applicable: false`
+          // at the check level so the aggregate verdict treats the
+          // check as neither pass nor fail. rcf-schemas 0.6.3 added
+          // the optional `applicable` boolean on
+          // browserVerificationProbePackCheck, and its if/then guard
+          // omits `verdict`/`severity` when `applicable: false`.
           checkRecords.push({
             id: check.id,
-            verdict: 'skipped',
-            severity: check.severity,
+            applicable: false,
             detail: checkAppliesDetail ?? 'check appliesTo returned false (required capability not applied)',
           });
           continue;

package/src/build/mark.js

@@ -86,7 +86,7 @@ export function planMark(tree, { fbsId, status }) {
       refused: true,
       message: `build: refusing --mark verified on ${fbsId}; 'verified' is written only by the `
         + `independent verify gate, not by --mark. Promote it with: rcf build finalise ${fbsId} --url <deploy-url>. `
-        + `For a deliberate manual override (no verify run) use: rcf define update ${fbsId} --set executionStatus=verified`,
+        + `For a deliberate manual override (no verify run) use: rcf define update ${fbsId} --set executionStatus=verified --acknowledge-verified-override`,
     };
   }
   const fromIndex = LIFECYCLE.indexOf(from);