@vectros-ai/blueprints 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to `@vectros-ai/blueprints` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.4 — 2026-07-03
+
+### Added
+
+- **`agentic-sdlc` `editor` role now carries full data-plane delete** (blueprint `1.1.0 → 1.2.0`).
+  The human owner's `editor` role gains `records:d` / `documents:d` / `folders:d` on top of the
+  shared data-plane actions — so a person granted `editor` can hard-delete data-plane content
+  (curation cleanup), while the agent's service key stays delete-free and curates by soft-retract
+  (archive) instead. Deleting only *your own* data via a scoped credential is a separate, later
+  capability; today `editor` is context-wide.
+- **Guide + agent prompt now include KB query-mechanics guidance.** Reach for `record_query`
+  before `hybrid_search` for an enumerable ask (exact + compact); query compactly by default
+  (`limit: 3` + `uniqueDocuments: true`, since hits carry passages); how to scope by type per
+  tool (`hybrid_search` uses `typeName`, which narrows documents and records alike;
+  `record_query` uses `type`); and the `textMode: PHRASE` keyword-leg trap on long natural-language queries
+  (a `textScore` of 0 on every hit means the keyword leg contributed nothing — use a short
+  phrase or `textMode: "OR"`).
+- **`agentic-sdlc` records now carry a `sourceRef` field** (blueprint `1.0.0 → 1.1.0`).
+  The four record types (`control`, `convention`, `gotcha`, `term`) gain a `sourceRef` string —
+  the repo path of the source file each record was distilled from — as an equality
+  lookup. It is the record analog of the provenance a document keeps: because many
+  records are extracted from one file, a record can't embed an in-file back-reference,
+  so it names its source instead. A change to a source file then finds exactly its
+  records (`record_query` by `sourceRef`) to re-extract, keeping the knowledge base in
+  sync with the repository without a separate index to maintain. Additive and
+  backward-compatible; existing records simply have no `sourceRef` until re-extracted.
+- **Guide + agent prompt now document the repo↔KB sync pattern in full** — the two
+  self-describing markers (`vectros-kb-id` for a file that *is* a KB document,
+  `vectros-kb-records` for a file that *feeds* records) plus `sourceRef`, so a consumer
+  can keep a mirrored repo and its KB in sync with no side index.
+
+## 0.6.3 — 2026-07-01
+
+### Added
+
+- **`agentic-sdlc` now declares an `editor` role for the human owner.** `bootstrap`
+  provisions a scoped key for your *agent*, but doesn't join *you* — so a blueprint's
+  context doesn't appear in the data-plane app until your own user is granted access
+  there. The blueprint now ships a reusable `editor` role at **parity with the service
+  key** (`records:r/c/u`, `search:r`, `schemas:r`, `inference:r`, `documents:r/c`,
+  `folders:r/c`; no delete, no control-plane), which `bootstrap` creates in the context.
+  Bind it to your user once to browse and curate the KB in the app:
+  `vectros access grant --principal usr_<your-user-id> --context agentic-sdlc --role editor`
+  (or via the admin app's Access → Contexts → Profiles). The guide and walkthrough
+  document the one-time join, and the package README now documents the top-level
+  `roles` format field (previously undocumented — no bundled blueprint used it).
+
 ## 0.6.2 — 2026-06-29
 
 ### Changed

package/README.md

@@ -115,6 +115,16 @@ The `accessProfile.dataScope` value lists accept a **`null` sentinel** — e.g.
 (owner-less / shared) records. Omitting `null` restricts the key to the listed
 owners only.
 
+A blueprint may also declare top-level **`roles`** — a map of `roleId` → ordered
+scope clauses (each an `allowedActions` list with an optional `dataScope`). Unlike
+`accessProfile` (which scopes the service-principal key `bootstrap` mints), roles
+are reusable, identity-agnostic rules you bind to a principal *after* bootstrap with
+`vectros access grant --principal <p> --role <roleId>`. `bootstrap` provisions the
+declared roles in the context but binds them to no one. The bundled `agentic-sdlc`
+ships an `editor` role for this — join your own user to the context so you can
+browse and curate the knowledge base in the app. Role clauses pass the same
+data-plane scope gate as `accessProfile`.
+
 All of the above are **optional and backward-compatible** — a blueprint that
 omits them parses and provisions exactly as before.
 

package/dist/index.js

@@ -1065,9 +1065,22 @@ var codingAgentMemory = {
 var coding_agent_memory_default = codingAgentMemory;
 
 // src/blueprints/agentic-sdlc.ts
+var DATA_PLANE_ACTIONS = [
+  "records:r",
+  "records:c",
+  "records:u",
+  "search:r",
+  "schemas:r",
+  "inference:r",
+  "documents:r",
+  "documents:c",
+  "folders:r",
+  "folders:c"
+];
+var EDITOR_ACTIONS = [...DATA_PLANE_ACTIONS, "records:d", "documents:d", "folders:d"];
 var agenticSdlc = {
   name: "agentic-sdlc",
-  version: "1.0.0",
+  version: "1.2.0",
   description: "A whole-SDLC system of record for an AI development team \u2014 decisions, designs, references, runbooks, post-mortems (as documents) plus controls, conventions, gotchas, and a glossary (as records), cross-linked and recalled by meaning.",
   contextId: "agentic-sdlc",
   contextName: "Agentic SDLC Knowledge Base",
@@ -1502,6 +1515,19 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 last-reviewed date. Range-queryable.",
           renderHints: { label: "Reviewed on", widget: "date", order: 12 }
+        },
+        {
+          // Provenance for sync: the source file this record was distilled from. A
+          // record can't carry an in-file marker the way a document can (many records
+          // come from one file), so it names its source instead — a change to that file
+          // finds (equality lookup) and re-extracts exactly its records. Equality, not
+          // range: file-level is the sync unit (re-extraction reprocesses the whole file),
+          // and the schema keeps its single range lookup for the date row.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 13 }
         }
       ],
       lookupFields: [
@@ -1511,7 +1537,8 @@ var agenticSdlc = {
         "area",
         "verifiedBy",
         "relatedDecision",
-        { fieldName: "reviewedOn", rangeEnabled: true }
+        { fieldName: "reviewedOn", rangeEnabled: true },
+        "sourceRef"
       ]
     },
     {
@@ -1588,9 +1615,23 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when last revised. Range-queryable.",
           renderHints: { label: "Updated on", widget: "date", order: 9 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 10 }
         }
       ],
-      lookupFields: ["area", "status", "establishedBy", { fieldName: "updatedOn", rangeEnabled: true }]
+      lookupFields: [
+        "area",
+        "status",
+        "establishedBy",
+        { fieldName: "updatedOn", rangeEnabled: true },
+        "sourceRef"
+      ]
     },
     {
       // A GOTCHA / sharp edge: a symptom, its cause, and the fix. A tight typed
@@ -1644,9 +1685,22 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when first hit. Range-queryable.",
           renderHints: { label: "Discovered on", widget: "date", order: 7 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 8 }
         }
       ],
-      lookupFields: ["area", "status", { fieldName: "discoveredOn", rangeEnabled: true }]
+      lookupFields: [
+        "area",
+        "status",
+        { fieldName: "discoveredOn", rangeEnabled: true },
+        "sourceRef"
+      ]
     },
     {
       // A glossary TERM — a definition keyed by the term itself. Structure-dominant:
@@ -1706,6 +1760,14 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when last revised. Range-queryable.",
           renderHints: { label: "Updated on", widget: "date", order: 7 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 8 }
         }
       ],
       // `term` is a UNIQUE equality lookup — exact "define X" + a one-per-term
@@ -1714,27 +1776,32 @@ var agenticSdlc = {
         { fieldName: "term", unique: true },
         "area",
         "relatedDecision",
-        { fieldName: "updatedOn", rangeEnabled: true }
+        { fieldName: "updatedOn", rangeEnabled: true },
+        "sourceRef"
       ]
     }
   ],
-  // Least-privilege, data-plane only. r/c/u records + search + schema discovery +
-  // inference:r (grounded recall over the document bodies) + document/folder r/c
-  // (the content artifacts are documents). NO :d — knowledge is superseded/retired
-  // via a status flip, so the trail of how the team's thinking evolved stays intact.
+  // Least-privilege, data-plane only. The scope of the `ssk_*` key the bootstrap
+  // mints for THIS blueprint's service principal (the MCP/API runtime). See
+  // DATA_PLANE_ACTIONS above for the action set + rationale.
   accessProfile: {
-    allowedActions: [
-      "records:r",
-      "records:c",
-      "records:u",
-      "search:r",
-      "schemas:r",
-      "inference:r",
-      "documents:r",
-      "documents:c",
-      "folders:r",
-      "folders:c"
-    ]
+    allowedActions: DATA_PLANE_ACTIONS
+  },
+  // A reusable `editor` role for the HUMAN owner — DISTINCT from `accessProfile`
+  // (which scopes only the service-principal key). `bootstrap` provisions this
+  // role in the context but binds it to no one; the owner joins themselves so the
+  // data-plane app (app.vectros.ai) shows their KB — its switcher lists only
+  // contexts the signed-in user holds an active access profile in, and bootstrap
+  // grants the human none by default. Bind it after bootstrap with:
+  //   vectros access grant --principal usr_<your-user-id> --context agentic-sdlc --role editor
+  // (or the admin app's Access > Contexts > agentic-sdlc > Profiles > Create).
+  // The editor gets the full data plane so a human curator can browse, write/correct,
+  // AND hard-delete the KB (EDITOR_ACTIONS = the service key's set + delete). The
+  // service key deliberately lacks delete and archives instead; the trusted human
+  // owner may permanently remove genuine strays. Still no control-plane action, so
+  // the scope gate accepts it as a data-plane-only role.
+  roles: {
+    editor: [{ allowedActions: EDITOR_ACTIONS }]
   },
   servicePrincipal: {
     externalId: "agentic-sdlc",