@cat-factory/agents 0.44.1 → 0.45.0

package/dist/presets/tech-migration/phases.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The five migration phase ids, keyed by a semantic name so prose/prompts reference a phase by
+ * meaning rather than by a bare string. The string values are the ids matched VERBATIM against the
+ * planned phases at ingest.
+ */
+export declare const MIGRATION_PHASE_IDS: {
+    /** Enumerate every directly + transitively affected touchpoint; commit the inventory. */
+    readonly blastZone: 'migration-blast-zone';
+    /** Pin observable behaviour over the blast zone; close with the confidence case. */
+    readonly coverage: 'migration-coverage';
+    /** Decide the backwards-compatibility degree and design the migration / cutover path. */
+    readonly transitionDesign: 'migration-transition-design';
+    /** Execute the swap per the approved design, behaviour suite green throughout. */
+    readonly delivery: 'migration-delivery';
+    /** Prove parity on the new target, flip defaults, remove the old path. */
+    readonly verifyDecommission: 'migration-verify-decommission';
+};
+/** One of the five canonical migration phase ids. */
+export type MigrationPhaseId = (typeof MIGRATION_PHASE_IDS)[keyof typeof MIGRATION_PHASE_IDS];
+/**
+ * The phase ids in methodology order — the order the plan (and the preset's `phaseTemplate`) must
+ * present them. Consumers that iterate phases (the template builder, the E2E) read this so the
+ * order lives in one place too.
+ */
+export declare const MIGRATION_PHASE_ID_ORDER: readonly MigrationPhaseId[];
+//# sourceMappingURL=phases.d.ts.map

package/dist/presets/tech-migration/phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../../src/presets/tech-migration/phases.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,yFAAyF;aACzF,SAAS,EAAE,sBAAsB;IACjC,oFAAoF;aACpF,QAAQ,EAAE,oBAAoB;IAC9B,yFAAyF;aACzF,gBAAgB,EAAE,6BAA6B;IAC/C,kFAAkF;aAClF,QAAQ,EAAE,oBAAoB;IAC9B,0EAA0E;aAC1E,kBAAkB,EAAE,+BAA+B;CAC3C,CAAA;AAEV,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAA;AAE7F;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EAM/D,CAAA"}

package/dist/presets/tech-migration/phases.js

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// The canonical PHASE IDS of the `preset_tech_migration` initiative preset.
+//
+// A technological migration always runs the same five-phase methodology (blast zone →
+// coverage → transition → delivery → decommission), regardless of the specific from/to
+// technologies. Those phase ids are a CONTRACT shared by four consumers:
+//   - the preset's declarative `phaseTemplate` on the wire descriptor (T8),
+//   - the methodology prompt pack's planner steering (`prompt-additions.ts`, T5),
+//   - the plan post-processor `seedMigrationPlan` (T7), and
+//   - the migration E2E (T10).
+// Defined ONCE here so no consumer retypes a phase id. This matters because the generic
+// ingest normalizer matches a planned phase to a template phase by its `id` VERBATIM, so a
+// single typo would silently break the shape enforcement (a "missing required phase" reject
+// or a disallowed extra) rather than fail loudly. See
+// `docs/initiatives/tech-migration-preset-and-mssql-postgres-pilot.md`.
+// ---------------------------------------------------------------------------
+/**
+ * The five migration phase ids, keyed by a semantic name so prose/prompts reference a phase by
+ * meaning rather than by a bare string. The string values are the ids matched VERBATIM against the
+ * planned phases at ingest.
+ */
+export const MIGRATION_PHASE_IDS = {
+    /** Enumerate every directly + transitively affected touchpoint; commit the inventory. */
+    blastZone: 'migration-blast-zone',
+    /** Pin observable behaviour over the blast zone; close with the confidence case. */
+    coverage: 'migration-coverage',
+    /** Decide the backwards-compatibility degree and design the migration / cutover path. */
+    transitionDesign: 'migration-transition-design',
+    /** Execute the swap per the approved design, behaviour suite green throughout. */
+    delivery: 'migration-delivery',
+    /** Prove parity on the new target, flip defaults, remove the old path. */
+    verifyDecommission: 'migration-verify-decommission',
+};
+/**
+ * The phase ids in methodology order — the order the plan (and the preset's `phaseTemplate`) must
+ * present them. Consumers that iterate phases (the template builder, the E2E) read this so the
+ * order lives in one place too.
+ */
+export const MIGRATION_PHASE_ID_ORDER = [
+    MIGRATION_PHASE_IDS.blastZone,
+    MIGRATION_PHASE_IDS.coverage,
+    MIGRATION_PHASE_IDS.transitionDesign,
+    MIGRATION_PHASE_IDS.delivery,
+    MIGRATION_PHASE_IDS.verifyDecommission,
+];
+//# sourceMappingURL=phases.js.map

package/dist/presets/tech-migration/phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.js","sourceRoot":"","sources":["../../../src/presets/tech-migration/phases.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,EAAE;AACF,sFAAsF;AACtF,uFAAuF;AACvF,yEAAyE;AACzE,4EAA4E;AAC5E,kFAAkF;AAClF,4DAA4D;AAC5D,+BAA+B;AAC/B,wFAAwF;AACxF,2FAA2F;AAC3F,4FAA4F;AAC5F,sDAAsD;AACtD,wEAAwE;AACxE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,yFAAyF;IACzF,SAAS,EAAE,sBAAsB;IACjC,oFAAoF;IACpF,QAAQ,EAAE,oBAAoB;IAC9B,yFAAyF;IACzF,gBAAgB,EAAE,6BAA6B;IAC/C,kFAAkF;IAClF,QAAQ,EAAE,oBAAoB;IAC9B,0EAA0E;IAC1E,kBAAkB,EAAE,+BAA+B;CAC3C,CAAA;AAKV;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgC;IACnE,mBAAmB,CAAC,SAAS;IAC7B,mBAAmB,CAAC,QAAQ;IAC5B,mBAAmB,CAAC,gBAAgB;IACpC,mBAAmB,CAAC,QAAQ;IAC5B,mBAAmB,CAAC,kBAAkB;CACvC,CAAA"}

package/dist/presets/tech-migration/prompt-additions.d.ts

@@ -0,0 +1,31 @@
+import type { AgentKind } from '@cat-factory/kernel';
+/**
+ * Interviewer steering: the migration form already froze the enumerable facts (which migration,
+ * from/to tech, stored-proc policy, compat posture, coverage bar, docs dir), so the interview digs
+ * into the fuzzy, judgment-dependent facts a form cannot capture — the ones that actually change how
+ * the migration must be planned. Complements the generic T3 "build on the seeded form" line with the
+ * migration-specific probing agenda.
+ */
+export declare const MIGRATION_INTERVIEWER_PROMPT_ADDITION: string;
+/**
+ * Analyst steering: the analysis must produce the migration's BLAST ZONE (the touchpoint inventory
+ * the planner turns into the phase-1 report item and the provisional phase-2 coverage items), not a
+ * generic architecture overview — and it must chase the TRANSITIVE reach where migrations silently
+ * break, recording the existing test coverage per touchpoint (the phase-2 hardening target and the
+ * confidence case's grounding).
+ */
+export declare const MIGRATION_ANALYST_PROMPT_ADDITION: string;
+/**
+ * Planner steering: author each phase's items to the migration briefs, using the canonical phase
+ * ids VERBATIM, enforcing coverage-before-delivery and the single-writer artifact discipline. Pairs
+ * with the wire `phaseTemplate` (which dictates the phase SHAPE) — this is the per-phase ITEM
+ * methodology `seedMigrationPlan` (T7) then decorates and hardens.
+ */
+export declare const MIGRATION_PLANNER_PROMPT_ADDITION: string;
+/**
+ * The migration preset's `promptAdditions` map — the per-planning-kind steering the registration
+ * (T8) spreads onto its {@link InitiativePresetRegistration}. Keyed by the kernel agent-kind
+ * constants so a kind rename can't silently orphan an entry.
+ */
+export declare const MIGRATION_PROMPT_ADDITIONS: Partial<Record<AgentKind, string>>;
+//# sourceMappingURL=prompt-additions.d.ts.map

package/dist/presets/tech-migration/prompt-additions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-additions.d.ts","sourceRoot":"","sources":["../../../src/presets/tech-migration/prompt-additions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AA+BpD;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,QAqBtC,CAAA;AAEZ;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,QAwBlC,CAAA;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,QA4BlC,CAAA;AAEZ;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAIzE,CAAA"}

package/dist/presets/tech-migration/prompt-additions.js

@@ -0,0 +1,131 @@
+import { INITIATIVE_ANALYST_AGENT_KIND, INITIATIVE_INTERVIEWER_AGENT_KIND, INITIATIVE_PLANNER_AGENT_KIND, } from '@cat-factory/kernel';
+import { MIGRATION_PHASE_IDS } from './phases.js';
+// ---------------------------------------------------------------------------
+// The methodology PROMPT PACK for the `preset_tech_migration` initiative preset — the per-planning-
+// kind steering text the preset registers as its `promptAdditions` (T8). This is the DEEP,
+// code-side methodology the parent's off-the-wire rule keeps OUT of the descriptor: the wire
+// `phaseTemplate` carries only short phase ids/titles/goals (rendered as the "required plan
+// shape"), while these constants carry HOW each planning kind reasons about a migration.
+//
+// How each constant reaches its agent:
+//   - `initiative-analyst` / `initiative-planner` run through the engine, so `AgentContextBuilder`
+//     resolves `promptAdditions[kind]` onto `context.initiative.preset.promptAddition` and the
+//     server's `initiativeContextLines` renders it under `## Initiative preset: <label>` (the
+//     planner also gets the `phaseTemplate` fold). This seam already existed (T1 / parent S3).
+//   - `initiative-interviewer` is the INLINE `InitiativeInterviewService`, which folds
+//     `promptAdditions[INITIATIVE_INTERVIEWER_AGENT_KIND]` into its own prompt — a generic seam this
+//     slice completes, since the migration preset is the first FULL-interview preset to need it
+//     (docs-refresh is `interview: 'skip'`).
+//
+// Everything is DATA: the preset registration (T8) spreads `MIGRATION_PROMPT_ADDITIONS`, and the
+// loop never branches on a preset id. The planner brief references the canonical phase ids from
+// `phases.ts` so they are never retyped. See
+// `docs/initiatives/tech-migration-preset-and-mssql-postgres-pilot.md`.
+// ---------------------------------------------------------------------------
+/**
+ * Interviewer steering: the migration form already froze the enumerable facts (which migration,
+ * from/to tech, stored-proc policy, compat posture, coverage bar, docs dir), so the interview digs
+ * into the fuzzy, judgment-dependent facts a form cannot capture — the ones that actually change how
+ * the migration must be planned. Complements the generic T3 "build on the seeded form" line with the
+ * migration-specific probing agenda.
+ */
+export const MIGRATION_INTERVIEWER_PROMPT_ADDITION = [
+    'This initiative is a TECHNOLOGICAL MIGRATION — swapping a load-bearing technology (a database ' +
+        'engine, a framework major, a runtime, a core library) behind a behaviour-preservation safety ' +
+        'net. The intake form has already captured the enumerable facts (which migration, the from/to ' +
+        'technology, the stored-procedure policy, the compatibility posture, the coverage bar, the docs ' +
+        'location). Treat every one of those seeded answers as SETTLED — never re-ask what the form covers.',
+    '',
+    'Spend your questions on the fuzzy, judgment-dependent facts a form cannot capture, because they ' +
+        'shape the plan:',
+    '- Downtime / cutover tolerance: is a maintenance window acceptable, or must the switch be online?',
+    '- Data-migration constraints: data volume, backfill and rehearsal needs, point-in-time ' +
+        'correctness, and any records that cannot be recreated.',
+    '- Compatibility posture, when the form left it unset: how long must the old and new technologies ' +
+        'run side by side (big-bang vs dual-run vs adapter layer), and what forces that choice?',
+    '- The observable behaviour that must NOT change, and where silent drift is most likely.',
+    '- Rollback expectations, and who owns the decision to abort a cutover mid-flight.',
+    '- Operational reach: scheduled jobs, ops tooling, monitoring and CI that touch the technology ' +
+        'being swapped.',
+    '',
+    'Keep each batch small and high-leverage. Converge as soon as the migration methodology (blast ' +
+        'zone → coverage → transition → delivery → decommission) can be planned unambiguously.',
+].join('\n');
+/**
+ * Analyst steering: the analysis must produce the migration's BLAST ZONE (the touchpoint inventory
+ * the planner turns into the phase-1 report item and the provisional phase-2 coverage items), not a
+ * generic architecture overview — and it must chase the TRANSITIVE reach where migrations silently
+ * break, recording the existing test coverage per touchpoint (the phase-2 hardening target and the
+ * confidence case's grounding).
+ */
+export const MIGRATION_ANALYST_PROMPT_ADDITION = [
+    'This initiative is a TECHNOLOGICAL MIGRATION. Your analysis must produce the migration BLAST ' +
+        'ZONE — the touchpoint inventory the planner turns into the phase-1 report item and the ' +
+        'provisional phase-2 coverage items — not a generic architecture overview.',
+    '',
+    'Enumerate every touchpoint of the technology being swapped:',
+    '- DIRECT touchpoints: every site that uses the technology directly — queries, driver/ORM calls, ' +
+        'schema objects, vendor-specific idioms, connection/pool/timeout config.',
+    '- TRANSITIVE touchpoints: chase the reach BEYOND the direct sites — callers of those callers, ' +
+        'code that consumes the RESULT SHAPES or error contracts of the swapped calls, scheduled jobs, ' +
+        'ops and migration tooling, monitoring, and CI provisioning. Transitive reach is where ' +
+        'migrations silently break; do not stop at the obvious layer.',
+    '',
+    'For EACH touchpoint record: what it is, whether it is direct or transitive, a risk assessment, ' +
+        'and — critically — WHICH TESTS COVER IT TODAY (or "none"). That "covered by which tests today" ' +
+        'column is exactly what phase 2 hardens and the confidence case audits, so ground it in real ' +
+        'test files, not guesses.',
+    '',
+    'Call out the behaviour-preservation traps specific to THIS swap — the edge cases that differ ' +
+        'silently between the two technologies (NULL vs empty string, precision/rounding, collation and ' +
+        'comparison semantics, pagination, identity/sequence exposure) — and any set-based operation ' +
+        'that must NOT become an app-side per-row loop. Ground every touchpoint in real file/directory ' +
+        'references, and produce this provisional inventory IN your analysis so the planner can author ' +
+        'phase 1 and the provisional phase-2 items directly from it.',
+].join('\n');
+/**
+ * Planner steering: author each phase's items to the migration briefs, using the canonical phase
+ * ids VERBATIM, enforcing coverage-before-delivery and the single-writer artifact discipline. Pairs
+ * with the wire `phaseTemplate` (which dictates the phase SHAPE) — this is the per-phase ITEM
+ * methodology `seedMigrationPlan` (T7) then decorates and hardens.
+ */
+export const MIGRATION_PLANNER_PROMPT_ADDITION = [
+    'This initiative is a TECHNOLOGICAL MIGRATION, planned around the five fixed phases in the ' +
+        "required plan shape above. Author each phase's items to the briefs below, using each phase " +
+        '`id` VERBATIM. Coverage comes BEFORE delivery: never schedule a delivery item before the ' +
+        'behaviour it changes is characterised and green on the current technology.',
+    '',
+    `- \`${MIGRATION_PHASE_IDS.blastZone}\`: ONE report item (a SINGLE writer) that verifies and ` +
+        "deepens the analyst's provisional inventory against the real code and commits it as a " +
+        'Markdown document. Do not split the inventory across parallel writers.',
+    `- \`${MIGRATION_PHASE_IDS.coverage}\`: one coverage item per area of the provisional inventory ` +
+        '(keep it to roughly eight; group finer-grained rows by area), each writing characterization ' +
+        'tests at a seam ABOVE the layer being swapped so they survive the swap. CLOSE the phase with a ' +
+        'single confidence-case item that depends on every other phase-2 item and is human-gated: it ' +
+        'sweeps coverage and commits the evidence-backed proof (per-touchpoint named tests, gaps and ' +
+        'waivers justified against the coverage bar, risk mitigations, safety nets) a human audits ' +
+        'before delivery.',
+    `- \`${MIGRATION_PHASE_IDS.transitionDesign}\`: one or two human-gated design items that decide ` +
+        'the backwards-compatibility posture and design the migration / cutover path — schema ' +
+        'translation, transaction-boundary ownership, the error-contract mapping, the per-object ' +
+        'replacement strategy, and the data-migration path plus rehearsal — committing the design ' +
+        'document. Each set-based operation replaced with application code needs an explicit note that ' +
+        'it stays set-based (never an app-side per-row loop).',
+    `- \`${MIGRATION_PHASE_IDS.delivery}\`: delivery items batched by design area, each depending on ` +
+        'the enabling schema / infrastructure item, executed per the approved design with the behaviour ' +
+        'suite green throughout.',
+    `- \`${MIGRATION_PHASE_IDS.verifyDecommission}\`: a parity-verification item (the behaviour suite ` +
+        'green on the new target, made primary), the CI / default flip, and removal of the old path and ' +
+        'its dependencies per the chosen compatibility posture.',
+].join('\n');
+/**
+ * The migration preset's `promptAdditions` map — the per-planning-kind steering the registration
+ * (T8) spreads onto its {@link InitiativePresetRegistration}. Keyed by the kernel agent-kind
+ * constants so a kind rename can't silently orphan an entry.
+ */
+export const MIGRATION_PROMPT_ADDITIONS = {
+    [INITIATIVE_INTERVIEWER_AGENT_KIND]: MIGRATION_INTERVIEWER_PROMPT_ADDITION,
+    [INITIATIVE_ANALYST_AGENT_KIND]: MIGRATION_ANALYST_PROMPT_ADDITION,
+    [INITIATIVE_PLANNER_AGENT_KIND]: MIGRATION_PLANNER_PROMPT_ADDITION,
+};
+//# sourceMappingURL=prompt-additions.js.map

package/dist/presets/tech-migration/prompt-additions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-additions.js","sourceRoot":"","sources":["../../../src/presets/tech-migration/prompt-additions.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD,8EAA8E;AAC9E,oGAAoG;AACpG,2FAA2F;AAC3F,6FAA6F;AAC7F,4FAA4F;AAC5F,yFAAyF;AACzF,EAAE;AACF,uCAAuC;AACvC,mGAAmG;AACnG,+FAA+F;AAC/F,8FAA8F;AAC9F,+FAA+F;AAC/F,uFAAuF;AACvF,qGAAqG;AACrG,gGAAgG;AAChG,6CAA6C;AAC7C,EAAE;AACF,iGAAiG;AACjG,gGAAgG;AAChG,6CAA6C;AAC7C,wEAAwE;AACxE,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG;IACnD,gGAAgG;QAC9F,+FAA+F;QAC/F,+FAA+F;QAC/F,iGAAiG;QACjG,oGAAoG;IACtG,EAAE;IACF,kGAAkG;QAChG,iBAAiB;IACnB,mGAAmG;IACnG,yFAAyF;QACvF,wDAAwD;IAC1D,mGAAmG;QACjG,wFAAwF;IAC1F,yFAAyF;IACzF,mFAAmF;IACnF,gGAAgG;QAC9F,gBAAgB;IAClB,EAAE;IACF,gGAAgG;QAC9F,uFAAuF;CAC1F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,+FAA+F;QAC7F,yFAAyF;QACzF,2EAA2E;IAC7E,EAAE;IACF,6DAA6D;IAC7D,kGAAkG;QAChG,yEAAyE;IAC3E,gGAAgG;QAC9F,gGAAgG;QAChG,wFAAwF;QACxF,8DAA8D;IAChE,EAAE;IACF,iGAAiG;QAC/F,iGAAiG;QACjG,8FAA8F;QAC9F,0BAA0B;IAC5B,EAAE;IACF,+FAA+F;QAC7F,iGAAiG;QACjG,8FAA8F;QAC9F,gGAAgG;QAChG,gGAAgG;QAChG,6DAA6D;CAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,4FAA4F;QAC1F,6FAA6F;QAC7F,2FAA2F;QAC3F,4EAA4E;IAC9E,EAAE;IACF,OAAO,mBAAmB,CAAC,SAAS,0DAA0D;QAC5F,wFAAwF;QACxF,wEAAwE;IAC1E,OAAO,mBAAmB,CAAC,QAAQ,8DAA8D;QAC/F,8FAA8F;QAC9F,iGAAiG;QACjG,8FAA8F;QAC9F,8FAA8F;QAC9F,4FAA4F;QAC5F,kBAAkB;IACpB,OAAO,mBAAmB,CAAC,gBAAgB,sDAAsD;QAC/F,uFAAuF;QACvF,0FAA0F;QAC1F,2FAA2F;QAC3F,gGAAgG;QAChG,sDAAsD;IACxD,OAAO,mBAAmB,CAAC,QAAQ,+DAA+D;QAChG,iGAAiG;QACjG,yBAAyB;IAC3B,OAAO,mBAAmB,CAAC,kBAAkB,sDAAsD;QACjG,iGAAiG;QACjG,wDAAwD;CAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC5E,CAAC,iCAAiC,CAAC,EAAE,qCAAqC;IAC1E,CAAC,6BAA6B,CAAC,EAAE,iCAAiC;IAClE,CAAC,6BAA6B,CAAC,EAAE,iCAAiC;CACnE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/agents",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "description": "Agent catalog, routing, prompts and fragment library for the Agent Architecture Board.",
   "repository": {
     "type": "git",