rcf-lite 0.28.2 → 0.29.0

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

@@ -0,0 +1,64 @@
+{
+  "usId": "US-205",
+  "prdId": "PRD-001",
+  "reqId": "REQ-002",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "An engineer jumps to any document or AC by id",
+  "description": "A SearchButton to the right of the tabstrip and the Cmd/Ctrl+F keyboard binding open a LookupModal with type-ahead over a server-built `./index.json` carrying every document id and every AC. Id matches rank first (exact, prefix, contains), then every query word must match title or snippet, title above snippet; a single character searches ids only; 20 results. A pick sets `#tab=<tab>&entity=<id>`; the Router activates the tab, opens every ancestor DocRow and flashes the target. `embed` and `theme` survive every hash write. See viewer UI refresh design doc section 6.",
+  "asA": "an engineer looking at any tab of the review surface",
+  "iWant": "a modal that lets me jump to any document or AC by typing part of its id or title",
+  "soThat": "I can navigate the tree by id without hunting through the tabs",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-205-1",
+      "description": "[happy] Given the review surface, when the SearchButton is pressed or Cmd/Ctrl+F is typed from any tab, then the LookupModal opens; typing an exact id (`REQ-002`) or a prefix (`REQ-00`) ranks that id first and the first result row is pre-highlighted.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-2",
+      "description": "[happy] Given the LookupModal, when a word query matches a document's title and another document's snippet, then the title match ranks above the snippet match.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-3",
+      "description": "[happy] Given the LookupModal, when a query of exactly one character is typed, then only ids whose identifier contains that character rank, and the title / snippet word-match pass is skipped.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-4",
+      "description": "[happy] Given a pre-highlighted result for `US-304`, when Enter is pressed, then the hash becomes `#tab=requirements&entity=US-304`, the Router activates the Requirements tab, opens the REQ-003 ancestor DocRow and the US-304 row, scrolls the target into view and flashes it.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-5",
+      "description": "[happy] Given a mount URL `?tab=requirements&entity=US-304`, when the shell first paints, then the Router lands on the same position: Requirements tab active, REQ-003 and US-304 DocRows open, US-304 scrolled into view.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-6",
+      "description": "[happy] Given `?embed=1&theme=dark` on the viewer URL, when a result is picked from the LookupModal, then the resulting URL still carries `embed=1` and `theme=dark` in the query string and the hash is `#tab=<tab>&entity=<id>`.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-7",
+      "description": "[failure] Given a `./index.json` fetch that returns a non-2xx status or a malformed body, when the LookupModal is opened, then an empty state renders with a reload affordance that re-fetches the index, and no result rows show.",
+      "testable": true
+    },
+    {
+      "id": "AC-205-8",
+      "description": "[must-not] Given the LookupModal, when the user types a query, picks a result or closes the modal, then no `postMessage` is sent to the parent window, no outbound network request beyond the `./index.json` fetch is made, and no search term is written to `localStorage` / `sessionStorage` / cookies.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4132-id-lookup"
+  ],
+  "tags": [
+    "view",
+    "lookup",
+    "navigation"
+  ],
+  "createdAt": "2026-10-02T19:00:00Z",
+  "updatedAt": "2026-10-02T19:00:00Z"
+}

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

@@ -0,0 +1,54 @@
+{
+  "usId": "US-206",
+  "prdId": "PRD-001",
+  "reqId": "REQ-002",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "wespa's embedding contract is proved by a CI host fixture",
+  "description": "A same-origin test-host fixture served by the viewer's dev server (route `/test-host.html` behind a `--test-host` flag or an env guard; off by default so wespa's proxy allow-list is unaffected) mimics the wespa shell: a 56px header, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying an `<iframe src=\"./?embed=1&theme=light\">`. The host posts `{ type: \"rcf-view-theme\", theme: \"light\"|\"dark\" }` on a toggle control; it stores no theme itself so a passing run proves the iframe reads the message. The viewer sends no outbound postMessage. Three lints run in the test suite: (1) framing lint (`GET /` returns no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin, and the fixture loads the iframe without a browser error); (2) target lint (no `target=\"_top\"` string in the server-rendered HTML); (3) localStorage namespace lint (every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site in `src/view/**` uses a key starting with `rcf-view:v1:`). See viewer UI refresh design doc section 9 and Dex's wespa requirements of 2026-10-02.",
+  "asA": "Dex integrating the rcf-lite viewer behind wespa's reverse proxy",
+  "iWant": "a CI host fixture that proves the viewer honours the embedding contract and three lints that keep framing, target='_top' and localStorage namespace in place over time",
+  "soThat": "regressions in the embedding contract are caught in the viewer's own suite before they reach wespa",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-206-1",
+      "description": "[happy] Given the test-host fixture at `/test-host.html`, when the page loads with the viewer served from the same origin, then the iframe `src` is `./?embed=1&theme=light`, the title block and footer of the iframed viewer are hidden (`<html data-embed=\"1\">`), the tab nav is visible and the host's 56px header plus the resizable sidebar render around it.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-2",
+      "description": "[happy] Given the test-host fixture with the iframe loaded, when the host's theme toggle posts `{ type: \"rcf-view-theme\", theme: \"dark\" }` to the iframe's `contentWindow`, then the iframe's `<html data-theme>` flips to `dark` without a reload and the content repaints in the dark token set.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-3",
+      "description": "[happy] Given the test-host fixture with the iframe loaded at `./?embed=1&theme=dark`, when a hash-only navigation inside the iframe writes `#tab=requirements&entity=REQ-002`, then the iframe's query still carries `embed=1` and `theme=dark` and the viewer's inner `<html data-embed=\"1\" data-theme=\"dark\">` is preserved.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-4",
+      "description": "[failure] Given the viewer page listening for `rcf-view-theme` postMessages, when a message with `event.origin` different from `window.location.origin` is delivered, then the message is ignored and `<html data-theme>` is not changed.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-5",
+      "description": "[must-not] Given the viewer's `GET /` response, when the three lints run in the test suite, then (a) no `X-Frame-Options` header is set and no CSP `frame-ancestors` directive forbids same-origin framing, (b) `target=\"_top\"` appears zero times in the rendered HTML across every tab, (c) every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site under `src/view/**` uses a key starting with `rcf-view:v1:`.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-6",
+      "description": "[must-not] Given the test-host fixture and the viewer page, when either is loaded, then neither posts any outbound message beyond the host's `rcf-view-theme`; the viewer sends no `postMessage` of any shape, and the test-host adds no new postMessage shape.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4134-wespa-host-fixture"
+  ],
+  "tags": [
+    "view",
+    "embedding",
+    "lint"
+  ],
+  "createdAt": "2026-10-02T20:00:00Z",
+  "updatedAt": "2026-10-02T20:00:00Z"
+}

package/releases/releases.yaml

@@ -40,8 +40,38 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.28.2"
+latest: "0.29.0"
 releases:
+  - version: "0.29.0"
+    date: "2026-10-03"
+    breaking: true
+    headlines:
+      - "rcf-lite 0.29.0 lands the viewer UI refresh train in one release: a rebuilt shell with the Stravica brand tokens, light and dark theme and an embed contract; shared components across Requirements, Architecture, Build and Readiness; a Build DAG sub-tab with click-to-highlight closure, dependency inspector and an unconnected lane; fast ID lookup over a new ./index.json served from the viewer root (Cmd/Ctrl+F from any tab); the Readiness tab Product Owner redesign; and a same-origin test-host fixture that pins the embedding contract with three in-suite guards. For wespa embedders, the reverse-proxy allow-list for /rcf-viewer/* MUST add /page-init.js and /index.json before the version pin bump; /test-host.html and /test-host.js stay 404 by default so the allow-list is unchanged by the embedding-proof fixture."
+      - "The DEFINE readiness persona split arrives too: every gate check carries a persona (product owner or engineer), two readiness levels (intent-complete, ready-to-build), the Readiness tab moves to tab one, and rcf define readiness gains --level and --persona flags with a persona-grouped text report."
+      - "The first three DEFINE step 3 PRs ship: document intake into the brief ledger via a statement file parser and the mechanical intake scans; a new rcf define ledger <name> update <id> subverb with a closed resolvedBy pointer grammar (REQ-nnn, TAD.entity:<name>, PRD.user:<name>, TAD.system:<name>, TAC-nnnn, omitted:<reason>) and the D2 skeleton:resolvedBy title-hit fallback dropped; a rcf define questions verb with three new MCP tools and two argument-free prompts for the harness-driven loop; and the [draft] shapes gate across TAC purpose, interface and core-entity homes with a DISCOVERY prototypes doctrine."
+    minAgentAction: rerun-init
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - 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

package/src/cli/feedback.js

@@ -54,7 +54,7 @@ import {
   emitSessionStart,
   shouldAsk,
 } from '../feedback/hook.js';
-import { redact, allowedHosts, findResidualSecrets } from '../feedback/redact.js';
+import { redact, allowedHosts, findResidualSecrets, RESERVED_IDENTITY_TOKENS } from '../feedback/redact.js';
 import { fingerprint } from '../feedback/fingerprint.js';
 import { renderIssue, renderComment, renderBundle } from '../feedback/render.js';
 import { resolve as resolveDestination, listUnresolvedLibraries, findBlueprintRecord } from '../feedback/destination.js';
@@ -477,17 +477,58 @@ async function handleAdd(argv, ctx) {
 }
 
 /**
- * Classify an evidence pointer into `{ kind, value }`. A colon-separated
- * `path:line` pattern is 'file'; a bare identifier that looks like an
- * upper-cased id is 'id'; anything else is 'command'. The classification
- * is best-effort and does not gate the write.
+ * Classify an evidence pointer into `{ kind, value }`. The help text
+ * promises three shapes: command / path:line / id. The classifier
+ * distinguishes them by cheap shape rules:
+ *
+ * - `id`: a canonical uppercase-prefix RCF artefact id (`AC-15501-1`,
+ *   `REQ-155`, `FBS-181`, `US-15701`).
+ * - `file`: `path:line` (a non-space token ending in `:<digits>`) OR
+ *   a bare filesystem path shape - a slash-bearing, non-whitespace
+ *   token that ends in a known file extension. This is the shape a
+ *   `--evidence rcf/.blueprint-libraries/wsd/1.0.0/library.json`
+ *   argument carries (issue #245).
+ * - `command`: anything else. This is the fallback shape for a bare
+ *   verb invocation like `rcf feedback preview` or `pnpm --filter
+ *   rcf-lite test`.
+ *
+ * Classification is best-effort and never gates the write; the value
+ * itself is always preserved verbatim. The rendered preview label
+ * uses this kind so the operator sees which shape the pointer carries
+ * without having to re-run it.
  *
  * @param {string} value
  * @returns {{ kind: 'file' | 'id' | 'command', value: string }}
  */
+// 0.28.3 (issue #245): extension shortlist used by `classifyEvidence`
+// to recognise bare file-path evidence. Kept in lockstep with the
+// redactor's default extension allowlist so operators see the same
+// treatment on both sides. Duplicated deliberately (not imported) to
+// keep the CLI light on cross-module reads for a per-call classifier.
+const EVIDENCE_FILE_EXTENSIONS = new Set([
+  'md', 'mdx', 'json', 'yml', 'yaml', 'txt',
+  'js', 'mjs', 'cjs', 'ts', 'tsx',
+  'html', 'css', 'png', 'svg', 'sh', 'csv', 'log', 'lock',
+]);
+
 export function classifyEvidence(value) {
+  if (typeof value !== 'string' || value.length === 0) return { kind: 'command', value };
+  // Canonical RCF id shape: uppercase prefix, then digits (e.g. AC-15501-1).
   if (/^[A-Z]+-\d[\w-]*$/.test(value)) return { kind: 'id', value };
-  if (/^[^\s].*:\d+$/.test(value)) return { kind: 'file', value };
+  // path:line - a non-whitespace token ending in ":<digits>".
+  if (/^[^\s]+:\d+$/.test(value)) return { kind: 'file', value };
+  // Bare filesystem path or filename: no whitespace, ends in a known
+  // extension (issue #245). Whitespace anywhere disqualifies the
+  // candidate; that is almost certainly a shell command. A bare
+  // filename without a slash still counts because a --evidence
+  // pointer to README.md or CHANGELOG.md is common.
+  if (!/\s/.test(value)) {
+    const lastDot = value.lastIndexOf('.');
+    if (lastDot > 0 && lastDot < value.length - 1) {
+      const ext = value.slice(lastDot + 1).toLowerCase();
+      if (EVIDENCE_FILE_EXTENSIONS.has(ext)) return { kind: 'file', value };
+    }
+  }
   return { kind: 'command', value };
 }
 
@@ -624,6 +665,14 @@ async function handleStatus(argv, ctx) {
       visibility: dest.visibility ?? 'unresolved',
       derived: !!dest.derived,
       reason: dest.reason ?? null,
+      // Issue #244 (0.28.3): the preview surface prints
+      // `source: <library-manifest|package-bugs-url|derived|...>` so
+      // the operator can see WHICH resolver path picked the destination.
+      // The --json surface must expose the same field for programmatic
+      // verifiers per AC-15502-2 (--json emits the same as text). The
+      // field is null when the resolver did not attach one (e.g. an
+      // unresolved library).
+      source: dest.source ?? null,
     });
   }
 
@@ -672,6 +721,12 @@ async function handleStatus(argv, ctx) {
         ? `${row.repo} (${row.visibility}${row.derived ? ', derived' : ''})`
         : `(unresolved${row.reason ? `: ${row.reason}` : ''})`;
       stdout.write(`  - ${row.ref} -> ${cell}\n`);
+      // Issue #244 (0.28.3): print the resolver source so text and
+      // --json carry the same disclosure. Preview already prints this;
+      // status now matches per AC-15502-2 parity.
+      if (row.source) {
+        stdout.write(`    source: ${row.source}\n`);
+      }
     }
   }
   return 0;
@@ -1003,15 +1058,76 @@ async function handlePreview(argv, ctx) {
  */
 async function buildRedactionContext(projectRoot) {
   let operatorName;
+  // 0.28.3 (R5g, issue #246): track why identity folding might be
+  // disabled so we can emit exactly one visible stderr warning
+  // instead of leaving the operator to guess. `disabledReason` is
+  // one of 'no-profile' (rcf/.identity/profile.md is missing or
+  // unreadable), 'no-name-line' (present but no `## Name` heading),
+  // 'blank-name' (whitespace-only), 'placeholder' (matches the
+  // placeholder/todo regex), 'stopword-only' (Name contains only
+  // reserved-noun tokens), or null when a foldable identity was
+  // extracted.
+  let disabledReason = 'no-profile';
   try {
     const profile = await readFile(resolve(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
-    const m = profile.match(/^##\s+Name\s*\n([^\n]+)/m);
-    if (m) {
-      const n = m[1].trim();
-      if (n && !/placeholder|todo|your name/i.test(n)) operatorName = n;
+    // Codex P1-2: extract the Name-section body up to the next `## `
+    // heading or EOF, using ONLY horizontal whitespace on the heading
+    // line so an empty section (`## Name\n\n## Role\n...`) does not
+    // greedy-match into the next section's heading. Bind the search
+    // to the first `## Name` header only.
+    // JS regex has no `\Z`; use a lookahead for the next `## ` header
+    // OR end of string. `[\s\S]*?` is lazy so it stops at the first
+    // matching lookahead.
+    const nameSection = profile.match(/^##[ \t]+Name[ \t]*\n([\s\S]*?)(?=^##[ \t]+|$(?![\s\S]))/m);
+    if (!nameSection) {
+      disabledReason = 'no-name-line';
+    } else {
+      // The first non-empty non-comment line inside the Name section is
+      // the operator's identity. Strip whitespace and leading/trailing
+      // markdown emphasis so a shipped placeholder like
+      // `_(who you are; how you want the agent to address you)_` is
+      // seen as text, not folded as a name token.
+      const nonEmpty = nameSection[1].split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+      const first = nonEmpty[0];
+      if (!first) {
+        disabledReason = 'blank-name';
+      } else if (/^_\(.*\)_$/i.test(first) || /placeholder|todo|your name/i.test(first) || /^_.*(who you are|how you want).*_$/i.test(first)) {
+        // Codex P1-3: recognise the shipped seed placeholder shape
+        // `_(who you are; how you want the agent to address you)_`
+        // as a placeholder so the untouched generated profile emits
+        // the disabled-folding warning rather than folding the
+        // placeholder text as a name.
+        disabledReason = 'placeholder';
+      } else {
+        operatorName = first;
+        const rawTokens = first.split(/\s+/);
+        const foldable = rawTokens.filter((t) => t.length > 3 && !RESERVED_IDENTITY_TOKENS.has(t.toLowerCase()));
+        if (foldable.length === 0) {
+          disabledReason = 'stopword-only';
+        } else {
+          disabledReason = null;
+        }
+      }
     }
   } catch { /* absent is fine */ }
 
+  // Emit the one-line warning once per context build. All disabled
+  // reasons carry the same fix pointer so the operator knows how to
+  // arm folding without having to read the source.
+  if (disabledReason) {
+    const path = 'rcf/.identity/profile.md';
+    const detail = {
+      'no-profile': `${path} is missing`,
+      'no-name-line': `${path} has no \`## Name\` heading`,
+      'blank-name': `${path} \`## Name\` line is empty`,
+      'placeholder': `${path} \`## Name\` line is a placeholder`,
+      'stopword-only': `${path} \`## Name\` line contains only reserved nouns`,
+    }[disabledReason] ?? path;
+    process.stderr.write(
+      `[warn] operator-identity: ${detail}; identity folding is disabled. Add a real \`## Name\` line to arm the redactor.\n`
+    );
+  }
+
   let projectName;
   const remotes = new Set();
   try {