rcf-lite 0.28.1 → 0.28.4

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

@@ -0,0 +1,38 @@
+{
+  "usId": "US-17301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-173",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf define ledger reads and writes the four sidecars under rcf/define/",
+  "description": "User story under REQ-173. The operator-facing CLI for the four sidecar ledgers lands with add / resolve / list on every ledger name.",
+  "asA": "an operator staging or reviewing a DEFINE change",
+  "iWant": "rcf define ledger to author brief statements, decisions, concern dispositions and probe findings under rcf/define/ with numbered ids stable for the life of the project, and to leave every ledger invisible to the walker",
+  "soThat": "the freeze record's high-water mark, the D7 decisions list, D5 concern coverage and D6 probe findings all have a written record and every later DEFINE slice reads the same seam without discovering a second source of truth",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17301-1",
+      "description": "rcf define ledger brief add --kind <k> --text <t> appends a numbered statement to rcf/define/brief-ledger.json, mints the next id (highest current + 1), stamps status open and addedAt (ISO-8601), refuses an unknown kind with a usage-class error, and refuses --text combined with --from with a usage-class error.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-2",
+      "description": "rcf define ledger decisions list prints the numbered #241 format: one decision per item (id. question), options rendered as 'letter) text', the default letter labelled 'default:', and what it blocks labelled 'blocks:'. rcf define ledger <name> list --json emits the machine-readable envelope { ledger, <arrayKey>: [...] }.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-3",
+      "description": "rcf define ledger brief add --from <file> reads the file, splits it into one statement per non-empty line (stripping leading '- ', '* ' or '<n>. ' bullets), mints sequential ids for every statement, refuses if the file produced zero non-empty lines, and stamps the file path as source unless --source overrides it. The intake-scan-against-frozen-statements hook is a named seam in the writer, not called in this slice.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-4",
+      "description": "walkTree run over a project that carries rcf/define/freeze.json, all four ledger files, and a bug-bait file named req-999.json under rcf/define/ never surfaces any rcf/define/ file as a tree.byId document and reports no walker error naming a rcf/define/ path. The sidecar directory is invisible to every consumer of walkTree.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4121-define-ledgers"],
+  "tags": [],
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,58 @@
+{
+  "usId": "US-17401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-174",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Stage gates land as pure check functions with per-stage state",
+  "description": "User story under REQ-174. Eight stage-gate check functions land in src/query/gates.js with a stable per-stage return shape that computeReadiness and every later slice can consume unchanged.",
+  "asA": "a downstream consumer of DEFINE gates (readiness, freeze, viewer)",
+  "iWant": "gates.js to expose one pure check function per stage D1..D8, each returning a { stage, gate, state, checks[] } object with checks in the { name, ok, over: 'delta'|'tree', pass, total, failing: [{ id, why }] } shape",
+  "soThat": "computeReadiness composes the eight checks, the freeze verb refuses on any failing state, and the viewer's Readiness tab prints the same rows the CLI does with no schema translation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17401-1",
+      "description": "src/query/gates.js exports one check function per stage D1..D8 (checkD1Brief, checkD2Skeleton, checkD3Shapes, checkD4Stories, checkD5Crosscut, checkD6Consistency, checkD7Decisions, checkD8Freeze), each taking (tree, { ledgers, profile, scope, freeze, delta, validateErrors, probeOpenCount, coverageTree }) and returning { stage, gate, state, checks[] }; every entry in checks is { name, ok, over: 'delta'|'tree', pass, total, failing: [{ id, why }] } (failing empty on ok).",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-2",
+      "description": "Blocking stages in 0.29.0 (D1, D2, D4, D7, D8) report state 'passed' when every check ok is true, 'failing' when any check ok is false; warn-with-ack stages (D3, D5, D6) report 'passed' when every check ok is true, 'failing' when any check ok is false and the freeze record does NOT acknowledge that gate at the current tree hash, and 'acknowledged' when the freeze.gates[<gate>] entry names state 'acknowledged' and at.hash === currentTreeHash and any check ok is false.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-3",
+      "description": "notApplicable is decided per stage per proposal section 3.2: D2 notApplicable when no statement of a resolving kind (capability, constraint, entity, actor, externalSystem, surface) is in the delta AND no REQ, PRD or TAD is in scope; D3 notApplicable when no TAC and no shaped REQ (httpApi/persistence/auth) is in scope; D5 notApplicable when no REQ is in scope; D7 notApplicable when no open decisions exist AND the profile sets skipReviewFor: singleDocument AND the delta holds exactly one document; D4 and D6 use their own rules; D1 and D8 never notApplicable.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-4",
+      "description": "checkD4Stories enforces the D4 floors: every REQ in scope has a US (fail: 'no owning user story'), every US in scope has a testable AC ('missing testable AC'), a failure AC (parsed by the bracketed [failure] prefix on AC description) or a reasoned opt-out per class (manifest.baselineAcOptOuts[] entry with baselineKey 'defineD4:failure' and matching scope), a must-not AC (parsed by [must-not] prefix) or a reasoned opt-out per class (baselineKey 'defineD4:mustNot'), tacIds non-empty and every named tac resolving to a real TAC, and no AC description contains the scaffold TODO placeholder.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-5",
+      "description": "checkD3Shapes runs only cheap data-backed checks in 0.29.0: every TAC in scope has at least one interface (fail: 'no interfaces authored'), and every interface's kind is in the closed vocabulary { recordShape, httpRoute, event, cliCommand, uiRoute, port, fileFormat, fixture, other } (fail: 'unknown interface kind <k>'). The template parser, entity-name join, ownerRef and path resolution are named seams (not called this slice) and D3 stays warn-with-ack.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-6",
+      "description": "checkD5Crosscut runs only cheap data-backed checks in 0.29.0: TAD.securityArchitecture non-empty when the tree carries any REQ whose shapeClassification.shapes includes 'auth' or 'httpApi'; TAD.operationalConcerns non-empty when any AC description carries the '[deployed]' marker (a cheap presence signal proposal section 3.2 D5 lists as 'deployed-scope AC'); concern-ledger entries in scope disposed as 'applied' or 'waived' (no dangling 'open' concerns on REQs in scope). The full catalogue and per-pair enumeration are named seams for 0.30.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-7",
+      "description": "checkD6Consistency runs only cheap data-backed checks in 0.29.0: validate is clean tree-wide (validateErrors is empty; the caller passes the walker + validator's error list), and probe-ledger holds zero 'open' probe entries. Contradiction-lite, unsatisfiable-lite, duplicates and orphan-interface scans, plus the probe runner, are named seams for 0.30.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-8",
+      "description": "checkD8Freeze enforces the tree-wide gate: every prior stage state (D1..D7 as computeReadiness composes them) is passed or acknowledged at the current hash; every AC id in the tree is bound by exactly one FBS (walker's fbsByAcId map has length 1); the queue head (computeQueue.nextActionable) is not null; validateErrors is empty. The stage is never notApplicable.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4122-define-gates"],
+  "tags": [],
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14:30:00Z"
+}

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

@@ -0,0 +1,48 @@
+{
+  "usId": "US-17501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-175",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "computeReadiness and rcf define readiness render the same object",
+  "description": "User story under REQ-175. computeReadiness lands as a pure module and rcf define readiness as its CLI twin. The viewer's Readiness tab (slice 5) will render the same object with no schema translation.",
+  "asA": "an operator asking 'can I build, and if not what is in the way'",
+  "iWant": "one pure compute that composes delta, fan-out, gates, coverage and decisions into a single object, and one CLI that prints it in a compact form or emits it as JSON",
+  "soThat": "the tree line, next action, stage chips, delta list and failing items are the same wherever they are shown, and slice 3's rcf define freeze refuses on the same freezeable flag the CLI reports",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17501-1",
+      "description": "computeReadiness(tree, { freeze, ledgers, profile, testPointers }) returns the exact section 2.4 shape: tree { frozen, frozenAt, treeHash, currentTreeHash, buildAt, fbsTotal }, delta { changed, added, removed, briefSince, impacted, impactedFbs }, stages [{ stage, gate, state, checks }], nextAction { stage, check, ids, command } or null, coverage { tree, delta }, decisions [...open in #241 format], freezeable boolean. freezeable is true when every stage state is 'passed', 'acknowledged' or 'notApplicable'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-2",
+      "description": "Fan-out is computed by calling computeImpact once per id in the union of changed and added; impacted is the union of every impact node id excluding the pivots; impactedFbs is the subset whose kind is 'fbs' and actionNeeded is 're-execute'. Gates run over scope = changed union added union impacted (with duplicates removed).",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-3",
+      "description": "Coverage is tree-wide plus per REQ ancestor of the delta: coverage.tree is computeCoverage(tree, { testPointers, strict: true }) once over the whole tree; coverage.delta is an array with one CoverageResult per unique REQ id reachable by walking back from every delta id (changed union added) through parentByChild until the reqId is found, using scopeId per invocation. testPointers is the map the CLI produced with resolveTestPointers.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-4",
+      "description": "nextAction picks the first stage in D1..D8 order whose state is 'failing', then the first failing check in that stage's checks[] (or the check with the largest failing.length when tie); it names the stage id, the check name, the failing ids (deduped), and a command string like 'rcf define readiness --check <stage-short-name> after editing'. nextAction is null when every stage is passed / acknowledged / notApplicable.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-5",
+      "description": "rcf define readiness prints a text summary: the tree line ('Frozen at <shortHash> on <frozenAt>. N documents changed since, M impacted. Build at <fbsId> of <total>; K FBS impacted.' or 'Unfrozen. N documents; the whole tree is the delta.'), the next action line, a chip line 'D1:passed D2:failing D3:acknowledged D4:notApplicable ...', and the failing-items list per stage. --json emits the full computeReadiness object under `${JSON.stringify(result, null, 2)}\\n`. --check <stage> (D1..D8 or short name brief|skeleton|shapes|stories|crosscut|consistency|decisions|freeze) prints only that stage and exits 0 when its state is 'passed' or 'acknowledged' or 'notApplicable', exit 4 on 'failing' for blocking stages (D1, D2, D4, D7, D8), exit 0 with a visible '[warn]' line on 'failing' for warn-with-ack stages (D3, D5, D6). The verb wraps its producer with runWithAdmissibilityGate and, on admissibility refusal, prints the refusal on stderr and exits 4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-6",
+      "description": "loadAllLedgers({ projectRoot }) returns a LedgerBundle that OMITS a ledger key when the sidecar file does not exist (ENOENT), so computeDelta records no docHash for absent ledgers; the docstring on computeDelta (LedgerBundle typedef) and the loader implementation agree. A project that has authored a brief ledger and no others sees exactly one 'ledger:brief' entry in the delta docHashes; a project that has authored no ledgers sees zero 'ledger:*' entries.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4123-define-readiness"],
+  "tags": [],
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14:30:00Z"
+}

package/releases/releases.yaml

@@ -40,8 +40,38 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.28.1"
+latest: "0.28.4"
 releases:
+  - version: "0.28.4"
+    date: "2026-09-30"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.4 fixes user story minting on legacy trees that carry flat sequential ids. On a tree migrated in from a v1 project, minting a new user story under a requirement now extends the flat sequence (US-163 to US-164) instead of jumping to an encoded slot such as US-5301; a tree that mixes both id shapes is refused with a message naming one example of each so the operator can normalise it first. Acceptance criteria minting is unchanged."
+      - "The 0.28.3 fixes ship in this release, because 0.28.3 was written up on 22 September but never tagged or published. Those are the feedback redactor no longer folding git protocol sentinels as emails, a visible warning when identity folding is disabled, and the live-view server snapshotting its static assets at startup."
+      - "The DEFINE workflow foundations arrive ahead of the 0.29.0 train: delta detection, freeze records, four sidecar ledgers with rcf define ledger, stage gates D1 to D8, and rcf define readiness, plus the Product Map tab on the review surface."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.28.3"
+    date: "2026-09-22"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.3 is a small batched fix release for the residuals Dex's 0.28.2 round-trip surfaced and one HQ-side viewer bug caught the same day. The feedback redactor no longer folds the git protocol sentinel git@<host> inside git+ssh, ssh or git URLs as an email, so an evidence pointer copied verbatim from a git remote or clone URL survives as evidence. Bare git remotes and single-letter trailing labels like a.b.c are also protected as URI userinfo and filename fragments; real emails in surrounding prose still fold."
+      - "The redactor emits a visible stderr warning when identity folding is disabled, so an operator whose rcf/.identity/profile.md is missing, empty, a placeholder, or contains only reserved nouns is no longer left thinking their identity is in force when it silently is not. Feedback status --json now exposes the destination source field the preview surface already prints, and --evidence pointers now render with the label matching their shape (command / path:line / id) rather than always (command)."
+      - "The live-view server snapshots its shipped static assets (style.css, mermaid.min.js, live-client.js) at startup instead of reading them from disk per request, so a checkout branch switch during the server's lifetime can no longer silently change the served CSS."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.28.2"
+    date: "2026-09-22"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.2 is a batched fix release for the seven defects Barry's WSD-lens dogfood on 0.28.1 surfaced, plus three unreported dry-run gaps folded into the same release. Feedback submit no longer folds unrelated findings into one issue and no longer replaces the report with a +1 stub. Submit re-reads every candidate issue body and folds only on a verified fingerprint match, refusing to fold across differing anchor or target; every fold comment now carries the full report. The redactor also stops rewriting .md filenames as hostnames: a candidate whose trailing dot-label is on a bundled extensions shortlist in redact-allowlist.json is left intact."
+      - "The five discover verbs share one schema pass across --dry-run and the write path (intake, preflight, review, ui-baseline init, browser-verify). A preview now reports the same validation error the real run would refuse on, so intake --dry-run --input catches a fidelity enum miss and preflight --dry-run --input catches a kebab-case service id. intake and preflight --help advertise their allowed values."
+      - "Three more build defects ride along: discover intake dedupes findings before writing the record so a shared branch that fires on two artefacts lands as one finding, req-baseline sweep --yes now allocates distinct AC ids across a batch on one user story, and the TAD review surface renders dataStores, coreEntities and externalSystems as tables instead of raw JSON.stringify blobs."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.28.1"
     date: "2026-09-17"
     breaking: false

package/src/browser-verify/manifest-writer.js

@@ -5,7 +5,7 @@ import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { rcfError } from '#core/errors';
-import { validateDocument } from '#core/store';
+import { buildNextManifest, validateDocument } from '#core/store';
 
 /**
  * Compute the next `bv-<fbsId>-<n>` id: monotonic per FBS.
@@ -181,10 +181,14 @@ function stripSeverity(check) {
  * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
  */
 export async function writeBrowserVerificationRecord({ projectRoot, tree, record, options = {} }) {
-  const manifest = tree.manifest ?? {};
-  const nextManifest = { ...manifest };
-  const existing = Array.isArray(nextManifest.browserVerification) ? nextManifest.browserVerification : [];
-  nextManifest.browserVerification = [...existing, record];
+  // 0.28.2 (Codex review follow-up on the shared helper): compose via
+  // the shared `buildNextManifest` helper so write and dry-run
+  // produce the same shape and the same schema pass runs on both.
+  const nextManifest = buildNextManifest({
+    manifest: tree.manifest ?? {},
+    record,
+    verb: 'browserVerify',
+  });
 
   const relPath = 'rcf/manifest.json';
   const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });

package/src/cli/browser-verify.js

@@ -20,7 +20,7 @@ import { parseArgs } from 'node:util';
 import process from 'node:process';
 import { isAbsolute, resolve } from 'node:path';
 
-import { walkTree } from '#core/store';
+import { walkTree, validateComposedRecord } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
@@ -270,6 +270,14 @@ export async function main(argv, deps = {}) {
   if (flags.json) stdout.write(`${JSON.stringify(record, null, 2)}\n`);
 
   if (flags['dry-run']) {
+    // 0.28.2 (folded into #230): dry-run runs the same schema pass
+    // the writer runs so a preview reports the same validation error
+    // the write path would refuse.
+    const dryValidation = validateComposedRecord({ tree, record, verb: 'browserVerify' });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     if (!flags.quiet) {
       renderSummary({ stdout, record });
     }