ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/19-7-llm-writability-validation-tests.md

@@ -1,280 +0,0 @@
-# Story 19.7: LLM-Writability Contract Validation and Integration Tests
-
-Status: ready-for-dev
-
-## Story
-
-As a **Chief Architect**,
-I want the knowledge graph JSON format validated against the LLM-writability contract and covered by integration tests,
-so that we can verify that any LLM can extend the graph by copying existing patterns, and that the additive-only semantics are enforced.
-
-## Acceptance Criteria
-
-1. **Given** a `knowledge-graph.json` file with one existing node and one existing edge
-   **When** an LLM is instructed to add a new node and a new edge by copying the existing patterns (no external schema provided)
-   **Then** the resulting JSON is valid and passes `emitToGraph()` ingestion without errors
-   **And** the existing node and edge are preserved unchanged (NFR40)
-
-2. **Given** `emitToGraph()` is called with a node id that already exists in `nodes`
-   **When** the function completes
-   **Then** `nodes` contains exactly one entry with that id (no duplicate)
-   **And** the original node's fields are unchanged (except `title` which may be updated)
-
-3. **Given** `emitToGraph()` is called with an edge `(from, to, type)` triple that already exists
-   **When** the function completes
-   **Then** `edges` contains exactly one entry with that triple (no duplicate)
-   **And** the original edge's provenance (created_by, agent) is unchanged
-
-4. **Given** a graph with 500 nodes and 1000 edges
-   **When** `emitToGraph()` adds one new node and one new edge
-   **Then** the operation completes in under 1 second
-
-5. **Given** the full emission sequence is run (all 7 skills emit in order)
-   **When** the resulting `knowledge-graph.json` is inspected
-   **Then** all emitted nodes are present
-   **And** all emitted edges are present with correct provenance
-   **And** `meta.file_count`, `meta.node_count`, `meta.edge_count` are accurate
-
-## Tasks / Subtasks
-
-### Task 1: Set up test directory structure (AC: 1–5)
-
-Story 19.7 integration tests follow the existing Node.js test runner pattern. Epic 7 (Test Suite) is on hold, so these tests use the existing Node.js test runner directly (no Jest, no Vitest — plain Node.js `assert` and test runner, or whichever lightweight pattern is already in use in the repo).
-
-- [ ] 1.1 Create directory `tests/knowledge-graph/`
-- [ ] 1.2 Create `tests/knowledge-graph/fixtures/` for test fixture files
-- [ ] 1.3 Check existing test files in the repo (e.g., `tests/` root) to identify the test runner pattern in use — do NOT introduce a new test framework; replicate the existing pattern exactly
-
-### Task 2: Test — additive-only semantics (AC: 1, 2, 3)
-
-- [ ] 2.1 Create `tests/knowledge-graph/emit.test.js`:
-  - **Test: first call creates valid structure**
-    - Use a temp directory; call `emitToGraph(tmpDir, minimalPayload)`
-    - Verify file is created, has `meta`, `files`, `nodes`, `edges` sections
-    - Verify `meta.node_count` and `meta.edge_count` match array lengths
-
-  - **Test: duplicate node is rejected (AC: 2)**
-    - Seed graph with node `{ id: "prd#test", ... }`
-    - Call `emitToGraph()` again with the same node id but different title
-    - Verify `nodes` has exactly 1 entry with that id
-    - Verify title is updated (expected behavior per Story 19.1: title updates are allowed)
-
-  - **Test: duplicate edge is rejected (AC: 3)**
-    - Seed graph with edge `{ from: "prd#a", to: "prd#b", type: "implements", created_by: "original", ... }`
-    - Call `emitToGraph()` again with same `(from, to, type)` but different `created_by`
-    - Verify `edges` has exactly 1 entry with that triple
-    - Verify `created_by` is unchanged (provenance preserved — only `created_at`/`agent` can update)
-
-  - **Test: existing entries preserved (AC: 1, 2, 3 — NFR40)**
-    - Seed graph with 3 nodes and 2 edges
-    - Call `emitToGraph()` with 2 new nodes and 1 new edge
-    - Verify total: 5 nodes, 3 edges
-    - Verify all original entries are byte-identical to their initial values
-
-### Task 3: Test — LLM-writability contract (AC: 1)
-
-- [ ] 3.1 Create `tests/knowledge-graph/fixtures/llm-seed.json` — a minimal valid `knowledge-graph.json` with exactly 1 node and 1 edge (following the exact schema structure from `architecture.md` Decision P3-1)
-- [ ] 3.2 Create `tests/knowledge-graph/llm-writability.test.js`:
-  - **Test: copy-pattern extension produces valid JSON**
-    - Load `fixtures/llm-seed.json`
-    - Programmatically "extend" it by copying the pattern (add a new node entry and new edge entry following the exact same field structure)
-    - Write the extended JSON back to a temp file
-    - Call `emitToGraph(tmpDir, emptyEmission)` on the extended file — verify no errors thrown
-    - Verify total node/edge counts are correct
-  - **Test: valid structure can be round-tripped**
-    - Read `fixtures/llm-seed.json`, parse, serialize as `JSON.stringify(graph, null, 2)`, parse again — verify no data loss
-
-### Task 4: Test — performance (AC: 4)
-
-- [ ] 4.1 Add to `tests/knowledge-graph/emit.test.js`:
-  - **Test: large graph performance**
-    - Generate a fixture graph with 500 nodes and 1000 edges programmatically (use a helper function, not a fixture file — 500-node JSON fixture would be large)
-    - Write to temp dir
-    - Measure time of `emitToGraph()` adding 1 node and 1 edge
-    - Assert elapsed < 1000ms (using `Date.now()` before/after)
-
-### Task 5: Test — full emission sequence (AC: 5)
-
-- [ ] 5.1 Create `tests/knowledge-graph/sequence.test.js`:
-  - **Test: sequential emission produces correct final graph**
-    - Simulate the 7-skill emission sequence using `emitToGraph()` directly (no actual skills invoked — just the payloads each skill would emit)
-    - Use representative payloads:
-      1. PRD seeding: 3 PRD nodes, 0 edges
-      2. Architecture: 2 arch nodes, 2 `implements` edges to PRD nodes
-      3. Epics: 2 epic nodes, 2 `derives-from` edges + 1 `informed-by` edge
-      4. Story: 1 story node, 1 `traces-to` edge + 1 `informed-by` edge
-      5. Validate-prd: 1 validation node, 1 `validates` edge
-      6. Dev-story: 1 `refines` edge (story → arch)
-      7. Sprint-planning: 1 sprint node, 1 `derives-from` edge
-    - Verify final graph:
-      - `meta.node_count == 9` (3+2+2+1+1)
-      - `meta.edge_count == 8` (2+3+2+1+1) (approximately — adjust to actual test payload)
-      - All emitted nodes present
-      - All emitted edges present with correct provenance fields
-
-### Task 6: Test — VSCode detection (AC — Story 19.5)
-
-- [ ] 6.1 Create `tests/knowledge-graph/vscode-detection.test.js`:
-  - **Test: VSCODE_PID env var triggers VSCode path**
-    - Set `process.env.VSCODE_PID = "12345"` before running detection logic
-    - Verify detection returns `true`
-    - Restore `process.env` after test
-  - **Test: TERM_PROGRAM=vscode triggers VSCode path**
-    - Set `process.env.TERM_PROGRAM = "vscode"`
-    - Verify detection returns `true`
-  - **Test: neither env var set returns false**
-    - Ensure both env vars are unset; verify detection returns `false`
-  - Extract detection logic from `lib/bmad-extension/skills/open-graph/SKILL.md` into a testable helper function `lib/bmad-extension/skills/open-graph/detect-env.js`
-
-## Dev Notes
-
-### CRITICAL: Test Framework — Use Existing Pattern
-
-Epic 7 (Test Suite Foundation) is on hold. Do NOT introduce Jest, Vitest, Mocha, or any new test framework. Check if any test files already exist in `tests/` and replicate their exact pattern.
-
-If no test infrastructure exists: use Node.js built-in `node:test` module (available from Node.js 18+) and `node:assert`. This requires no npm installation.
-
-Pattern to check first:
-- Look for any `*.test.js` files in the repo
-- Look for `test` script in `package.json`
-
-### Prerequisite: All of Stories 19.1–19.6 Must Be Complete
-
-This story validates the complete Epic 19 implementation. It depends on:
-- `lib/knowledge-graph/emit.js` (Story 19.1)
-- `lib/bmad-extension/skills/open-graph/` (Stories 19.5, 19.6)
-
-### Test Directory Convention
-
-Tests live in `tests/knowledge-graph/` following the expectation from the Epic 19 cross-epic notes. Temp directories for all file I/O in tests:
-```javascript
-import { mkdtempSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-
-let tmpDir;
-setup(() => { tmpDir = mkdtempSync(join(tmpdir(), 'kg-test-')); });
-teardown(() => { rmSync(tmpDir, { recursive: true, force: true }); });
-```
-
-### LLM-Writability Fixture (Task 3)
-
-The fixture `tests/knowledge-graph/fixtures/llm-seed.json` must be a minimal but complete example:
-```json
-{
-  "meta": {
-    "schema_version": "1.0",
-    "project": "test-project",
-    "generated_at": "2026-04-07T10:00:00Z",
-    "last_updated": "2026-04-07T10:00:00Z",
-    "file_count": 1,
-    "node_count": 1,
-    "edge_count": 1
-  },
-  "files": {
-    "prd": {
-      "pointer": "_bmad-output/planning-artifacts/prd.md",
-      "title": "Product Requirements Document",
-      "pointer_type": "relative_path"
-    }
-  },
-  "nodes": [
-    {
-      "id": "prd#functional-requirements",
-      "file": "prd",
-      "anchor": "functional-requirements",
-      "title": "Functional Requirements",
-      "type": "prd"
-    }
-  ],
-  "edges": [
-    {
-      "from": "arch#decision-test",
-      "to": "prd#functional-requirements",
-      "type": "implements",
-      "label": "implements requirement",
-      "created_by": "test-user",
-      "agent": "test-agent",
-      "created_at": "2026-04-07T10:00:00Z"
-    }
-  ]
-}
-```
-
-This fixture is intentionally minimal so that an LLM reading it has exactly one example to copy.
-
-### Performance Test Helper (Task 4)
-
-Generate the 500-node / 1000-edge test graph programmatically:
-```javascript
-function generateLargeGraph(nodeCount, edgeCount) {
-  const nodes = Array.from({ length: nodeCount }, (_, i) => ({
-    id: `prd#node-${i}`, file: 'prd', anchor: `node-${i}`, title: `Node ${i}`, type: 'prd'
-  }));
-  const edges = Array.from({ length: edgeCount }, (_, i) => ({
-    from: `prd#node-${i % nodeCount}`,
-    to: `prd#node-${(i + 1) % nodeCount}`,
-    type: 'implements',
-    label: `edge ${i}`,
-    created_by: 'test', agent: 'test', created_at: new Date().toISOString()
-  }));
-  // ... build and write graph to temp dir
-}
-```
-
-### `detect-env.js` Extraction (Task 6)
-
-The VSCode detection logic from SKILL.md should be extracted to a testable Node.js module:
-```javascript
-// lib/bmad-extension/skills/open-graph/detect-env.js
-function detectVSCode() {
-  return process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
-}
-module.exports = { detectVSCode };
-```
-
-This makes it importable by tests without executing the `execSync` open command.
-
-### File Structure Created by This Story
-
-```
-tests/
-└── knowledge-graph/
-    ├── fixtures/
-    │   └── llm-seed.json              ← NEW (LLM-writability test fixture)
-    ├── emit.test.js                   ← NEW (additive semantics + performance tests)
-    ├── llm-writability.test.js        ← NEW (copy-pattern extension tests)
-    ├── sequence.test.js               ← NEW (full emission sequence test)
-    └── vscode-detection.test.js       ← NEW (env var detection tests)
-
-lib/bmad-extension/skills/open-graph/
-└── detect-env.js                      ← NEW (extracted detection logic for testability)
-```
-
-### Project Structure Notes
-
-- No SKILL.md files modified by this story.
-- No new skills registered.
-- The `detect-env.js` extraction from Story 19.5's SKILL.md is a minor refactor to enable testability.
-- If no `tests/` directory exists, create it. Add a `test` script to `package.json` if one does not exist: `"test": "node --test tests/**/*.test.js"` (Node.js 18+ built-in runner).
-
-### References
-
-- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md` — `emitToGraph()` behavior under test
-- Architecture LLM-writability contract: `_bmad-output/planning-artifacts/architecture.md#llm-writability-contract-nfr39`
-- Architecture additive-only semantics: `_bmad-output/planning-artifacts/architecture.md#nfr40-additive-only-emission`
-- Epics cross-epic notes on testing: `_bmad-output/planning-artifacts/epics.md#epic-19--cross-epic-notes`
-- NFRs: NFR39 (LLM-writability), NFR40 (additive-only)
-- FR: FR152 (no duplicates, provenance preservation)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-_to be filled by dev agent_
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List

package/_bmad-output/implementation-artifacts/21-1-install-time-profile-prompt.md

@@ -1,181 +0,0 @@
-# Story 21.1: Install-Time Profile Prompt and Persistence
-
-Status: done
-
-## Story
-
-As an **engineer running `npx ma-agents install`**,
-I want the installer to ask whether this is an on-prem / air-gapped install once and remember my answer,
-So that on-prem-specific guardrails activate without me having to remember a CLI flag, and I am not re-prompted on subsequent installs.
-
-## Acceptance Criteria
-
-1. A new module `lib/profile.js` exists exposing exactly three functions: `getProfile(projectRoot)`, `setProfile(projectRoot, value)`, `resolveProfile({ persisted, yesMode })`. No other public API.
-2. `getProfile(projectRoot)` reads `.ma-agents.json` at project root and returns the value of the top-level `"profile"` field, or `undefined` if the file or field is absent. It does not throw on missing file.
-3. `setProfile(projectRoot, value)` writes `"profile": <value>` to the top-level of `.ma-agents.json`, preserving all existing fields (`manifestVersion`, `agent`, `agents`, `scope`, `skills`). When the file does not exist, it is created via the existing `ensureManifest` path so the standard schema is initialized.
-4. `setProfile` accepts only the values `"on-prem"` and `"standard"`. Any other value throws an `Error` naming the bad value.
-5. `resolveProfile({ persisted, yesMode })` returns the effective profile per this precedence: (a) `persisted` if set; (b) `"standard"` if `yesMode === true`; (c) `null` (caller must prompt). It does not perform any I/O.
-6. The interactive wizard in `bin/cli.js` shows a single `prompts({ type: 'select' })` question after agent selection (Step 2) and before repository-layout selection (Step 2.5), with message `Is this an on-prem / air-gapped install using a local LLM (e.g. Nemotron)?` and choices `Yes — apply local-LLM guardrails (recommended for non-Claude models)` (value `on-prem`) and `No  — standard install (Claude on web, Anthropic API, etc.)` (value `standard`). Default initial selection is the `No` (standard) row.
-7. The wizard prompt is shown only when `resolveProfile()` returns `null`. When a value is already persisted or `--yes` is passed, no prompt appears and the resolved value is logged once using one of the canonical formats: `Using profile: <value> (from .ma-agents.json)`, `Using profile: standard (from --yes default)`, or `Using profile: <value> (from wizard)`. These formats are pinned in architecture.md P3-3 and referenced by tests verbatim.
-8. After the wizard prompt is answered (or after resolver returns a non-null value), `setProfile` is called with the resolved value before any agent installation runs — guaranteeing the profile is persisted even if a later install step fails.
-9. Direct install command (`npx ma-agents install <skill> --agent <agent>`) respects `--yes`: `--yes` without a persisted value defaults to `standard` and persists; absence of `--yes` and no persisted value triggers the same prompt as the wizard when stdin is a TTY, and defaults silently to `standard` (same as `--yes`) when stdin is not a TTY.
-10. CI/CD path: `npx ma-agents install --yes` with no persisted profile writes `"profile": "standard"` to `.ma-agents.json` and proceeds without prompting (NFR45).
-11. Re-running install with a persisted profile does NOT re-prompt and does NOT change the persisted value (NFR45).
-12. The existing `manifestVersion` value is bumped from `1.1.0` to `1.2.0` in `ensureManifest` to reflect the new `"profile"` field. Manifests at `1.1.0` (no `profile`) are read without error — the `"profile"` field is treated as optional and absent equals `undefined`. Writing to an existing `1.1.0` manifest via `setProfile` MIGRATES `manifestVersion` to `1.2.0` (the `profile` field is only valid under the 1.2.0 schema — carrying it on a 1.1.0 manifest would be schema drift). The migration is logged once per install: `Migrated .ma-agents.json manifestVersion 1.1.0 → 1.2.0`. Fresh manifests bootstrapped via `ensureManifest` start at `1.2.0` directly. NOTE: This migration behavior is a Step 2 follow-up code change (tracked separately); this AC documents the intended end state.
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create `lib/profile.js` (AC: #1–#5)
-  - [x] 1.1 Create `lib/profile.js` with `'use strict'` and the three exports
-  - [x] 1.2 Implement `getProfile` reading via existing `readManifest`-style path; return `undefined` if file or field missing
-  - [x] 1.3 Implement `setProfile` with value validation; reuse `ensureManifest` to bootstrap the file when absent; preserve all other fields on write
-  - [x] 1.4 Implement `resolveProfile` as a pure function (no I/O) per the precedence in AC #5
-
-- [x] Task 2: Add wizard prompt (AC: #6, #7, #8)
-  - [x] 2.1 In the wizard flow (cli.js:655–900), after Step 2 (agent selection, ~line 829) and before Step 2.5 (repository layout), call `resolveProfile({ persisted: getProfile(projectRoot), yesMode: yesFlag })`
-  - [x] 2.2 If the result is `null`, run the `prompts({ type: 'select' })` question per AC #6 (initial index = 1 for the "No" row)
-  - [x] 2.3 Log `Using profile: <value> (from <source>)` exactly once
-  - [x] 2.4 Call `setProfile(projectRoot, resolvedValue)` BEFORE any agent install step (AC #8)
-
-- [x] Task 3: Direct install path parity (AC: #9, #10)
-  - [x] 3.1 Apply the same `resolveProfile` + prompt fallback logic in the direct-install path of `handleInstall`
-  - [x] 3.2 When stdin is not a TTY and resolver returns `null`, silently default to `standard` (same as `--yes`) and persist — do not abort
-
-- [x] Task 4: Manifest version bump + back-compat (AC: #12)
-  - [x] 4.1 In `ensureManifest` (installer.js:64-70), change `manifestVersion: '1.1.0'` to `'1.2.0'`
-  - [x] 4.2 Existing files at `1.1.0` continue to load — do NOT migrate or rewrite the version on read; only writes through `setProfile` / `ensureManifest` produce `1.2.0`. A `1.1.0` file with no `profile` field is valid; `getProfile` returns `undefined`
-
-- [x] Task 5: Unit tests in `test/profile.test.js` (covers all ACs)
-  - [x] 5.1 `getProfile` returns `undefined` when `.ma-agents.json` does not exist (AC #2)
-  - [x] 5.2 `getProfile` returns `undefined` when file exists but `profile` field is absent (AC #2, #12 back-compat)
-  - [x] 5.3 `getProfile` returns the persisted value when present (AC #2)
-  - [x] 5.4 `setProfile` creates the file with the standard schema when absent (AC #3)
-  - [x] 5.5 `setProfile` preserves existing fields (`manifestVersion`, `agent`, `agents`, `scope`, `skills`) when updating (AC #3)
-  - [x] 5.6 `setProfile` throws on invalid value with the bad value in the error message (AC #4)
-  - [x] 5.7 `resolveProfile` precedence — persisted wins over yes-default (AC #5)
-  - [x] 5.8 `resolveProfile` precedence — yes-default returns `standard` only when no persisted (AC #5)
-  - [x] 5.9 `resolveProfile` returns `null` when nothing is set and `yesMode === false` (AC #5)
-  - [x] 5.10 `resolveProfile` does not perform I/O (AC #5 — verified by spying on `fs`)
-  - [x] 5.11 Round-trip: `setProfile('on-prem')` then `getProfile()` returns `'on-prem'` (AC #2/#3)
-  - [x] 5.12 Re-running `setProfile` with same value is idempotent (file content byte-identical except potentially `installedAt` if other fields update — but profile field stable)
-
-- [ ] Task 6: Integration test in `test/onprem-injection.test.js` (deferred to Story 21.9 — list as TODO here, do not implement)
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P3-3** (Local-LLM / On-Prem Agent Tuning Profile) — this story implements the `lib/profile.js` module and the install-time prompt. Stories 21.2–21.7 consume `getProfile()` to gate content. Stories 21.8 (docs) and 21.9 (tests) close the epic.
-- **NFR45** (CI/CD compatibility) — `--yes` defaults to `standard`; non-TTY direct installs silently default to `standard`; persisted answer is not re-prompted.
-- **NFR44** (profile isolation) — `setProfile` is the only mutator; no other code path writes the `profile` field. Standard profile installs must produce no on-prem-specific output (verified in Story 21.9).
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `lib/profile.js` | CREATE — `getProfile`, `setProfile`, `resolveProfile` |
-| `lib/installer.js` | MODIFY — `manifestVersion` bump 1.1.0 → 1.2.0 in `ensureManifest` (line ~64-70) |
-| `bin/cli.js` | MODIFY — wizard prompt insertion after Step 2 (line ~829); direct-install path resolution in `handleInstall` |
-| `test/profile.test.js` | CREATE — unit tests per Task 6 |
-
-### Library and Pattern References
-
-- Prompts library: **`prompts`** (npm) — same as everywhere else in the wizard. Existing example to mirror: `lib/installer.js:625-631` (the repo-layout `select` prompt).
-- Manifest read/write: reuse `readManifest` / `writeManifest` / `ensureManifest` in `lib/installer.js:23-70`. Do not create a parallel JSON-IO path. `setProfile` may import these or, if circular-import risk exists, replicate the minimal write pattern (`fs.writeFileSync(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8')`).
-- Flag parsing site: `bin/cli.js:170-176`. No new flag is added — profile is resolved from persisted state or `--yes` default only.
-
-### Wizard Insertion Point
-
-Per the explore report, wizard step order is:
-- Step 0: Existing installation check (~668)
-- Step 1: Skill selection (~737)
-- Step 2: Agent selection (IDE + BMAD multiselects, ~776–804)
-- **Step 2.4 (NEW): Profile prompt** ← insert here
-- Step 2.5: Repository layout (~829)
-- Step 3: Installation scope (~832)
-
-Place the call so that the profile is resolved and persisted BEFORE repo-layout because future stories may want to gate layout-related guidance on profile (out of scope for this story, but the order is correct).
-
-### `.ma-agents.json` Example After This Story
-
-Standard profile, fresh install:
-
-```json
-{
-  "manifestVersion": "1.2.0",
-  "agent": "claude-code",
-  "agents": ["claude-code"],
-  "scope": "project",
-  "profile": "standard",
-  "skills": {}
-}
-```
-
-On-prem profile after install:
-
-```json
-{
-  "manifestVersion": "1.2.0",
-  "agent": "claude-code",
-  "agents": ["claude-code", "roo-code"],
-  "scope": "project",
-  "profile": "on-prem",
-  "skills": { "...": "..." }
-}
-```
-
-### Out of Scope for This Story
-
-- Per-tool template content (Stories 21.2–21.5)
-- On-prem layered guardrail content (Story 21.6)
-- BMAD persona phase prefix (Story 21.7)
-- vLLM deployment doc (Story 21.8)
-- Integration test asserting standard vs on-prem produces correct injection content (Story 21.9)
-
-This story is foundation only: prompt + persistence + read API. Downstream stories consume `getProfile(projectRoot)` and branch on its value.
-
-### Testing Standards
-
-Match the existing test layout in `test/` (mocha-style or node:test — verify by reading one existing test file first). Place `test/profile.test.js` next to `test/generate-project-context.test.js`. All tests must run as part of `npm test`. Use a temporary directory per test (e.g., `os.tmpdir()` + `fs.mkdtempSync`) to isolate `.ma-agents.json` reads/writes — never mutate the repo's own `.ma-agents.json`.
-
-### Epic 21 Cross-Story Context
-
-**Story 21.1 (this):** Profile prompt + `lib/profile.js` API + persistence. No template content yet.
-**Story 21.2:** Universal instruction-block expansion (consumes `getProfile` indirectly via installer composition function).
-**Stories 21.3–21.5:** Per-tool templates (`.roomodes`, `AGENTS.md`, `.clinerules`).
-**Story 21.6:** On-prem layered guardrails — first story that branches behavior on `profile === 'on-prem'`.
-**Story 21.7:** BMAD persona phase prefix in customize-loader.
-**Story 21.8:** vLLM reference doc + README on-prem section.
-**Story 21.9:** Tests covering NFR44, NFR46, NFR47 (integration-level).
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context) — bmad-dev-story + bmad-code-review flow.
-
-### Debug Log References
-- Initial `npm test` run hit a pre-existing `bmad-version-bump` failure in the worktree due to missing `node_modules/bmad-method/package.json`. Resolved by running `npm install` in the worktree; not related to this story's changes.
-- Self-review finding (Cynical Review layer): initial implementation used `installPath` (the custom skills install target) as the project root for `.ma-agents.json` in the wizard path, which is wrong — `.ma-agents.json` lives at `process.cwd()`, not the skills install dir. Corrected before opening the PR.
-
-### Completion Notes List
-- `lib/profile.js` exposes exactly the three required functions (`getProfile`, `setProfile`, `resolveProfile`). `resolveProfile` is pure — verified by fs-spy test (6.11).
-- `lib/installer.js`: bumped `MANIFEST_VERSION` from `1.1.0` → `1.2.0`; added `ensureManifest` to `module.exports` so `setProfile` can bootstrap fresh manifests without duplicating JSON-IO logic.
-- `bin/cli.js`: Both wizard and direct-install paths call `setProfile` BEFORE any agent install step (AC #8) and log `Using profile: <value> (from <source>)` exactly once. No CLI flag is introduced — profile is sourced from persisted `.ma-agents.json` or the `--yes` default.
-- Wizard insertion point is "Step 2.4" — after agent selection, before repo-layout (matches story spec). Direct-install path silently defaults to `standard` when stdin is not a TTY (mirrors `--yes`) rather than aborting.
-- Manifest back-compat: reads never migrate the version. A 1.1.0 file without `profile` reads as `undefined`; writing `setProfile` onto an existing 1.1.0 manifest adds the `profile` field while preserving the original `manifestVersion`. Fresh manifests created through `ensureManifest` are initialized at 1.2.0.
-- Task 6 (integration test) intentionally left unchecked — explicitly deferred to Story 21.9 per spec.
-
-### File List
-- CREATED: `lib/profile.js`
-- CREATED: `test/profile.test.js` (14 unit tests, all passing)
-- MODIFIED: `lib/installer.js` (manifest version bump; export `ensureManifest`)
-- MODIFIED: `bin/cli.js` (wizard Step 2.4 profile prompt; direct-install profile resolution with non-TTY standard default)
-- MODIFIED: `package.json` (added `test/profile.test.js` to npm test script)
-
-## Change Log
-- 2026-04-14: Story created (Epic 21, Story 21.1)
-- 2026-04-14: Story 21.1 implemented — `lib/profile.js` + install-time prompt + manifest 1.2.0 bump; status moved ready-for-dev → review.
-- 2026-04-13: Spec correction — `--profile=` CLI flag removed (never wanted); `resolveProfile` reduced to 2-arg `{ persisted, yesMode }`; direct-install non-TTY path now defaults to `standard` silently instead of aborting. AC count reduced 14 → 11.
-- 2026-04-14: Story delivered via PR #32 (feature/story-21-1-install-time-profile). Status → done. Dev Notes aligned with no-flag correction (removed stale `--profile=` references in Architecture Compliance, Source Tree Components, Library and Pattern References).
-- 2026-04-14: AC #12 clarified — `setProfile` on 1.1.0 manifest migrates to 1.2.0 (no schema drift). Migration implementation tracked as Step 2 follow-up (separate PR).
-- 2026-04-14: AC #7 log-string enum expanded to match canonical formats pinned in architecture.md P3-3 ("from wizard" source added).

package/_bmad-output/implementation-artifacts/21-10-profile-reconfigure.md

@@ -1,161 +0,0 @@
-# Story 21.10: Profile Reconfigure
-
-Status: Review
-
-## Story
-
-As an **engineer who needs to change a previously-persisted profile**,
-I want a `ma-agents reconfigure` subcommand that re-runs the profile prompt and re-stamps all profile-dependent artifacts,
-So that a CI-default `standard` profile or a mistaken interactive answer can be corrected without hand-editing `.ma-agents.json`.
-
-## Acceptance Criteria
-
-1. A new CLI subcommand `npx ma-agents reconfigure` exists. It accepts no positional arguments and the usual flags where relevant (`--yes`, scope flags if present — see AC #6 for `--yes` handling). Running it in a project without `.ma-agents.json` exits with a named error and a hint to run `install` first — it does NOT silently bootstrap a manifest, because reconfigure presumes a prior install.
-2. `reconfigure` shows the same profile-selection prompt Story 21.1's wizard shows, but with the currently-persisted value as the default highlighted option. The prompt text references the current value: `Current profile: <value>. Change to?`.
-3. After the user picks a value (or confirms the existing one), `reconfigure` writes the resolved value via `setProfile` (reusing `lib/profile.js` unchanged). Logging follows the canonical log-string formats pinned in architecture.md P3-3 — the source of the write is `wizard` for this command (matching the `(from wizard)` suffix used by the install wizard).
-4. If the newly-resolved profile equals the previously-persisted value, `reconfigure` reports `Profile unchanged: <value>. No re-stamp needed.` and exits 0 without touching any files.
-5. If the profile CHANGED, `reconfigure` re-stamps ALL profile-dependent artifacts:
-   - The instruction-block-injection files (`CLAUDE.md`, `.clinerules`, `.cline/clinerules.md`, `.roo/rules/00-ma-agents.md`, `AGENTS.md`)
-   - The `.roomodes` file (per-mode `customInstructions`)
-   - The BMAD customize-loader output (if Story 21.7 has landed — if it has not, this bullet is a no-op and the Task 3 subitems are skipped)
-   Implementation strategy: reuse the exact injection functions the installer uses; do NOT fork logic.
-6. `reconfigure` with `--yes` is explicitly rejected: the command exits nonzero with the message `--yes is not valid for reconfigure — this command is interactive by design to prevent accidental CI-triggered profile changes.` Rationale: Finding #5 is that CI quietly persists `standard`; we must not allow CI to silently flip profiles in either direction.
-7. Before re-stamping, `reconfigure` prints the list of files that will be modified and asks for a single yes/no confirmation: `The following files will be updated to match profile=<new>: [list]. Continue?`. This is in addition to the profile-selection prompt in AC #2 — two-step confirmation for destructive scope.
-8. `reconfigure` backs up each to-be-overwritten marker-block region to `<target>.backup-<ISO-timestamp>` before re-stamping. Same backup convention as Story 21.2 AC #8 — reuse if already implemented.
-9. `reconfigure` respects Story 21.3 AC #9 slug-stomp protection: if user-edited ma-agents-owned `.roomodes` slugs are detected, the command aborts with the same `RoomodesSlugDivergenceError` and instructs the user to either rename the slug or pass `--force-roomodes-overwrite`. `--force-roomodes-overwrite` IS honored by `reconfigure` (unlike `--yes`) because it is a deliberate, user-supplied override.
-10. `reconfigure` respects Story 21.5 AC #6 `.clinerules` dual-file drift detection: if the two Cline rule files (`.clinerules` and `.cline/clinerules.md`) have divergent marker-block content, the command aborts with `ClinerulesDualFileDriftError`. The user reconciles manually before retrying. No override flag is provided for this case.
-11. A new log event is appended to `.ma-agents.json::profileHistory` (new field, append-only, capped at 20 entries — oldest entries dropped first when the cap is reached): `{ date: <ISO>, from: <previous>, to: <new>, source: "reconfigure" }`. The field is created on first reconfigure; a missing field on read means no prior reconfigure event. Gives operators a forensic trail for "when did this project's profile last change, and from what?"
-
-## Tasks / Subtasks
-
-- [ ] Task 1: Register `reconfigure` subcommand in `bin/cli.js` (AC: #1, #6)
-  - [ ] 1.1 Add `reconfigure` case to the top-level command dispatcher
-  - [ ] 1.2 Reject `--yes` with the pinned error message per AC #6 (exit nonzero)
-  - [ ] 1.3 When `.ma-agents.json` is absent, exit with a named error and a hint to run `install` first (AC #1)
-  - [ ] 1.4 Route to the new `lib/reconfigure.js` orchestrator
-
-- [ ] Task 2: Create `lib/reconfigure.js` orchestrator (AC: #2, #3, #4, #7)
-  - [ ] 2.1 Load persisted profile via `getProfile()`; abort if absent (AC #1)
-  - [ ] 2.2 Show profile-selection prompt with persisted value as default (AC #2)
-  - [ ] 2.3 If resolved value equals persisted value, log `Profile unchanged: <value>. No re-stamp needed.` and exit 0 (AC #4)
-  - [ ] 2.4 Otherwise, compute the list of files that will be touched; print the list and ask the `Continue?` confirmation (AC #7)
-  - [ ] 2.5 Call `setProfile(projectRoot, newValue)` and log via the canonical `Using profile: <value> (from wizard)` format (AC #3)
-
-- [ ] Task 3: Re-stamp orchestration (AC: #5)
-  - [ ] 3.1 Reuse the injection helpers from `lib/installer.js` for the 5 instruction-block-injection files
-  - [ ] 3.2 Reuse the `.roomodes` merger from `lib/merge/roomodes.js` (Story 21.3) for `customInstructions`
-  - [ ] 3.3 If Story 21.7 has landed, invoke the BMAD customize-loader re-stamp; otherwise skip (documented as conditional)
-  - [ ] 3.4 Ensure zero duplication with installer stamping logic — do NOT fork
-
-- [ ] Task 4: Backup step (AC: #8)
-  - [ ] 4.1 Before each overwrite, capture the current marker-block region and write to `<target>.backup-<ISO-timestamp>`
-  - [ ] 4.2 Use UTC ISO format for the timestamp (stable across locales)
-  - [ ] 4.3 Reuse Story 21.2 backup helper if present; otherwise implement inline and note the refactor opportunity
-
-- [ ] Task 5: Slug-stomp protection integration (AC: #9)
-  - [ ] 5.1 Before touching `.roomodes`, run the Story 21.3 AC #9 slug-divergence check
-  - [ ] 5.2 On divergence, throw `RoomodesSlugDivergenceError` with a message instructing rename or `--force-roomodes-overwrite`
-  - [ ] 5.3 Honor `--force-roomodes-overwrite` when supplied — user-supplied override is allowed
-
-- [ ] Task 6: Clinerules dual-file drift detection (AC: #10)
-  - [ ] 6.1 Before touching Cline rule files, compare the marker-block content of `.clinerules` and `.cline/clinerules.md`
-  - [ ] 6.2 On divergence, throw `ClinerulesDualFileDriftError` with a message pointing the user at both files; no override flag
-
-- [ ] Task 7: `profileHistory` append (AC: #11)
-  - [ ] 7.1 After a successful re-stamp, append `{ date, from, to, source: "reconfigure" }` to `.ma-agents.json::profileHistory`
-  - [ ] 7.2 Create the field on first use; cap at 20 entries (drop oldest first)
-  - [ ] 7.3 Ensure the write goes through `setProfile` or an equivalent atomic write path (no parallel JSON-IO)
-
-- [ ] Task 8: Tests in `test/reconfigure.test.js` (covers all ACs)
-  - [ ] 8.1 `--yes` is rejected with pinned message and nonzero exit (AC #6)
-  - [ ] 8.2 Missing `.ma-agents.json` exits with named error (AC #1)
-  - [ ] 8.3 Same-value confirmation exits with `Profile unchanged:` and no file writes (AC #4)
-  - [ ] 8.4 Profile change from `standard` to `on-prem` re-stamps all injection files + `.roomodes` (AC #5)
-  - [ ] 8.5 Two-step confirmation — selecting "no" at the `Continue?` prompt aborts with zero file changes (AC #7)
-  - [ ] 8.6 Backup files created at `<target>.backup-<ISO-timestamp>` before each overwrite (AC #8)
-  - [ ] 8.7 Slug divergence raises `RoomodesSlugDivergenceError`; `--force-roomodes-overwrite` bypasses (AC #9)
-  - [ ] 8.8 Dual-file drift raises `ClinerulesDualFileDriftError`; no override flag (AC #10)
-  - [ ] 8.9 `profileHistory` append — first reconfigure creates the field; subsequent reconfigures append; cap at 20 drops oldest (AC #11)
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P3-3** (Local-LLM / On-Prem Agent Tuning Profile) — `reconfigure` extends the profile API established in Story 21.1 without changing `lib/profile.js`'s public contract. The three exports stay exactly as defined in Story 21.1 AC #1: `getProfile`, `setProfile`, `resolveProfile`. `reconfigure` is a new consumer, not a new API.
-- **NFR44** (profile isolation) — standard-profile output must remain free of on-prem strings after a `reconfigure` that lands on `standard`. Reuse of the installer's injection helpers (AC #5) is what guarantees this — forked re-stamp logic would risk drift.
-- **NFR45** (CI/CD compatibility) — `reconfigure` is *deliberately* incompatible with CI (`--yes` blocked per AC #6). This is not a regression of NFR45; NFR45 covers `install`, not `reconfigure`. CI never needs to call `reconfigure`; profile changes are a human, interactive act.
-- **NFR46** (idempotency) — after `reconfigure`, running `install` with the same profile must produce byte-identical output. Verified in Task 8 by running `install` after `reconfigure` and diffing marker-block regions.
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `bin/cli.js` | MODIFY — register `reconfigure` subcommand; route to new handler |
-| `lib/reconfigure.js` | CREATE — orchestrates prompt → confirmation → backup → re-stamp → history append |
-| `lib/installer.js` | MINOR — export injection functions currently internal if `reconfigure` needs to call them directly (avoid duplication) |
-| `lib/profile.js` | UNCHANGED — `setProfile` already does the right thing post-Step 2 of the corrective plan |
-| `test/reconfigure.test.js` | CREATE |
-
-### Library and Pattern References
-
-- Prompts library: **`prompts`** (npm) — same as the Story 21.1 wizard. Reuse the exact prompt shape; override only the `initial` index (to highlight the currently-persisted value) and the message text (`Current profile: <value>. Change to?`).
-- Injection helpers: reuse from `lib/installer.js` for the 5 instruction-block-injection files; reuse from `lib/merge/roomodes.js` (Story 21.3) for `.roomodes`.
-- `setProfile` from `lib/profile.js` — unchanged public contract.
-- Backup naming convention: `<target>.backup-<ISO-timestamp>` per Story 21.2 AC #8.
-- Error class names must match upstream exactly: `RoomodesSlugDivergenceError` (Story 21.3 AC #9), `ClinerulesDualFileDriftError` (Story 21.5 AC #6).
-
-### Out of Scope
-
-- Profile migration / data migration — none required. `.ma-agents.json` schema already has the `profile` field (Story 21.1 AC #12). Only the new optional `profileHistory` field is added; its absence is valid.
-- Programmatic re-stamp without a human — explicitly forbidden by AC #6. `--yes` is blocked.
-- Changing `lib/profile.js`'s public API — Story 21.1 AC #1 pinned three exports; `reconfigure` is a consumer, not a modifier.
-- Auto-rollback on failed re-stamp — out of scope for this story; failures surface as errors and leave the backup files available for manual recovery. A future story may add transactional re-stamp.
-
-### Testing Standards
-
-Match the existing test layout (node:test or mocha-style — verify by reading one existing test file first). Place `test/reconfigure.test.js` next to `test/profile.test.js`. All tests must run as part of `npm test`. Use `fs.mkdtempSync(os.tmpdir() + ...)` per test to isolate `.ma-agents.json` reads/writes — never mutate the repo's own `.ma-agents.json` or instruction files. Mock `prompts` for deterministic test runs (the installer tests already do this — reuse the pattern).
-
-### Epic 21 Cross-Story Context
-
-**Story 21.10 (this):** Reconfigure subcommand — escape hatch for a previously-persisted profile. Depends on Stories 21.1 (profile API), 21.2 (marker injection + backup convention), 21.3 (slug-stomp protection), 21.4 (`AGENTS.md` template + `markdown-markers` merger — re-stamped on profile flip), 21.5 (dual-file drift detection), 21.6 (on-prem layer composition — the actual content being re-stamped), 21.7 (BMAD persona `on_prem_phase_prefix` — re-composed when profile flips, per Task 3.3). Runs after 21.6 in the execution order; must exist before 21.9's end-to-end tests so the round-trip test (21.9 AC #1 (f)) can exercise the real command instead of manual `.ma-agents.json` edits.
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context) — bmad-dev-story flow.
-
-### Debug Log References
-- `.roomodes` slug-divergence comparison deliberately strips `customInstructions` because installed files already carry the profile-composed universal block; a profile flip legitimately rewrites that field. `whenToUse`, `roleDefinition`, `groups`, `name` are the user-editable surfaces the check catches. Documented inline in `lib/reconfigure.js::checkRoomodesSlugDivergence`.
-- `updateAgentInstructions` is invoked with `yesMode: true` from the reconfigure loop so per-file drift prompts do not re-ask after the global `Continue?` confirmation (AC #7). The installer's `handleMarkerBlockDrift` still emits the pinned WARNING line and writes the canonical `<target>.backup-<ISO>` sibling (AC #8).
-- `appendProfileHistory` does a fresh read-modify-write of `.ma-agents.json` so it composes with `setProfile`'s write — no parallel JSON-IO path. Cap enforcement is `shift()`-based (oldest-first eviction).
-
-### Completion Notes List
-- New `lib/reconfigure.js` orchestrator exports `reconfigure({ projectRoot, argv, promptsLib, now })` plus three named error classes (`RoomodesSlugDivergenceError`, `ManifestNotFoundError`, `ReconfigureYesRejectedError`) and the `PROFILE_HISTORY_CAP` constant (20).
-- `bin/cli.js` registers the `reconfigure` verb and routes to `handleReconfigure`, which maps each error class to a user-facing exit(1) message. `--yes` on reconfigure exits nonzero with the pinned message verbatim (AC #6).
-- Re-stamp reuses the canonical `updateAgentInstructions` path from `lib/installer.js`; zero forked logic. Backups are produced by the installer's existing drift handler using the canonical `buildBackupFilename` helper owned by Story 21.2.
-- `checkRoomodesSlugDivergence` throws `RoomodesSlugDivergenceError` when any ma-agents-owned slug present in the existing `.roomodes` differs from the shipped template on non-customInstructions fields; `--force-roomodes-overwrite` bypasses the check (AC #9). `.clinerules` dual-file drift is delegated to Story 21.5's `checkClinerulesDualFileDrift` (no override, AC #10).
-- `profileHistory` append uses a fresh read-modify-write that composes with `setProfile`'s write — capped at 20, oldest-first eviction (AC #11). Missing-field start is handled (first reconfigure creates the array).
-- Prompt shape mirrors Story 21.1's wizard prompt (same two choices) but with `initial` set to the persisted value's row and the message `Current profile: <value>. Change to?` per AC #2.
-
-### Adversarial Review Findings
-
-| # | Layer | Severity | Finding | Disposition |
-|---|-------|----------|---------|-------------|
-| 1 | Cynical | P1 | setProfile runs BEFORE re-stamp loop; mid-flight re-stamp failure leaves profile+artifacts out of sync | Accepted — story explicitly lists "Auto-rollback" as out of scope; `profileHistory` append is gated on full loop success so forensic log does not falsely record a partial reconfigure |
-| 2 | Cynical | P2 | `--yes` detection is string-includes on argv; benign for reconfigure (no positional args) | Accepted — same pattern as installer; reconfigure AC #1 forbids positional args |
-| 3 | Edge-case | P1 | Slug-divergence check drops `customInstructions` from the compare | Correct by design — installer-stamped `customInstructions` carries the composed block which legitimately changes per profile; other fields remain user-edit detectors. Test 8.7 exercises `whenToUse` drift |
-| 4 | Cynical | P2 | `appendProfileHistory` is read-modify-write, not atomic rename | Accepted — matches `setProfile`'s write pattern; reconfigure is interactive-only so concurrency isn't a realistic vector |
-| 5 | Edge-case | P2 | Same-value short-circuit when `persistedProfile === undefined` requires user to pick a value; cannot short-circuit to undefined | Accepted — prompt choices are `on-prem` | `standard` only; chosenProfile is always a concrete value |
-| 6 | Edge-case | P2 | No help-text doc for `--force-roomodes-overwrite` | **Fixed** — added Reconfigure options block in `showHelp()` |
-
-### File List
-- CREATED: `lib/reconfigure.js`
-- CREATED: `test/reconfigure.test.js` (12 tests, all passing)
-- MODIFIED: `bin/cli.js` (new `reconfigure` case + `handleReconfigure` + help text)
-- MODIFIED: `package.json` (added `test/reconfigure.test.js` to npm test script)
-- MODIFIED: `_bmad-output/implementation-artifacts/21-10-profile-reconfigure.md` (Dev Agent Record / File List / Change Log)
-
-## Change Log
-- 2026-04-15: Story 21.10 implemented — reconfigure CLI verb + orchestrator + slug/dual-file guards + profileHistory append. Status ready-for-dev → review.
-- 2026-04-15: Upstream dependency list completed per adversarial-review finding — added Stories 21.4 (`AGENTS.md` re-stamping surface), 21.7 (BMAD persona phase prefix re-composition). Restores Dependencies bidirectionality with those stories' downstream lists.
-- 2026-04-14: Story created (Epic 21, Story 21.10). Closes adversarial-review Findings #5 and #7 (no escape hatch for persisted profile; CI-default silent-downgrade trap).