rcf-lite 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0, breaking changes are signalled by a minor version bump.
 
+## [Unreleased]
+
+## [0.16.0] - 2026-09-03
+
+External blueprint libraries complete. Phase 2c lands git and tarball fetchers with a checked-in on-disk cache so a fresh clone lists library blueprints without a re-fetch, and a refresh path that re-resolves annotated-tag or tarball digest and refuses on drift. Amendment A2 makes plain-path adds library-aware so an author's local edit loop stamps the same effective slug and identity a qualified add would. Amendment A3 adds a blueprint paragraph to the managed agent-instructions block so the agent conversationally offers blueprints and registered libraries and the operator chooses. A library-authoring standard doc plus a worked-example fixture binds the doc against the shipped tooling.
+
+### Added
+
+- **External blueprint libraries phase 2c: git and tarball fetchers + on-disk cache.** `rcf define blueprint library add` now accepts `git+<url>#<annotated-tag-or-sha>` and tarball URLs (with `--sha256 <hex>` for the pin). Fetched content lands 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 (spec section 4.4). Floating branches (`main`, `master`, `HEAD`, `latest`, `develop`, `trunk`) refuse categorically; lightweight tags refuse with a diagnostic pointing at annotation as the fix; a tarball digest mismatch refuses the fetch and writes nothing. `rcf define blueprint library refresh <prefix>` re-resolves the tag's peeled commit (git) or re-downloads and re-verifies the digest (tarball) and refuses on drift per spec sections 6.4 / 9.12. `rcf define blueprint library remove <prefix>` now drops the on-disk cache for network sources. Zero new runtime dependencies: the git side shells out to the ambient `git` CLI; the tarball side uses built-in `fetch()`, `zlib`, and a bundled minimal POSIX-ustar parser. Auth remains out of scope for v1 (spec section 9.4): ambient git access is the model, no-access is definitive.
+- **Amendment A2: library-aware local path (2026-09-03).** `rcf define blueprint add <path>` now walks up from the target directory looking for `library.json`; on a hit the resolver requires the target to sit at `<library-root>/blueprints/<slug>` and stamps the same effective slug and identity a qualified `<prefix>:<slug>` add would after registration. Library-qualified addressing and plain-path addressing now produce identical slugs and stamped ids. A path with no `library.json` in any ancestor keeps the phase-1 route unchanged, byte-for-byte. The trade-off (spec: an unregistered local library bypasses review-on-add) is accepted because the alternative kills the "author now, test now" loop; the `local` provenance warning on apply is the mitigation.
+- **Amendment A3: blueprint paragraph in the managed agent-instructions block (2026-09-03).** New paragraph inside the "How to talk to your operator" section teaches the plain-language shape: agent enumerates blueprints and registered libraries and offers one that fits; the operator chooses, the agent never picks; qualified names and command lines belong in files and `rcf` output, not in the conversation. Hash regenerated via `scripts/gen-managed-artefacts.mjs`; harness template mirrored automatically.
+- **Library authoring standard doc.** `packages/rcf-lite/docs/library-authoring.md` documents the library shape, `library.json` field contract, prefix and band rules, the local-path authoring loop (A2), registration, refresh / drift, and interaction with core. Ships with a minimum-viable worked-example library at `test/fixtures/library-authoring-example/` (prefix `wla`, one blueprint with one REQ and one ADR) that doubles as the fixture body for `test/blueprint/library-authoring-example.test.js`; the fixture binds the doc against the shipped tooling so a drift in either trips the suite.
+
 ## [0.15.0] - 2026-08-31
 
 Same-evening fix wave on top of 0.14.0. Four PRs closing off the WSD-handover surface: durable library-ownership stamping on applied records (paired with `@stravica-ai/rcf-schemas` 0.5.1), `blueprint supersede --incoming` accepting the same source forms as `add`, the review-on-add card gaining its section 8.1 global-topics and prefix-check lines, and the `delivery-ci-workflows` v2.1 additive shape resolving the four P1 findings from the second dogfood run.

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.15.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",

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.15.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

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, '-');
+}