@cat-factory/prompt-fragments 0.16.0 → 1.0.1

package/README.md

@@ -4,7 +4,7 @@ The **built-in tier** of best-practice prompt fragments: small, curated guidance
 snippets that get folded into an agent's system prompt at run time
 (`composeSystemPrompt`). This package is **plain, build-static data**: no I/O, no
 framework. It is the source of truth for the shipped defaults and the seed for the
-tenant-scoped [prompt-fragment library](../../docs/adr/0006-prompt-fragment-library.md).
+tenant-scoped [prompt-fragment library](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0006-prompt-fragment-library.md).
 
 ## What's here
 
@@ -13,7 +13,7 @@ tenant-scoped [prompt-fragment library](../../docs/adr/0006-prompt-fragment-libr
 - `src/index.ts`: merges the collections into a single `FRAGMENTS` registry plus
   `FRAGMENTS_BY_ID` and `getFragment(id)` for O(1) lookup during composition.
 
-A `PromptFragment` (shape defined in [`@cat-factory/contracts`](../contracts))
+A `PromptFragment` (shape defined in [`@cat-factory/contracts`](https://github.com/kibertoad/cat-factory/tree/main/backend/packages/contracts))
 carries an `id`, `version`, `title`, optional `category`, a `summary` (used by the
 relevance selector), the `body` (injected text), an optional condensed `brief`
 (see below), and an optional `appliesTo` hint (`blockTypes` / `agentKinds`).
@@ -32,7 +32,7 @@ relevance selector), the `body` (injected text), an optional condensed `brief`
 - When the optional library is enabled, this becomes the **built-in tier** of a
   three-tier merge (built-in ∪ account ∪ workspace); ids here can be shadowed or
   suppressed by higher tiers. See
-  [ADR 0006](../../docs/adr/0006-prompt-fragment-library.md).
+  [ADR 0006](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0006-prompt-fragment-library.md).
 
 ### Two-tier bodies: `body` and `brief`
 
@@ -61,7 +61,7 @@ by hand when a built-in grows past ~1,500 characters.
 ### Where a brief comes from at run time
 
 The built-in `brief` above is only the first of three answers. For a fragment resolved through
-the tenant library ([ADR 0006](../../docs/adr/0006-prompt-fragment-library.md)) the resolution
+the tenant library ([ADR 0006](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0006-prompt-fragment-library.md)) the resolution
 order is:
 
 1. **The winning tier's linked `brief`**: a built-in's, or the one a tenant authored on its own
@@ -75,44 +75,60 @@ order is:
    that path lands (no model wired, an unreadable store, a refused condensation).
 
 Design, decisions and gotchas:
-[`docs/initiatives/auto-generated-fragment-briefs.md`](../../../docs/initiatives/auto-generated-fragment-briefs.md).
+[`docs/initiatives/auto-generated-fragment-briefs.md`](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/auto-generated-fragment-briefs.md).
 
 ## Programmatic deployment seams (custom fragments + per-task-type defaults)
 
-Two **module-global** registration seams let a deployment (local **or** hosted) extend
-the fragment behaviour at startup: an import side effect from the deployment entry, run
-**once before** `start()` / `startLocal()`, mirroring `registerAgentKind`. No fork, no
+A deployment (local **or** hosted) extends the fragment behaviour through the app-owned
+`PromptFragmentRegistry` (kernel), injected BY REFERENCE into the facade it builds. No fork, no
 rebuild, no per-workspace UI.
 
-- **Add custom fragments to the universal pool**: `registerPromptFragment(fragment)` /
-  `registerPromptFragments(fragments)`. Every `GET /prompt-fragments` catalog read and
-  every run-time body lookup then sees them; re-registering an id overrides the built-in
-  of that id. (`universalFragments()` is the merged built-in ∪ registered pool.)
+> **This replaced two MODULE GLOBALS** (`registerPromptFragment` and
+> `registerTaskTypeDefaultFragments`), and the reason is worth stating because it is invisible from
+> inside this repo. Their correctness depended on every reader resolving the same physical copy of
+> this package. A `workspace:*` dependency publishes as an EXACT version, so a consumer floating the
+> range onto a newer patch gets TWO copies: the registration lands in one, the server reads the
+> other, and every task of the deployment's operation is seeded with ids that fold nothing. The only
+> signal was one boot warning, which is also the warning a typo produces.
+
+- **Build the registry**: `promptFragmentRegistryWithBuiltins()` (this package) news one carrying
+  the shipped catalog and its built-in per-type defaults; `defaultPromptFragmentRegistry()` (kernel)
+  news an EMPTY one, which is how a deployment says it wants only its own standards. The built-ins
+  install through the registry's ordinary public methods, so the platform exercises a consumer's own
+  seam on every boot and it cannot rot for consumers only.
+- **Add custom fragments to the universal pool**: `registry.register(fragment)` /
+  `registry.registerAll(fragments)`. Every `GET /prompt-fragments` catalog read and every run-time
+  body lookup then sees them; re-registering an id REPLACES the entry of that id, so a deployment
+  refines a shipped standard in place.
 - **Mark fragments as the default for a BUILT-IN task type**:
-  `registerTaskTypeDefaultFragments(taskType, fragmentIds)`. Every **new** task of that
-  type (`document`, `review`, `feature`, …) is then seeded with those fragments onto its
-  own `fragmentIds` at creation (unioned with the built-in defaults and whatever it
-  inherits from its service). The board resolves a new task's seed set through
-  `defaultFragmentIdsForTaskType(taskType)`; the only built-in per-type default is the
-  document writing-style set (`DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS`), which registered
-  ids augment rather than replace. Seeding is server-side and authoritative: it applies
-  even for tasks created via the public API with no create-form picker.
+  `registry.registerTaskTypeDefaults(taskType, fragmentIds)`. Every **new** task of that type
+  (`document`, `review`, `feature`, …) is then seeded with those fragments onto its own
+  `fragmentIds` at creation, beside whatever it inherits from its service. Seeding is server-side
+  and authoritative: it applies even for tasks created via the public API with no create-form picker.
+
+  **Registering a type REPLACES its built-in set rather than unioning with it.** The module-global
+  seam unioned silently, which meant a deployment could not remove a shipped default however it
+  wrote the call. Spread `DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS` into your own list to keep both,
+  which says so in the code.
 
   **A deployment's OWN (namespaced) task type does not use this seam.** It declares
-  `defaultFragmentIds` on its own registration instead, where boot validation can see the
-  ids and warn on one the code pool does not resolve; this module-global exists for the
-  built-in types, which have no descriptor to carry them. That declaration is one third of
-  a **reusable operation**: see
-  [`backend/docs/reusable-operations.md`](../../docs/reusable-operations.md).
+  `defaultFragmentIds` (and `conditionalFragmentIds`, for standing context that depends on the
+  answers a case supplies) on its own registration, where boot validation can see the ids and warn
+  on one the code pool does not resolve. That declaration is one third of a **reusable operation**:
+  see [`backend/docs/reusable-operations.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/reusable-operations.md).
+
+- **A code-registered fragment may NOT carry a `documentRef`.** Every code registration lands on the
+  `builtin` tier, whose live resolution needs a connection workspace a deployment-wide registration
+  cannot name, so boot REFUSES it (`fragment_document_ref_unsupported`) rather than carrying it,
+  rendering it as live in the library UI, and ignoring it at run time (which is what it did).
+  Register the body inline, or create the fragment at the ACCOUNT tier with a fetch-via workspace.
 
 ```ts
 // deployment entry, before start()/startLocal()
-import {
-  registerPromptFragments,
-  registerTaskTypeDefaultFragments,
-} from '@cat-factory/prompt-fragments'
+import { promptFragmentRegistryWithBuiltins } from '@cat-factory/prompt-fragments'
 
-registerPromptFragments([
+const promptFragmentRegistry = promptFragmentRegistryWithBuiltins()
+promptFragmentRegistry.registerAll([
   {
     id: 'org.review-checklist',
     version: '1.0.0',
@@ -122,9 +138,18 @@ registerPromptFragments([
   },
 ])
 // every new REVIEW task starts with this guidance
-registerTaskTypeDefaultFragments('review', ['org.review-checklist'])
+promptFragmentRegistry.registerTaskTypeDefaults('review', ['org.review-checklist'])
+
+// …and the SAME instance goes into the facade, which is the whole point.
+start({ promptFragmentRegistry /* …the rest */ })
 ```
 
+**In MOTHERSHIP mode the pool is read from the mothership**, not from the node's own registry: the
+standards are org state, and a node one build behind would otherwise fold different guidance than
+the deployment registered. A failed read THROWS rather than answering with an empty pool, because
+"the mothership is unreachable" and "this deployment registers no standards" are the same value and
+opposite facts. Boot warns and names any fragments registered on a mothership-mode node.
+
 ## Adding a collection
 
 1. Create `src/collections/<topic>.ts` and export an array of `PromptFragment`.

package/dist/index.d.ts

@@ -1,27 +1,39 @@
 import type { PromptFragment } from '@cat-factory/contracts';
+import { PromptFragmentRegistry } from '@cat-factory/kernel';
 export type { PromptFragment } from '@cat-factory/contracts';
 export declare const FRAGMENTS: PromptFragment[];
 export { styleFragments, DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS } from './collections/style.js';
-export { registerTaskTypeDefaultFragments, clearRegisteredTaskTypeDefaultFragments, defaultFragmentIdsForTaskType, } from './task-type-defaults.js';
+export { BUILTIN_TASK_TYPE_DEFAULTS } from './task-type-defaults.js';
 export { MIGRATION_FRAGMENT_IDS, migrationFragmentIdsFor } from './collections/migration.js';
 export { DESIGN_CONTEXT_FRAGMENT_ID, withDesignContextFragment } from './collections/design.js';
 /** Fragments keyed by id for O(1) lookup during prompt composition. */
 export declare const FRAGMENTS_BY_ID: ReadonlyMap<string, PromptFragment>;
-/** Register a custom prompt fragment into the universal pool. Re-registering an id replaces it. */
-export declare function registerPromptFragment(fragment: PromptFragment): void;
-/** Register several custom prompt fragments at once. */
-export declare function registerPromptFragments(fragments: Iterable<PromptFragment>): void;
-/** Drop all registered fragments. Intended for tests that exercise registration. */
-export declare function clearRegisteredPromptFragments(): void;
 /**
- * The universal fragment pool: the built-in catalog plus any deployment-registered
- * fragments, with a registered id shadowing the built-in of the same id. This is what
- * the catalog endpoint serves and what a service's fragment selection is drawn from.
+ * A {@link PromptFragmentRegistry} carrying the SHIPPED catalog and its built-in per-task-type
+ * default sets. Each facade's composition root news one, and a deployment registers its own
+ * standards onto the same instance by reference.
+ *
+ * The built-ins install through the registry's ordinary public methods rather than being baked in,
+ * which is the `defaultGateRegistry()` ⇄ `@cat-factory/gates` shape: the platform exercises the
+ * consumer's own seam on every boot, so it cannot rot for consumers only. Registration order is
+ * what makes a deployment's re-registration of a shipped id an override, so the built-ins go first.
+ *
+ * This replaced two module globals (`registerPromptFragment`'s map and
+ * `registerTaskTypeDefaultFragments`') whose correctness depended on every reader resolving the
+ * same physical copy of this package. A `workspace:*` dependency publishes as an EXACT version, so
+ * a consumer floating the range onto a newer patch got two copies: the registration landed in one,
+ * the server read the other, and every task of the deployment's operation was seeded with ids that
+ * folded nothing. Injection by reference makes that unrepresentable.
  */
-export declare function universalFragments(): PromptFragment[];
+export declare function promptFragmentRegistryWithBuiltins(): PromptFragmentRegistry;
 /**
- * Resolve a fragment by id, or `undefined` if no such fragment exists. Checks the
- * deployment-registered fragments first (override-by-id) then the built-in catalog.
+ * Resolve a fragment from the SHIPPED catalog by id, or `undefined`.
+ *
+ * Strictly the built-ins: a deployment's own fragments live on the injected registry, and the
+ * paths still calling this are the ones with no registry in hand (a prompt composed outside a
+ * container, a test harness). That narrowing is deliberate rather than a leftover. Before it,
+ * this function silently answered from a module global that a second copy of the package would
+ * have left empty, which is the whole failure the registry removes.
  */
 export declare function getFragment(id: string): PromptFragment | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAiB5D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,eAAO,MAAM,SAAS,EAAE,cAAc,EAOrC,CAAA;AAKD,OAAO,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAI5F,OAAO,EACL,gCAAgC,EAChC,uCAAuC,EACvC,6BAA6B,GAC9B,MAAM,yBAAyB,CAAA;AAKhC,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAI5F,OAAO,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAE/F,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAE/D,CAAA;AAYD,mGAAmG;AACnG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAErE;AAED,wDAAwD;AACxD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,IAAI,CAEjF;AAED,oFAAoF;AACpF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,EAAE,CAMrD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAElE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,wBAAwB,CAAA;AACtE,OAAO,EAAE,sBAAsB,EAAiC,MAAM,qBAAqB,CAAA;AAkB3F,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,eAAO,MAAM,SAAS,EAAE,cAAc,EAOrC,CAAA;AAKD,OAAO,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAG5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA;AAKpE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAI5F,OAAO,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAE/F,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAE/D,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kCAAkC,IAAI,sBAAsB,CAO3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAElE"}

package/dist/index.js

@@ -1,3 +1,5 @@
+import { PromptFragmentRegistry, defaultPromptFragmentRegistry } from '@cat-factory/kernel';
+import { BUILTIN_TASK_TYPE_DEFAULTS } from './task-type-defaults.js';
 import { acceptanceFragments } from './collections/acceptance.js';
 import { designFragments } from './collections/design.js';
 import { migrationFragments } from './collections/migration.js';
@@ -16,10 +18,9 @@ export const FRAGMENTS = [
 // board service seeding a new document task's fragments, the docs-refresh preset building its
 // `styleFragments` form options) draws on the same source of truth the catalog is built from.
 export { styleFragments, DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS } from './collections/style.js';
-// The per-task-type default-fragments seam: a deployment registers the fragments every new task
-// of a given type (documentation/review/…) starts with; the board service resolves a new task's
-// seed set through `defaultFragmentIdsForTaskType`.
-export { registerTaskTypeDefaultFragments, clearRegisteredTaskTypeDefaultFragments, defaultFragmentIdsForTaskType, } from './task-type-defaults.js';
+// The built-in per-task-type default sets, installed onto a registry by
+// `promptFragmentRegistryWithBuiltins` below.
+export { BUILTIN_TASK_TYPE_DEFAULTS } from './task-type-defaults.js';
 // Re-export the migration fragment ids so the `preset_tech_migration` preset draws its default
 // fragment set from the same source of truth the catalog is built from: `MIGRATION_FRAGMENT_IDS`
 // (T8's descriptor `defaultFragmentIds`) + `migrationFragmentIdsFor` (T7's `seedMigrationPlan`,
@@ -31,48 +32,42 @@ export { MIGRATION_FRAGMENT_IDS, migrationFragmentIdsFor } from './collections/m
 export { DESIGN_CONTEXT_FRAGMENT_ID, withDesignContextFragment } from './collections/design.js';
 /** Fragments keyed by id for O(1) lookup during prompt composition. */
 export const FRAGMENTS_BY_ID = new Map(FRAGMENTS.map((fragment) => [fragment.id, fragment]));
-// Installation-level extension point for the universal fragment pool, mirroring the
-// custom-agent (`registerAgentKind`) and model-provider registry seams. A deployment —
-// e.g. a proprietary org package — adds extra best-practice fragments once at startup
-// (an import side effect); every `getFragment` lookup and the `GET /prompt-fragments`
-// catalog then see them, so a service's fragment selection can draw on them without the
-// core packages knowing they exist. Registering an id that already exists in the
-// built-in catalog overrides it (later registration wins), so a deployment can refine a
-// shipped fragment's body in place.
-const registered = new Map();
-/** Register a custom prompt fragment into the universal pool. Re-registering an id replaces it. */
-export function registerPromptFragment(fragment) {
-    registered.set(fragment.id, fragment);
-}
-/** Register several custom prompt fragments at once. */
-export function registerPromptFragments(fragments) {
-    for (const fragment of fragments)
-        registerPromptFragment(fragment);
-}
-/** Drop all registered fragments. Intended for tests that exercise registration. */
-export function clearRegisteredPromptFragments() {
-    registered.clear();
-}
 /**
- * The universal fragment pool: the built-in catalog plus any deployment-registered
- * fragments, with a registered id shadowing the built-in of the same id. This is what
- * the catalog endpoint serves and what a service's fragment selection is drawn from.
+ * A {@link PromptFragmentRegistry} carrying the SHIPPED catalog and its built-in per-task-type
+ * default sets. Each facade's composition root news one, and a deployment registers its own
+ * standards onto the same instance by reference.
+ *
+ * The built-ins install through the registry's ordinary public methods rather than being baked in,
+ * which is the `defaultGateRegistry()` ⇄ `@cat-factory/gates` shape: the platform exercises the
+ * consumer's own seam on every boot, so it cannot rot for consumers only. Registration order is
+ * what makes a deployment's re-registration of a shipped id an override, so the built-ins go first.
+ *
+ * This replaced two module globals (`registerPromptFragment`'s map and
+ * `registerTaskTypeDefaultFragments`') whose correctness depended on every reader resolving the
+ * same physical copy of this package. A `workspace:*` dependency publishes as an EXACT version, so
+ * a consumer floating the range onto a newer patch got two copies: the registration landed in one,
+ * the server read the other, and every task of the deployment's operation was seeded with ids that
+ * folded nothing. Injection by reference makes that unrepresentable.
  */
-export function universalFragments() {
-    if (registered.size === 0)
-        return [...FRAGMENTS];
-    const byId = new Map();
-    for (const fragment of FRAGMENTS)
-        byId.set(fragment.id, fragment);
-    for (const fragment of registered.values())
-        byId.set(fragment.id, fragment);
-    return [...byId.values()];
+export function promptFragmentRegistryWithBuiltins() {
+    const registry = defaultPromptFragmentRegistry();
+    registry.registerAll(FRAGMENTS);
+    for (const [taskType, ids] of Object.entries(BUILTIN_TASK_TYPE_DEFAULTS)) {
+        if (ids)
+            registry.registerTaskTypeDefaults(taskType, ids);
+    }
+    return registry;
 }
 /**
- * Resolve a fragment by id, or `undefined` if no such fragment exists. Checks the
- * deployment-registered fragments first (override-by-id) then the built-in catalog.
+ * Resolve a fragment from the SHIPPED catalog by id, or `undefined`.
+ *
+ * Strictly the built-ins: a deployment's own fragments live on the injected registry, and the
+ * paths still calling this are the ones with no registry in hand (a prompt composed outside a
+ * container, a test harness). That narrowing is deliberate rather than a leftover. Before it,
+ * this function silently answered from a module global that a second copy of the package would
+ * have left empty, which is the whole failure the registry removes.
  */
 export function getFragment(id) {
-    return registered.get(id) ?? FRAGMENTS_BY_ID.get(id);
+    return FRAGMENTS_BY_ID.get(id);
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAavD,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC,GAAG,aAAa;IAChB,GAAG,cAAc;IACjB,GAAG,mBAAmB;IACtB,GAAG,eAAe;IAClB,GAAG,cAAc;IACjB,GAAG,kBAAkB;CACtB,CAAA;AAED,+FAA+F;AAC/F,8FAA8F;AAC9F,8FAA8F;AAC9F,OAAO,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAC5F,gGAAgG;AAChG,gGAAgG;AAChG,oDAAoD;AACpD,OAAO,EACL,gCAAgC,EAChC,uCAAuC,EACvC,6BAA6B,GAC9B,MAAM,yBAAyB,CAAA;AAChC,+FAA+F;AAC/F,iGAAiG;AACjG,gGAAgG;AAChG,qFAAqF;AACrF,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAC5F,qGAAqG;AACrG,sGAAsG;AACtG,iEAAiE;AACjE,OAAO,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAE/F,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAwC,IAAI,GAAG,CACzE,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CACrD,CAAA;AAED,oFAAoF;AACpF,uFAAuF;AACvF,sFAAsF;AACtF,sFAAsF;AACtF,wFAAwF;AACxF,iFAAiF;AACjF,wFAAwF;AACxF,oCAAoC;AACpC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAA;AAEpD,mGAAmG;AACnG,MAAM,UAAU,sBAAsB,CAAC,QAAwB;IAC7D,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;AACvC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,uBAAuB,CAAC,SAAmC;IACzE,KAAK,MAAM,QAAQ,IAAI,SAAS;QAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAA;AACpE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,8BAA8B;IAC5C,UAAU,CAAC,KAAK,EAAE,CAAA;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAA;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0B,CAAA;IAC9C,KAAK,MAAM,QAAQ,IAAI,SAAS;QAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;IACjE,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;IAC3E,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AACtD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAA;AAC3F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAavD,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC,GAAG,aAAa;IAChB,GAAG,cAAc;IACjB,GAAG,mBAAmB;IACtB,GAAG,eAAe;IAClB,GAAG,cAAc;IACjB,GAAG,kBAAkB;CACtB,CAAA;AAED,+FAA+F;AAC/F,8FAA8F;AAC9F,8FAA8F;AAC9F,OAAO,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAC5F,wEAAwE;AACxE,8CAA8C;AAC9C,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA;AACpE,+FAA+F;AAC/F,iGAAiG;AACjG,gGAAgG;AAChG,qFAAqF;AACrF,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAC5F,qGAAqG;AACrG,sGAAsG;AACtG,iEAAiE;AACjE,OAAO,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAE/F,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAwC,IAAI,GAAG,CACzE,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CACrD,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kCAAkC;IAChD,MAAM,QAAQ,GAAG,6BAA6B,EAAE,CAAA;IAChD,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;IAC/B,KAAK,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAAE,CAAC;QACzE,IAAI,GAAG;YAAE,QAAQ,CAAC,wBAAwB,CAAC,QAAoB,EAAE,GAAG,CAAC,CAAA;IACvE,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAChC,CAAC"}

package/dist/task-type-defaults.d.ts

@@ -1,21 +1,4 @@
 import type { TaskType } from '@cat-factory/contracts';
-/**
- * Register the default fragment ids for a task type. Every NEW task of `taskType` created
- * on the board then starts with these fragments (unioned with the built-in defaults and
- * whatever the task inherits). Re-registering the same task type REPLACES its registered
- * set. The ids reference the universal fragment pool (built-in catalog plus any
- * `registerPromptFragment`-registered fragments); an unresolvable id is simply skipped
- * when bodies are composed at run time, so registration order with `registerPromptFragment`
- * does not matter.
- */
-export declare function registerTaskTypeDefaultFragments(taskType: TaskType, fragmentIds: Iterable<string>): void;
-/** Drop all registered per-task-type defaults. Intended for tests that exercise registration. */
-export declare function clearRegisteredTaskTypeDefaultFragments(): void;
-/**
- * The effective default fragment ids a new task of `taskType` is seeded with: the built-in
- * defaults for the type (the document writing-style set, else none) unioned with any
- * deployment-registered ids, deduped and order-stable (built-ins first). Empty when the
- * type has no built-in and nothing is registered.
- */
-export declare function defaultFragmentIdsForTaskType(taskType: TaskType): string[];
+/** The built-in per-task-type defaults shipped with the catalog (today: document only). */
+export declare const BUILTIN_TASK_TYPE_DEFAULTS: Partial<Record<TaskType, readonly string[]>>;
 //# sourceMappingURL=task-type-defaults.d.ts.map

package/dist/task-type-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-type-defaults.d.ts","sourceRoot":"","sources":["../src/task-type-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAkCtD;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC5B,IAAI,CAEN;AAED,iGAAiG;AACjG,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAK1E"}
+{"version":3,"file":"task-type-defaults.d.ts","sourceRoot":"","sources":["../src/task-type-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AA0BtD,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC,CAEnF,CAAA"}

package/dist/task-type-defaults.js

@@ -1,59 +1,28 @@
 import { DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS } from './collections/style.js';
 // ---------------------------------------------------------------------------
-// Per-TASK-TYPE default best-practice fragment ids.
+// The BUILT-IN per-task-type default best-practice fragment ids.
 //
-// The fragments a NEW task of a given type (`document`, `review`, `feature`, …) is
-// pre-seeded with at creation. The board service unions these onto a task's
-// `fragmentIds` when it is created (alongside whatever the task inherits from its
-// service or an explicit create-form pick), so every new task of that type starts with
-// the guidance without any per-block or per-workspace configuration.
+// The fragments a NEW task of a given type (`document`, `review`, `feature`, …) is pre-seeded
+// with at creation. The board service unions these onto a task's `fragmentIds` when it is created
+// (alongside whatever the task inherits from its service or an explicit create-form pick), so
+// every new task of that type starts with the guidance without any per-block or per-workspace
+// configuration.
 //
-// This is the deployment-level PROGRAMMATIC seam — a module-global registry mirroring
-// `registerPromptFragment` and `registerDocTemplate`. A deployment adds its own custom
-// fragments via `registerPromptFragments(...)` (universal pool) and then declares them as
-// the default for a task type via `registerTaskTypeDefaultFragments('review', [...ids])`,
-// so e.g. every new documentation or review task starts with that org's guidance. The
-// call happens once at startup (an import side effect in the deployment entry, before
-// `start()` / `startLocal()`), exactly like `registerPromptFragments`.
+// A DEPLOYMENT declares its own through the app-owned registry
+// (`promptFragmentRegistry.registerTaskTypeDefaults('review', [...ids])`), which is what this
+// module used to hold as a second module global beside the fragment pool, with the identical
+// two-physical-copies hazard. The built-in sets below are installed onto that same registry by
+// `promptFragmentRegistryWithBuiltins()`, through the same public method, so the platform and a
+// consumer exercise one code path.
 //
-// The shipped `document` writing-style defaults (`DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS`)
-// are the ONLY built-in per-type default; they are always applied for a document task and
-// union with any registered ids, so registering document defaults augments (never wipes)
-// the writing-style guidance. When nothing is registered, behaviour is unchanged.
+// Registering a task type REPLACES its set rather than unioning with these, which is a behaviour
+// change from the module-global seam and the honest one: a deployment's declaration is its final
+// answer, and the previous silent union meant a deployment could not remove a shipped default
+// however it wrote the call. A deployment that wants the writing-style set alongside its own
+// spreads `DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS` into its own list, which says so in the code.
 // ---------------------------------------------------------------------------
 /** The built-in per-task-type defaults shipped with the catalog (today: document only). */
-const BUILTIN_TASK_TYPE_DEFAULTS = {
+export const BUILTIN_TASK_TYPE_DEFAULTS = {
     document: DEFAULT_DOCUMENT_STYLE_FRAGMENT_IDS,
 };
-/** Deployment-registered per-task-type default fragment ids (added to the built-ins). */
-const registered = new Map();
-/**
- * Register the default fragment ids for a task type. Every NEW task of `taskType` created
- * on the board then starts with these fragments (unioned with the built-in defaults and
- * whatever the task inherits). Re-registering the same task type REPLACES its registered
- * set. The ids reference the universal fragment pool (built-in catalog plus any
- * `registerPromptFragment`-registered fragments); an unresolvable id is simply skipped
- * when bodies are composed at run time, so registration order with `registerPromptFragment`
- * does not matter.
- */
-export function registerTaskTypeDefaultFragments(taskType, fragmentIds) {
-    registered.set(taskType, [...fragmentIds]);
-}
-/** Drop all registered per-task-type defaults. Intended for tests that exercise registration. */
-export function clearRegisteredTaskTypeDefaultFragments() {
-    registered.clear();
-}
-/**
- * The effective default fragment ids a new task of `taskType` is seeded with: the built-in
- * defaults for the type (the document writing-style set, else none) unioned with any
- * deployment-registered ids, deduped and order-stable (built-ins first). Empty when the
- * type has no built-in and nothing is registered.
- */
-export function defaultFragmentIdsForTaskType(taskType) {
-    const builtin = BUILTIN_TASK_TYPE_DEFAULTS[taskType] ?? [];
-    const custom = registered.get(taskType) ?? [];
-    if (custom.length === 0)
-        return [...builtin];
-    return [...new Set([...builtin, ...custom])];
-}
 //# sourceMappingURL=task-type-defaults.js.map

package/dist/task-type-defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-type-defaults.js","sourceRoot":"","sources":["../src/task-type-defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAE5E,8EAA8E;AAC9E,oDAAoD;AACpD,EAAE;AACF,mFAAmF;AACnF,4EAA4E;AAC5E,kFAAkF;AAClF,uFAAuF;AACvF,qEAAqE;AACrE,EAAE;AACF,sFAAsF;AACtF,uFAAuF;AACvF,0FAA0F;AAC1F,0FAA0F;AAC1F,sFAAsF;AACtF,sFAAsF;AACtF,uEAAuE;AACvE,EAAE;AACF,wFAAwF;AACxF,0FAA0F;AAC1F,yFAAyF;AACzF,kFAAkF;AAClF,8EAA8E;AAE9E,2FAA2F;AAC3F,MAAM,0BAA0B,GAAiD;IAC/E,QAAQ,EAAE,mCAAmC;CAC9C,CAAA;AAED,yFAAyF;AACzF,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAA;AAEzD;;;;;;;;GAQG;AACH,MAAM,UAAU,gCAAgC,CAC9C,QAAkB,EAClB,WAA6B;IAE7B,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,uCAAuC;IACrD,UAAU,CAAC,KAAK,EAAE,CAAA;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAkB;IAC9D,MAAM,OAAO,GAAG,0BAA0B,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAA;IAC5C,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;AAC9C,CAAC"}
+{"version":3,"file":"task-type-defaults.js","sourceRoot":"","sources":["../src/task-type-defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAE5E,8EAA8E;AAC9E,iEAAiE;AACjE,EAAE;AACF,8FAA8F;AAC9F,kGAAkG;AAClG,8FAA8F;AAC9F,8FAA8F;AAC9F,iBAAiB;AACjB,EAAE;AACF,+DAA+D;AAC/D,8FAA8F;AAC9F,6FAA6F;AAC7F,+FAA+F;AAC/F,gGAAgG;AAChG,mCAAmC;AACnC,EAAE;AACF,iGAAiG;AACjG,iGAAiG;AACjG,8FAA8F;AAC9F,6FAA6F;AAC7F,8FAA8F;AAC9F,8EAA8E;AAE9E,2FAA2F;AAC3F,MAAM,CAAC,MAAM,0BAA0B,GAAiD;IACtF,QAAQ,EAAE,mCAAmC;CAC9C,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/prompt-fragments",
-  "version": "0.16.0",
+  "version": "1.0.1",
   "description": "Curated, versioned best-practice prompt fragments injected into agent system prompts.",
   "repository": {
     "type": "git",
@@ -24,7 +24,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@cat-factory/contracts": "0.253.0"
+    "@cat-factory/contracts": "0.255.0",
+    "@cat-factory/kernel": "0.254.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",