rcf-lite 0.13.0 → 0.14.0

package/guidance/document-model.md

@@ -26,7 +26,7 @@ One page per document type, the reference rule that keeps the tree drift-proof,
 
 **TC (Test Case).** One test: which AC it verifies, where the executable test lives (its test pointer), and its status.
 
-**CN (Code Node).** The spec-to-code bridge: a working-tree source path, optionally `#symbol`-suffixed, that implements one or more acceptance criteria (`implementsAcIds`, which may be empty - an orphan CN is a legitimate state for utilities and glue code). `rcf define validate` checks every CN's path/symbol against the working tree, so a rename or deletion that leaves the pointer dangling is caught the same way a broken spec-side reference is. Author CNs during Stage 2 of the build cycle (see below), not after: `rcf build mark <fbs-id> complete` refuses when an in-scope acceptance criterion has none. Full detail, including the honest limits, is `docs/code-nodes.md` in the rcf-build-lite repo.
+**CN (Code Node).** The spec-to-code bridge: a working-tree source path, optionally `#symbol`-suffixed, that implements one or more acceptance criteria (`implementsAcIds`, which may be empty - an orphan CN is a legitimate state for utilities and glue code). `rcf define validate` checks every CN's path/symbol against the working tree, so a rename or deletion that leaves the pointer dangling is caught the same way a broken spec-side reference is. Author CNs during Stage 2 of the build cycle (see below), not after: `rcf build mark <fbs-id> complete` refuses when an in-scope acceptance criterion has none. Full detail, including the honest limits, is `docs/code-nodes.md` in the rcf-lite repo.
 
 ## Edges live on the child
 

package/guidance/harness-template.md

@@ -222,6 +222,19 @@ ask for. A failure the operator has to point out is a failure you did
 not check for. The depth for each stage's self-check lives in the
 build-cycle playbook.
 
+### RULE 14: Check freshness at session start; offer, never install.
+
+At the start of a new session on this project, run `rcf version --check`
+(one call, silent on network trouble) and note the result. If a newer
+release is available, tell the operator in one line what changed and
+OFFER the upgrade. The exact command to run depends on how rcf-lite is
+installed here (global npm, per-repo dep, npx pin); propose the command
+that matches this repo's setup and wait for the operator's yes before
+running it. If the check reports `status: "unknown"` (offline, cache
+miss, feed unreachable) say nothing to the operator; freshness is a
+convenience, not a gate. Never run the upgrade without the operator's
+explicit go.
+
 ### Session start
 
 Run `rcf define validate`. A broken tree is fixed or reported before anything

package/guidance/managed/agent-instructions-block.hash

@@ -1 +1 @@
-70e0048d6160f15191dfbcf43588b0ba4cd24349b7ee8098671f121110677348
+a36dfe0d47c57bafa2ace121e7390fac95c7fff70ee362e864adf75c07be190a

package/guidance/managed/agent-instructions-block.md

@@ -209,6 +209,19 @@ ask for. A failure the operator has to point out is a failure you did
 not check for. The depth for each stage's self-check lives in the
 build-cycle playbook.
 
+### RULE 14: Check freshness at session start; offer, never install.
+
+At the start of a new session on this project, run `rcf version --check`
+(one call, silent on network trouble) and note the result. If a newer
+release is available, tell the operator in one line what changed and
+OFFER the upgrade. The exact command to run depends on how rcf-lite is
+installed here (global npm, per-repo dep, npx pin); propose the command
+that matches this repo's setup and wait for the operator's yes before
+running it. If the check reports `status: "unknown"` (offline, cache
+miss, feed unreachable) say nothing to the operator; freshness is a
+convenience, not a gate. Never run the upgrade without the operator's
+explicit go.
+
 ### Session start
 
 Run `rcf define validate`. A broken tree is fixed or reported before anything

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rcf-lite",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "One-install tooling for the Requirements Confidence Framework (RCF): the unified `rcf` CLI grouped into the five RCF tool groups (discover, define, build, verify, audit) plus a small core set (init, doctor, guidance, mcp), an MCP server, the live tree viewer and the fresh-context adversarial ship-gate verifier. Consumes @stravica-ai/rcf-schemas.",
   "license": "Apache-2.0",
@@ -27,6 +27,7 @@
     "src",
     "guidance",
     "rcf",
+    "releases",
     "fixtures",
     "blueprints",
     "scripts/preinstall-node-check.mjs",
@@ -43,10 +44,11 @@
     "vendor": "node scripts/vendor-mermaid.mjs",
     "build:managed": "node scripts/gen-managed-artefacts.mjs",
     "canary:register": "node scripts/canary-register.mjs",
+    "validate:releases": "node scripts/validate-releases.mjs",
     "stage:blueprints": "node scripts/stage-blueprint-shelf.mjs",
     "preinstall": "node scripts/preinstall-node-check.mjs",
     "prepack": "node scripts/stage-blueprint-shelf.mjs",
-    "prepublishOnly": "node scripts/gen-managed-artefacts.mjs && node scripts/stage-blueprint-shelf.mjs",
+    "prepublishOnly": "node scripts/gen-managed-artefacts.mjs && node scripts/stage-blueprint-shelf.mjs && node scripts/validate-releases.mjs",
     "rcf": "node bin/rcf.js"
   },
   "repository": {
@@ -76,6 +78,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.0",
     "mermaid": "11.6.0"
   }
 }

package/rcf/adrs/adr-001.json

@@ -5,7 +5,7 @@
   "version": "0.1.0",
   "status": "accepted",
   "title": "Local filesystem is the single source of truth",
-  "context": "RCF Build Lite must guarantee that a project's RCF documents live in the source repository, beside the code. v1 tooling operated over the GitHub API rather than the local repo, which broke the in-repository differentiator and tied the tool to a network surface.",
+  "context": "RCF Lite must guarantee that a project's RCF documents live in the source repository, beside the code. v1 tooling operated over the GitHub API rather than the local repo, which broke the in-repository differentiator and tied the tool to a network surface.",
   "decision": "Every read and write targets the local rcf tree directly. No external service, cache or database mirrors the documents. The CLI, the MCP server and the build loop all reach the filesystem only through the document store.",
   "consequences": "The tool works offline and stays harness-agnostic. There is no sync problem and no second source to drift. The cost is that any multi-user or hosted scenario is out of scope by construction, which matches the product boundaries.",
   "alternativesConsidered": [

package/rcf/adrs/adr-009.json

@@ -12,7 +12,7 @@
     },
     {
       "name": "Build an independent-gate subsystem now",
-      "summary": "Solve the independent-verification problem inside rcf-build-lite immediately.",
+      "summary": "Solve the independent-verification problem inside rcf-lite immediately.",
       "reasonNotChosen": "That is a separate product being scoped at HQ; duplicating it here pre-empts a repo reshape and over-builds the lite tier. The Tier-1 scope is guidance, not a gate."
     }
   ],

package/rcf/build-sequence.json

@@ -3,7 +3,7 @@
   "prdId": "PRD-001",
   "version": "0.1.0",
   "status": "draft",
-  "title": "RCF Build Lite initial delivery",
+  "title": "RCF Lite initial delivery",
   "buildPhilosophy": "Dependency-first. Build the document store, then the read-only view surface, then mutating CRUD, then the query layer, then the build loop, then the MCP surface over everything below. Each layer is usable on its own before the next is added.",
   "generationStrategy": "dependencyFirst",
   "createdAt": "2026-06-25T00:00:00Z",

package/rcf/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": "2.0.0",
-  "projectName": "RCF Build Lite",
-  "description": "RCF tree for the RCF Build Lite product. Manifest declares the three root documents; every other document is discovered by walking from the roots.",
+  "projectName": "RCF Lite",
+  "description": "RCF tree for the RCF Lite product. Manifest declares the three root documents; every other document is discovered by walking from the roots.",
   "prd": {
     "id": "PRD-001",
     "path": "prd.json"

package/rcf/prd.json

@@ -1,9 +1,9 @@
 {
   "prdId": "PRD-001",
-  "productName": "RCF Build Lite",
+  "productName": "RCF Lite",
   "version": "0.1.0",
   "status": "draft",
-  "executiveSummary": "RCF Build Lite is the tooling product of the RCF suite. It runs the full Requirements Confidence Framework over a project whose RCF documents live in the source repository, alongside the code. It gives a non-engineering product owner deterministic create, read, update and delete operations on every RCF document type, a visual review surface, traceability and query, a build loop that turns build specifications into implementation prompts, and a local MCP surface that exposes all of this to AI tooling.",
+  "executiveSummary": "RCF Lite is the tooling product of the RCF suite. It runs the full Requirements Confidence Framework over a project whose RCF documents live in the source repository, alongside the code. It gives a non-engineering product owner deterministic create, read, update and delete operations on every RCF document type, a visual review surface, traceability and query, a build loop that turns build specifications into implementation prompts, and a local MCP surface that exposes all of this to AI tooling.",
   "problemStatement": "Power vibe-coders build real applications without engineering teams. They cannot read code, so they cannot judge whether what an AI tool produces is trustworthy. The full RCF chain makes output trustworthy without reading code, but authoring that chain by hand is the very effort these users lack the time and discipline for. There is no tool that runs the full RCF method over in-repository documents and surfaces it through structured, deterministic operations.",
   "targetUsers": [
     "Power vibe-coders: product owners, founders and business voices building applications without engineering teams",

package/releases/releases.yaml

@@ -0,0 +1,116 @@
+# rcf-lite release feed source of truth.
+#
+# This file is the single source that the docs site (stravica.ai) reads
+# at build time to publish the machine-readable feed at
+#   https://stravica.ai/docs/rcf/releases.json
+# and that the rcf-lite package's prepublishOnly step validates against
+# `package.json:version` so a release cannot ship without its own entry.
+#
+# Contract lives in
+#   projects/rcf-lite-wsd/specs/update-awareness-spec-2026-08-28.md
+# section 1 (ratified 2026-08-30).
+#
+# Editing rules at release time:
+#   1. Add the new release as the top entry under `releases:` (newest
+#      first).
+#   2. Update `latest:` to match the new top entry's `version`.
+#   3. Keep `headlines[]` operator-facing: one to three sentences, plain
+#      language, sentence case, terminal period, no method vocabulary
+#      shortcuts.
+#   4. Set `breaking: true` only when the release is a semver-breaking
+#      change per the pre-1.0 breaking-is-minor convention (see
+#      CHANGELOG.md preamble).
+#   5. `minAgentAction` names the extra work the agent needs to do beyond
+#      running the install command. `null` means no extra action. The
+#      enumerated values are listed in the spec section 1.5:
+#        - rewrite-shell-invocations
+#        - rerun-init
+#        - regenerate-chain
+#        - schema-migration
+#   6. `notesUrl` is optional. It currently points at the top of the
+#      human changelog; per-release deep links are a follow-up once the
+#      docs pipeline gives /docs/ headings stable anchor ids.
+#   7. Do not delete or rewrite historical entries; the feed is append-only.
+#
+# Every published release under the `rcf-lite` npm name is listed here.
+# The pre-rename history (packages published under
+# `@stravica-ai/rcf-build-lite`, `@stravica-ai/rcf-lite-core`, and
+# `@stravica-ai/rcf-verify-lite`) lives in CHANGELOG.md but is not part of
+# this feed; the feed is scoped to what an operator can install today as
+# `npm install rcf-lite`.
+
+feedVersion: 1
+latest: "0.14.0"
+releases:
+  - version: "0.14.0"
+    date: "2026-08-31"
+    breaking: true
+    headlines:
+      - "The ci-pipeline blueprint is renamed to delivery-ci-workflows and gains a broader set of CI workflows and optional checks."
+      - "A new rcf version command reports the installed version, with --check comparing against the release feed."
+      - "Rerun rcf init to refresh the agent guidance block with the new session-start freshness check."
+    minAgentAction: "rerun-init"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.13.0"
+    date: "2026-08-31"
+    breaking: false
+    headlines:
+      - "The 14 first-party blueprints now ship inside the installed package, so any doc pointing at a blueprint slug works on a fresh install."
+      - "rcf define blueprint add resolves bare slugs and @stock slugs against the packaged shelf, matching how the docs write the commands."
+      - "Installing on Node earlier than 24 now refuses outright instead of silently resolving an old placeholder release."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.12.0"
+    date: "2026-08-28"
+    breaking: true
+    headlines:
+      - "Tests that claim to pass or fail must now point at a real test file, enforced by the shared schema."
+      - "Tests marked pending or skipped no longer need a pointer, matching how in-progress coverage really looks."
+    minAgentAction: "schema-migration"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.11.0"
+    date: "2026-08-27"
+    breaking: false
+    headlines:
+      - "The shipped agent guidance gained three new rules for how the agent drives the method loop."
+      - "Re-run rcf init to refresh the managed block in your project's agent instructions file."
+    minAgentAction: "rerun-init"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.10.0"
+    date: "2026-08-26"
+    breaking: true
+    headlines:
+      - "The command-line interface is reorganised: every command now sits under one of five groups."
+      - "Old flat command forms fail with a message that names the new form."
+    minAgentAction: "rewrite-shell-invocations"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.9.0"
+    date: "2026-08-25"
+    breaking: false
+    headlines:
+      - "Blueprints landed: compose pre-built implementation patterns onto your project instead of inventing them from a blank page."
+      - "Six starter blueprints ship in the same release, covering web app, REST API, auth, persistence, CI pipeline and observability."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.8.0"
+    date: "2026-08-12"
+    breaking: false
+    headlines:
+      - "A shared standards ruleset ships bundled with the package and now feeds refuse-first admissibility checks on the chain."
+      - "The verifier catches a subtle dishonesty: a test that is narrower in scope than the check it claims to prove."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.7.1"
+    date: "2026-08-12"
+    breaking: false
+    headlines:
+      - "The first release under the unified rcf-lite name, bringing the previously separate tools together as one package on the public npm registry."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"

package/src/blueprint/apply.js

@@ -15,6 +15,7 @@ import { readFile } from 'node:fs/promises';
 import { rcfError } from '../core/errors/index.js';
 import { subdirFor } from '#core/store';
 import { detectCrossBlueprintClaims, detectGlobalAdrConflicts } from './conflicts.js';
+import { detectContributionsOutOfBand } from './library-registry.js';
 import { loadBlueprint } from './loader.js';
 import { updateManifest } from './manifest-writer.js';
 import { stampId } from './namespace.js';
@@ -40,6 +41,19 @@ import { nextResolutionId } from './resolutions.js';
  *        string the operator can copy back. Defaults to `source` when omitted (so
  *        existing callers keep today's byte-for-byte behaviour).
  * @param {string} [args.namespaceOverride] - non-default namespace slug
+ * @param {string} [args.effectiveSlug] - override for the blueprint's own slug
+ *        when applied through an external-library qualified reference (spec §5.3):
+ *        `<libraryPrefix>-<blueprintSlug>`. When set, this becomes BOTH the
+ *        stamping namespace (so contributions inherit the library prefix) AND
+ *        the value written into `manifest.blueprints[].slug` on the applied
+ *        record, so `rcf define blueprint remove wsd-auth-oauth2` reads back
+ *        cleanly. `namespaceOverride` still wins over `effectiveSlug` if both
+ *        are set (operator explicitly chose a different namespace).
+ * @param {{ ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> }} [args.libraryBands]
+ *        Declared bands from the resolved library. When set, every stamped
+ *        contribution is band-gated before write; a contribution whose numeric
+ *        portion falls outside the library's bands refuses at apply-time (spec
+ *        §8.3, open question 9.9 ratified as "add both").
  * @param {Array<{ topic: string, resolvedByAdrId: string }>} [args.resolveDeclarations]
  *        Operator-supplied conflict resolutions declared on the add
  *        itself. One entry per resolved topic. For each, the resolution
@@ -58,25 +72,38 @@ import { nextResolutionId } from './resolutions.js';
  *        prove the rollback runs. Never used in production.
  * @returns {Promise<ApplyResult | import('../core/errors/index.js').RcfError>}
  */
-export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryBands, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
   const hintSource = typeof displaySource === 'string' && displaySource.length > 0 ? displaySource : source;
   const blueprint = await loadBlueprint(source);
   if (blueprint.kind) return blueprint; // RcfError
-  const namespace = namespaceOverride ?? blueprint.slug;
+  // Effective slug rewires the blueprint's identity under a library
+  // prefix (spec §5.3). It becomes both the stamping namespace and the
+  // slug written into `manifest.blueprints[].slug`. `namespaceOverride`
+  // still wins over `effectiveSlug` (operator's explicit --namespace on
+  // the CLI). When neither is set the blueprint's own slug applies.
+  const appliedSlug = typeof effectiveSlug === 'string' && effectiveSlug.length > 0
+    ? effectiveSlug
+    : blueprint.slug;
+  const namespace = namespaceOverride ?? appliedSlug;
 
   const applied = tree.manifest?.blueprints ?? [];
-  const existing = applied.find((b) => b.slug === blueprint.slug);
+  const existing = applied.find((b) => b.slug === appliedSlug);
   const stamped = stampContributions(blueprint.contributions, namespace);
   if (stamped.error) {
     return rcfError({ kind: 'validation', message: stamped.error });
   }
+  // Apply-time band gate for external-library blueprints.
+  if (libraryBands) {
+    const bandErr = detectContributionsOutOfBand(stamped.contributions, libraryBands);
+    if (bandErr) return bandErr;
+  }
 
   // Pre-detection: fold operator-supplied --resolve declarations into a
   // WORKING COPY of the manifest so the detector honours them on this
   // run. The final manifest write later composes the same resolution
   // records into the persisted manifest, so the in-memory copy and the
   // on-disk write agree.
-  const incomingForConflicts = { slug: blueprint.slug, contributions: stamped.contributions };
+  const incomingForConflicts = { slug: appliedSlug, contributions: stamped.contributions };
   const declResult = composeDeclaredResolutions({
     manifest: tree.manifest,
     applied,
@@ -109,7 +136,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     ...detectCrossBlueprintClaims(applied, incomingForConflicts),
   ];
   if (conflicts.length > 0) {
-    return { applied: false, slug: blueprint.slug, version: blueprint.version, contributions: [], conflicts };
+    return { applied: false, slug: appliedSlug, version: blueprint.version, contributions: [], conflicts };
   }
 
   // Ownership set for the overwrite guard below. On a re-apply, the
@@ -122,7 +149,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   if (existing && existing.version === blueprint.version) {
     return {
       applied: false, alreadyApplied: true,
-      slug: blueprint.slug, version: blueprint.version,
+      slug: appliedSlug, version: blueprint.version,
       contributions: stamped.contributions,
       ...(duplicateResolveTopics.length > 0 ? { warnings: [{ kind: 'duplicateResolveTopic', topics: duplicateResolveTopics }] } : {}),
     };
@@ -151,7 +178,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
       writtenContributions.push(preserveScope({ id: c.id, kind: c.kind, path: relDest }, c));
     }
   } else {
-    const tmpSuffix = `.rcf-tmp-${blueprint.slug}-${now.getTime()}`;
+    const tmpSuffix = `.rcf-tmp-${appliedSlug}-${now.getTime()}`;
     const stagedWrites = []; // { tmpAbs, absDest, relDest, id, kind, c }
     const rollback = async (err) => {
       for (const w of stagedWrites) {
@@ -184,7 +211,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
           for (const w of stagedWrites) await unlink(w.tmpAbs).catch(() => {});
           return rcfError({
             kind: 'duplicateId',
-            message: `blueprint apply: contribution ${c.id} would overwrite an existing file at ${relDest} that is not recorded as owned by blueprint '${blueprint.slug}'.`,
+            message: `blueprint apply: contribution ${c.id} would overwrite an existing file at ${relDest} that is not recorded as owned by blueprint '${appliedSlug}'.`,
             filePath: relDest,
           });
         }
@@ -225,12 +252,23 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     }
   }
 
-  // Update manifest.blueprints[].
+  // Update manifest.blueprints[]. The applied record's `source` field
+  // carries the qualified typed ref for library-resolved blueprints
+  // (`wsd:auth-oauth2`) so `rcf define blueprint upgrade` reads back
+  // cleanly (spec §5.3); local-path applies carry the absolute path as
+  // today. The optional `libraryPrefix` field named in spec §5.3 is a
+  // schema-additive change on `appliedBlueprintRecord` (the record's
+  // schema is `additionalProperties: false`); it is deferred and
+  // tracked in the PR description as a follow-up so the shape lands as
+  // a coordinated schemas + rcf-lite bump.
+  const recordSource = typeof displaySource === 'string' && displaySource.length > 0 && displaySource !== source
+    ? displaySource
+    : source;
   const nextEntry = {
-    slug: blueprint.slug,
+    slug: appliedSlug,
     version: blueprint.version,
     appliedAt: now.toISOString(),
-    source,
+    source: recordSource,
     ...(namespaceOverride ? { namespace: namespaceOverride } : {}),
     ...(writtenContributions.length > 0 ? { contributions: writtenContributions } : {}),
   };
@@ -239,7 +277,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     manifest: tree.manifest,
     mutate: (next) => {
       const list = Array.isArray(next.blueprints) ? next.blueprints : [];
-      const filtered = list.filter((b) => b.slug !== blueprint.slug);
+      const filtered = list.filter((b) => b.slug !== appliedSlug);
       filtered.push(nextEntry);
       next.blueprints = filtered;
       // Fold any --resolve declarations recorded on this add into the
@@ -257,7 +295,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
 
   return {
     applied: true,
-    slug: blueprint.slug,
+    slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
     ...(duplicateResolveTopics.length > 0 ? { warnings: [{ kind: 'duplicateResolveTopic', topics: duplicateResolveTopics }] } : {}),

package/src/blueprint/index.js

@@ -11,3 +11,15 @@ export { nextResolutionId, matchingResolution } from './resolutions.js';
 export { supersedeBlueprintTopic } from './supersede.js';
 export { diffBlueprintTopic, renderDiff } from './diff.js';
 export { resolveBlueprintSource, knownShelfSlugs, packagedShelfPath } from './shelf-resolver.js';
+export { loadLibrary } from './library-loader.js';
+export {
+  REGISTRY_PATH,
+  REGISTRY_VERSION,
+  readLibraryRegistry,
+  writeLibraryRegistry,
+  findLibrary,
+  loadCoreBandReservations,
+  detectBandOverlap,
+  detectContributionsOutOfBand,
+  detectPrefixCollision,
+} from './library-registry.js';