rcf-lite 0.14.0 → 0.16.0

package/fixtures/canary-manifest.json

@@ -1,3 +1,103 @@
 {
-  "registerCanary": []
+  "registerCanary": [
+    {
+      "id": "rc-2026-09-03-001",
+      "createdAt": "2026-09-03T13:16:14.200Z",
+      "buildVersion": "0.16.0-mockdriver",
+      "fixturePromptId": "canary-prompt-01",
+      "responseWordCount": 55,
+      "grades": {
+        "internalRuleCitation": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "unglossedJargon": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "redundantPermissionAsk": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "bypassOffer": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "wordCountBudget": {
+          "verdict": "pass",
+          "target": 200,
+          "actual": 55,
+          "matches": []
+        }
+      },
+      "verdict": "fail",
+      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
+    },
+    {
+      "id": "rc-2026-09-03-002",
+      "createdAt": "2026-09-03T13:16:14.200Z",
+      "buildVersion": "0.16.0-mockdriver",
+      "fixturePromptId": "canary-prompt-02",
+      "responseWordCount": 55,
+      "grades": {
+        "internalRuleCitation": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "unglossedJargon": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "redundantPermissionAsk": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "bypassOffer": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "wordCountBudget": {
+          "verdict": "pass",
+          "target": 200,
+          "actual": 55,
+          "matches": []
+        }
+      },
+      "verdict": "fail",
+      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
+    },
+    {
+      "id": "rc-2026-09-03-003",
+      "createdAt": "2026-09-03T13:16:14.201Z",
+      "buildVersion": "0.16.0-mockdriver",
+      "fixturePromptId": "canary-prompt-03",
+      "responseWordCount": 55,
+      "grades": {
+        "internalRuleCitation": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "unglossedJargon": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "redundantPermissionAsk": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "bypassOffer": {
+          "verdict": "pass",
+          "matches": []
+        },
+        "wordCountBudget": {
+          "verdict": "pass",
+          "target": 200,
+          "actual": 55,
+          "matches": []
+        }
+      },
+      "verdict": "fail",
+      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
+    }
+  ]
 }

package/guidance/harness-template.md

@@ -56,6 +56,15 @@ non-technical; the method must be invisible in what they read.
 - Tone: it is in hand. The operator steers; you drive. Confident
   without hedging, and plainly honest when something is genuinely
   blocked or ambiguous.
+- Blueprints and libraries. When the operator asks for a starting
+  shape, list what is available (the packaged shelf and any libraries
+  registered on this project) in plain words and offer one that fits.
+  The operator chooses; you do not pick for them. Registering a
+  library is a trust decision the operator makes; when it lands,
+  relay it in a sentence ("added the WSD library to this project").
+  Library-qualified names like `wsd:auth-oauth2`, the ids each apply
+  stamps, and the exact CLI lines belong in files and in `rcf`
+  output, not in the conversation.
 
 Before / after - the same first status after project setup:
 

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

@@ -1 +1 @@
-a36dfe0d47c57bafa2ace121e7390fac95c7fff70ee362e864adf75c07be190a
+1db0aeb320810137f642e7dcdc7e8ffb4b43c9d050383ae3c9d10d10de0dd690

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

@@ -43,6 +43,15 @@ non-technical; the method must be invisible in what they read.
 - Tone: it is in hand. The operator steers; you drive. Confident
   without hedging, and plainly honest when something is genuinely
   blocked or ambiguous.
+- Blueprints and libraries. When the operator asks for a starting
+  shape, list what is available (the packaged shelf and any libraries
+  registered on this project) in plain words and offer one that fits.
+  The operator chooses; you do not pick for them. Registering a
+  library is a trust decision the operator makes; when it lands,
+  relay it in a sentence ("added the WSD library to this project").
+  Library-qualified names like `wsd:auth-oauth2`, the ids each apply
+  stamps, and the exact CLI lines belong in files and in `rcf`
+  output, not in the conversation.
 
 Before / after - the same first status after project setup:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rcf-lite",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -39,18 +39,6 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "scripts": {
-    "test": "node --test --test-concurrency=1 'test/**/*.test.js'",
-    "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 && node scripts/validate-releases.mjs",
-    "rcf": "node bin/rcf.js"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Stravica/rcf-lite.git",
@@ -72,7 +60,7 @@
     "#admissibility": "./src/admissibility/index.js"
   },
   "dependencies": {
-    "@stravica-ai/rcf-schemas": "0.5.0",
+    "@stravica-ai/rcf-schemas": "0.5.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -80,5 +68,15 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0",
     "mermaid": "11.6.0"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 'test/**/*.test.js'",
+    "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",
+    "rcf": "node bin/rcf.js"
   }
-}
+}

package/releases/releases.yaml

@@ -40,8 +40,28 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.14.0"
+latest: "0.16.0"
 releases:
+  - version: "0.16.0"
+    date: "2026-09-03"
+    breaking: false
+    headlines:
+      - "External blueprint libraries now support git and tarball sources with an on-disk cache checked into the tree, plus a refresh command that re-resolves a library's pinned reference and refuses the update on drift."
+      - "Adding a blueprint from a local path inside an unregistered library now stamps the same slug and identity a registered add would, closing the author-and-test-locally loop."
+      - "The managed agent-instructions block now teaches the agent to offer blueprints and registered libraries in plain words so the operator picks; a new library authoring standard doc and worked-example fixture ship with the package. Rerun rcf init to refresh the block."
+    minAgentAction: "rerun-init"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.15.0"
+    date: "2026-08-31"
+    breaking: false
+    headlines:
+      - "Library-applied blueprints now carry a durable ownership stamp so re-registering a library under a different prefix no longer orphans records that came from it."
+      - "The review-on-add card gained a global-topics section and a prefix-check line so a library's cross-topic surface is visible before the operator commits."
+      - "The delivery-ci-workflows blueprint gained optional package-manager and branch-name shape fields, taught the coverage-strict bootstrap trap in the guide, and shipped a starting-point supersession ADR."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.14.0"
     date: "2026-08-31"
     breaking: true

package/src/blueprint/apply.js

@@ -49,6 +49,13 @@ import { nextResolutionId } from './resolutions.js';
  *        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 {string} [args.libraryPrefix] - the registered library prefix the
+ *        blueprint was resolved through (spec §5.3, §7.3). When set the applied
+ *        record carries a `libraryPrefix` field so `rcf library remove`'s
+ *        ownership check reads the ownership fact off the record itself
+ *        rather than string-matching `source`. Absent for shelf and path
+ *        applies. Requires @stravica-ai/rcf-schemas 0.5.1 or later
+ *        (`appliedBlueprintRecord.libraryPrefix`, additive optional).
  * @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
@@ -72,7 +79,7 @@ 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, effectiveSlug, libraryBands, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, 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
@@ -256,11 +263,12 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   // 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.
+  // today. When the apply resolved through a registered external
+  // library the record additionally carries `libraryPrefix`: the
+  // ownership fact for the library-registered ownership check in
+  // `rcf library remove`, so the registry may be edited (renamed,
+  // re-pointed, unregistered) without orphaning previously applied
+  // records. Shelf and path applies carry no `libraryPrefix`.
   const recordSource = typeof displaySource === 'string' && displaySource.length > 0 && displaySource !== source
     ? displaySource
     : source;
@@ -270,6 +278,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     appliedAt: now.toISOString(),
     source: recordSource,
     ...(namespaceOverride ? { namespace: namespaceOverride } : {}),
+    ...(typeof libraryPrefix === 'string' && libraryPrefix.length > 0 ? { libraryPrefix } : {}),
     ...(writtenContributions.length > 0 ? { contributions: writtenContributions } : {}),
   };
   const manifestResult = await updateManifest({

package/src/blueprint/index.js

@@ -23,3 +23,25 @@ export {
   detectContributionsOutOfBand,
   detectPrefixCollision,
 } from './library-registry.js';
+export {
+  CACHE_ROOT,
+  absoluteCachePath,
+  ensureEmptyCache,
+  relativeCachePath,
+  removeCache,
+  resolveCachePath,
+  sanitiseRef,
+} from './library-cache.js';
+export {
+  fetchGitLibrary,
+  parseGitRef,
+  resolveRemoteSha,
+  isFullSha,
+  refusedRefs,
+} from './library-fetcher-git.js';
+export {
+  createUstarBuffer,
+  fetchTarballLibrary,
+  parseUstar,
+  sha256Hex,
+} from './library-fetcher-tarball.js';

package/src/blueprint/library-cache.js

@@ -0,0 +1,143 @@
+// External-library on-disk cache helpers (spec §4.4).
+//
+// Fetched library content sits under
+// `rcf/.blueprint-libraries/<libraryPrefix>/<libraryRef>/`, checked
+// into git as ordinary tree content so a fresh clone can `rcf define
+// blueprint list` without a re-fetch. The cache is the working root
+// the resolver reads through; the `cachePath` field on every registry
+// entry points at it.
+//
+// This module owns path computation and a small set of directory
+// primitives shared by the git and tarball fetchers (Phase 2c). It
+// deliberately does NOT know about git or tar; the fetchers layer on
+// top and land their extracted content at the paths computed here.
+
+import { existsSync } from 'node:fs';
+import { mkdir, rm, stat } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+
+export const CACHE_ROOT = 'rcf/.blueprint-libraries';
+
+/**
+ * Repo-relative cache path for a library at a given ref. Repo-relative
+ * because that is what the registry stores (`entry.cachePath`); the
+ * resolver joins it against `projectRoot` at read time.
+ *
+ * @param {string} libraryPrefix
+ * @param {string} libraryRef
+ * @returns {string}
+ */
+export function relativeCachePath(libraryPrefix, libraryRef) {
+  return `${CACHE_ROOT}/${libraryPrefix}/${sanitiseRef(libraryRef)}`;
+}
+
+/**
+ * Absolute cache path for a library at a given ref, joined against a
+ * project root.
+ *
+ * @param {string} projectRoot
+ * @param {string} libraryPrefix
+ * @param {string} libraryRef
+ * @returns {string}
+ */
+export function absoluteCachePath(projectRoot, libraryPrefix, libraryRef) {
+  const rel = relativeCachePath(libraryPrefix, libraryRef);
+  return isAbsolute(rel) ? rel : join(projectRoot, rel);
+}
+
+/**
+ * Prepare an empty cache directory. Refuses when a non-empty cache
+ * already exists at the target (the caller must remove it first via
+ * `removeCache`, or fail fast and prompt the operator). This keeps
+ * fetches deterministic: content lands on a clean slate every time.
+ *
+ * @param {string} absPath
+ * @param {object} [opts]
+ * @param {boolean} [opts.replace=false] - when true, remove any
+ *   pre-existing content at absPath before creating the fresh dir.
+ * @returns {Promise<null | import('../core/errors/index.js').RcfError>}
+ */
+export async function ensureEmptyCache(absPath, opts = {}) {
+  try {
+    if (existsSync(absPath)) {
+      if (opts.replace === true) {
+        await rm(absPath, { recursive: true, force: true });
+      } else {
+        const s = await stat(absPath);
+        if (s.isDirectory()) {
+          return rcfError({
+            kind: 'usage',
+            message: `library cache: path already exists at ${absPath}. Remove it or run 'library refresh' to re-fetch.`,
+            filePath: absPath,
+          });
+        }
+        return rcfError({
+          kind: 'usage',
+          message: `library cache: non-directory blocks cache path ${absPath}.`,
+          filePath: absPath,
+        });
+      }
+    }
+    await mkdir(absPath, { recursive: true });
+    return null;
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `library cache: could not prepare ${absPath}: ${err.message}`,
+      filePath: absPath,
+      stack: err.stack,
+    });
+  }
+}
+
+/**
+ * Recursive remove of a cache directory. No-op when the path does not
+ * exist. Used by `library remove` and by the fetchers' rollback path.
+ *
+ * @param {string} absPath
+ * @returns {Promise<null | import('../core/errors/index.js').RcfError>}
+ */
+export async function removeCache(absPath) {
+  try {
+    await rm(absPath, { recursive: true, force: true });
+    return null;
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `library cache: could not remove ${absPath}: ${err.message}`,
+      filePath: absPath,
+      stack: err.stack,
+    });
+  }
+}
+
+/**
+ * Resolve an absolute cache path from either an absolute
+ * `entry.cachePath` (legacy local-source entries in phase 2b stored
+ * the library root path here) or a repo-relative one (phase 2c network
+ * fetches store the relative form; the resolver joins with the project
+ * root at read time).
+ *
+ * @param {string} projectRoot
+ * @param {string} cachePath
+ * @returns {string}
+ */
+export function resolveCachePath(projectRoot, cachePath) {
+  return isAbsolute(cachePath) ? cachePath : resolve(projectRoot, cachePath);
+}
+
+/**
+ * Replace path-hostile characters in a libraryRef so it can be used as
+ * a directory segment. Refs are already semver-ish or short tag names
+ * in practice; this guards against a publisher who ships a ref like
+ * `1.2.0/rc1` or an operator who hand-types one. Slashes and colons are
+ * mapped to a single `-` so the on-disk layout stays flat.
+ *
+ * @param {string} ref
+ * @returns {string}
+ */
+export function sanitiseRef(ref) {
+  return String(ref).replace(/[\\/:*?"<>|]+/g, '-');
+}