create-quiver 0.12.1 → 0.13.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-07-context-analysis-and-doctor-flow/slice.json

@@ -0,0 +1,88 @@
+{
+  "slice_id": "slice-07-context-analysis-and-doctor-flow",
+  "ticket": "QUIVER-27-07",
+  "type": "implementation",
+  "title": "Context analysis and doctor flow",
+  "objective": "Harden analyze, prepare-context, flow, and doctor so onboarding docs are evidence-based, dry-runs are read-only, and next steps are accurate.",
+  "description": "Fixes stack detection, read-only dry-run behavior, docs/status consistency checks, stale-state guidance, active spec/slice examples, root/package manager detection, and first-use diagnostics.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-context-analysis-doctor-flow",
+    "branch_name": "feature/QUIVER-27-07-v27-context-analysis-doctor-flow"
+  },
+  "files": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "src/create-quiver/commands/prepare.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "tests/fixtures/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/commands/analyze.test.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/flow.test.js",
+    "tests/commands/doctor.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "src/create-quiver/commands/prepare.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "tests/fixtures/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses",
+    "slice-06-validation-gates-and-scope-safety"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Context and doctor guidance depends on resolver and validation contract behavior.",
+  "must": [
+    "Make analyze --dry-run read-only.",
+    "Improve React/Vite and stack detection using package.json and config evidence.",
+    "Make prepare-context conservative and evidence-based.",
+    "Detect docs/status contradictions without overwriting human content.",
+    "Make flow show source/timestamp or stale-state information.",
+    "Make doctor prioritize active spec/slice examples where available."
+  ],
+  "not_included": [
+    "Changing spec create behavior.",
+    "Changing worktree lifecycle beyond guidance messages.",
+    "Executing AI providers."
+  ],
+  "acceptance": [
+    "analyze --dry-run leaves git status unchanged.",
+    "React + Vite projects are detected as React/Vite, not Vue.",
+    "prepare-context --dry-run does not propose placeholders as truth when evidence exists.",
+    "flow reports the state source or a stale/missing context explanation.",
+    "doctor examples prefer active spec/slice context or generic examples over the wrong spec."
+  ],
+  "tests": [
+    "node --test tests/commands/analyze.test.js tests/commands/ai-onboard.test.js tests/commands/flow.test.js tests/commands/doctor.test.js tests/lib/project-scan.test.js tests/lib/doctor.test.js",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Snapshot git status before/after dry-run tests.",
+    "Use fixtures with stale docs and real completed slices."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-08: Cross-platform help, auth, and DX
+
+## Summary
+
+Hardened cross-platform DX around help output, agent profile previews, GitHub auth diagnostics, SSH/path guidance, and package-manager-aware next-step messaging.
+
+## Validation Against Acceptance Criteria
+
+- Help output now documents the `ai agent set --dry-run` flow and the general `--dry-run` option includes `ai agent set`.
+- Paths with spaces now trigger shell-specific guidance for macOS/Linux, Windows PowerShell, Git Bash, and WSL in GitHub PR/preflight output.
+- GitHub auth failures now identify likely account, scope, and SSH alias issues and point to `gh auth status` as the next safe command.
+- `ai agent set --dry-run` validates and previews the profile without writing `.quiver/agents/profiles.json`.
+- `flow` now reports the detected package manager and generated `quiver:flow` script command; init/migrate install fallback warnings respect npm, pnpm, yarn, or bun.
+
+## Changes
+
+- Added `buildAgentProfileState` and wired `ai agent set --dry-run` through `src/create-quiver/commands/ai.js`.
+- Updated CLI help, examples, and agent dispatch in `src/create-quiver/index.js`.
+- Added GitHub auth classification and shell-safe command/path formatting in `src/create-quiver/lib/ai/github.js`.
+- Added package-manager-aware flow output in `src/create-quiver/commands/flow.js`.
+- Updated command docs and v27 evidence/status docs.
+- Added focused tests for agent dry-run, help contract, GitHub diagnostics/path guidance, and flow package-manager output.
+
+## Remaining Risks
+
+- `gh auth status` output varies by GitHub CLI version; diagnostics intentionally combine parsed hints with general account/scope/alias guidance.
+- Shell-safe examples are generated for common shells, but unusual shell configurations may still require manual path adaptation.
+
+## Follow-up Recommendations
+
+- In `slice-09`, include smoke coverage for packaged CLI help, `flow`, `ai agent set --dry-run`, and GitHub diagnostic fixtures.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-08: Cross-platform help, auth, and DX
+
+## Context
+
+Pixel Quiver exposed DX gaps around paths with spaces, GitHub auth, command copying, help coverage, and safe profile configuration. This slice focuses on user-facing clarity after core context behavior is hardened.
+
+## Objective
+
+Improve cross-platform help, auth diagnostics, and actionable command guidance.
+
+## Scope
+
+- CLI help
+- doctor/preflight messages
+- GitHub auth diagnostics
+- agent profile dry-run
+- package manager-aware suggestions
+- docs and tests
+
+## Acceptance Criteria
+
+- Help output covers public commands and key options.
+- Path guidance is copy-safe across OS variants.
+- GitHub auth diagnostics are actionable.
+- Agent profile dry-run does not write files.
+- Suggested commands respect detected package manager.
+
+## Technical Plan Summary
+
+Update help registry/messages, add auth diagnostics and dry-run preview, and cover OS/package-manager examples with tests.
+
+## Suggested Execution Steps
+
+1. Inspect help and diagnostics surfaces.
+2. Add/adjust `ai agent set --dry-run`.
+3. Improve GitHub auth and SSH alias messages.
+4. Add path/package-manager guidance.
+5. Update docs and tests.
+
+## Restrictions
+
+- Do not install credentials or mutate user auth.
+- Do not require network in tests.
+
+## Risks
+
+- Help output can drift; keep tests tied to command registry.
+
+## Completion Checklist
+
+- [ ] Help tests updated.
+- [ ] Auth diagnostics tested.
+- [ ] Agent dry-run tested.
+- [ ] Cross-platform path guidance tested.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-08-cross-platform-help-auth-and-dx",
+  "ticket": "QUIVER-27-08",
+  "type": "implementation",
+  "title": "Cross-platform help, auth, and DX",
+  "objective": "Improve cross-platform command guidance, GitHub auth diagnostics, help output, agent profile dry-runs, and next safe command messaging.",
+  "description": "Hardens copy-safe command output for macOS/Linux/Windows, paths with spaces, GitHub/SSH auth diagnostics, top-level help coverage, agent profile dry-runs, and actionable error messages.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-cross-platform-help-auth-dx",
+    "branch_name": "feature/QUIVER-27-08-cross-platform-help-auth-dx"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/actionable-error.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/doctor.js",
+    "docs/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/ai-github.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/actionable-error.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/doctor.js",
+    "docs/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-07-context-analysis-and-doctor-flow"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "DX/help output should reference the final hardened context and doctor behavior.",
+  "must": [
+    "Provide copy-safe path guidance for spaces and OS variants.",
+    "Improve GitHub auth diagnostics and SSH alias guidance.",
+    "Keep --help complete and grouped.",
+    "Add ai agent set --dry-run or equivalent safe preview.",
+    "Improve next safe command messages.",
+    "Respect package manager detection in suggested commands."
+  ],
+  "not_included": [
+    "Installing gh or SSH keys automatically.",
+    "Executing provider APIs.",
+    "Publishing npm."
+  ],
+  "acceptance": [
+    "Help output includes new/changed commands and key options.",
+    "Paths with spaces produce copy-safe guidance for macOS, Linux, PowerShell, Git Bash, and WSL.",
+    "GitHub auth errors identify likely account/scope/alias issues and next safe commands.",
+    "ai agent set dry-run previews file changes without writing.",
+    "Package manager suggestions respect detected npm/pnpm/yarn/bun."
+  ],
+  "tests": [
+    "node --test tests/commands/cli-contract.test.js tests/commands/ai-agent.test.js tests/lib/ai-github.test.js tests/lib/doctor.test.js",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fixtures for paths with spaces and missing/ambiguous gh auth.",
+    "Do not require real GitHub credentials in tests."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-09: Fixtures, smoke, docs, and release readiness
+
+## Summary
+
+Validated the full v27 hardening package from source and packaged CLI behavior. Added final fixture coverage, stale/legacy doctor regressions, packaged CLI smokes, and synchronized source-of-truth docs with the implemented-but-unpublished state.
+
+## Validation Against Acceptance Criteria
+
+- All v27 QP/QIS items are covered by completed slices or final fixture validation evidence.
+- Sanitized fixtures now cover Pixel Quiver-style completed specs, paths with spaces, no-Git projects, old `.quiver` state, multiple specs, and stale docs.
+- `node --test tests/**/*.test.js` passed with 356 tests.
+- `npm run smoke:create-quiver`, `npm run smoke:guided-workflow`, `npm run smoke:doctor-fixtures`, and `npm run package:quiver` passed.
+- Package/tarball smoke validates installed CLI behavior for help, `flow`, and `ai agent set --dry-run`, not only source files.
+- `README.md`, `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` are synchronized with v27 implemented but not published.
+
+## Changes
+
+- Extended `tests/fixtures/validation-errors/matrix.json` with executable coverage references for final dogfooding states.
+- Hardened `scripts/ci/smoke-doctor-fixtures.js` to require traceable fixture coverage files.
+- Added doctor tests for stale generated docs and old incomplete `.quiver` state.
+- Extended `scripts/ci/smoke-create-quiver.sh` to validate source and packaged CLI first-use guidance.
+- Updated v27 status, roadmap, PR body, evidence, closure, and root docs.
+
+## Remaining Risks
+
+- npm publication is intentionally outside this slice and must happen only through the normal release process.
+- The final Pixel Quiver project remains external evidence; committed fixtures stay sanitized and do not copy private project content.
+
+## Follow-up Recommendations
+
+- Open the v27 PR with the completed evidence pack.
+- After merge, run the normal release flow and publish the next package version if approved.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-09: Fixtures, smoke, docs, and release readiness
+
+## Context
+
+After all v27 implementation slices, Quiver needs full regression evidence from source and packaged CLI behavior. This slice closes the spec without publishing npm.
+
+## Objective
+
+Validate v27 end to end with sanitized fixtures, tests, smokes, tarball/package smoke, docs sync, and release readiness evidence.
+
+## Scope
+
+- Regression fixtures
+- Smoke scripts and evidence
+- README/README_FOR_AI/ROADMAP/CHANGELOG
+- v27 status/evidence/closure
+
+## Acceptance Criteria
+
+- Every QP/QIS is fixed, validated, or documented as remaining risk.
+- Sanitized fixtures cover real production cases.
+- Full tests and smokes pass.
+- Package/tarball smoke validates installed behavior.
+- Docs reflect implemented behavior only.
+
+## Technical Plan Summary
+
+Add fixtures, run full validation, smoke the packaged CLI from outside the repo, update docs and evidence, and mark the spec release-ready without publishing.
+
+## Suggested Execution Steps
+
+1. Add sanitized fixtures from dogfooding cases.
+2. Run full test and smoke suite.
+3. Package and smoke the tarball outside the repo.
+4. Update README, README_FOR_AI, ROADMAP, CHANGELOG, STATUS, and EVIDENCE_REPORT.
+5. Record remaining risks.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not commit private local paths or credentials.
+- Do not claim release until package smoke passes.
+
+## Risks
+
+- Tarball smoke may reveal package-only issues; fix or document before closure.
+
+## Completion Checklist
+
+- [ ] Fixtures sanitized.
+- [ ] Full tests passed.
+- [ ] Smokes passed.
+- [ ] Tarball smoke passed.
+- [ ] Docs synced.
+- [ ] Spec evidence completed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/slice.json

@@ -0,0 +1,91 @@
+{
+  "slice_id": "slice-09-fixtures-smoke-docs-and-release-readiness",
+  "ticket": "QUIVER-27-09",
+  "type": "validation",
+  "title": "Fixtures, smoke, docs, and release readiness",
+  "objective": "Validate the full v27 hardening package with sanitized fixtures, local tests, smoke tests, tarball/package validation, and source-of-truth docs.",
+  "description": "Adds final regression fixtures from real dogfooding, runs full local and package smokes, synchronizes docs, records evidence, and confirms release readiness without publishing npm.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-fixtures-smoke-docs-release-readiness",
+    "branch_name": "feature/QUIVER-27-09-fixtures-smoke-docs-release-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "package.json",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**",
+    "tests/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-02-json-export-contract-and-machine-output",
+    "slice-03-approved-plan-to-spec-create",
+    "slice-04-ai-artifact-storage-redaction-and-token-compaction",
+    "slice-05-worktree-lifecycle-locks-and-recovery",
+    "slice-06-validation-gates-and-scope-safety",
+    "slice-07-context-analysis-and-doctor-flow",
+    "slice-08-cross-platform-help-auth-and-dx"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and docs sync must run after all implementation slices.",
+  "must": [
+    "Add sanitized fixtures that represent real dogfooding failures.",
+    "Run full command and lib tests.",
+    "Run smoke suites.",
+    "Run package/tarball smoke from outside the repo.",
+    "Update source-of-truth docs only with implemented behavior.",
+    "Record release readiness evidence without publishing."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Opening PR unless requested.",
+    "Adding unsanitized local paths or credentials."
+  ],
+  "acceptance": [
+    "All v27 QP/QIS coverage items are either fixed, validated, or documented as remaining risk.",
+    "Sanitized fixtures cover Pixel Quiver completed specs, path with spaces, no Git, old .quiver state, multiple specs, and stale docs.",
+    "node --test tests/**/*.test.js passes.",
+    "smoke:create-quiver, smoke:guided-workflow, and smoke:doctor-fixtures pass or documented blockers are resolved.",
+    "Package/tarball smoke validates installed CLI behavior rather than only source code.",
+    "README, README_FOR_AI, ROADMAP, and CHANGELOG are synchronized with actual implementation state."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:guided-workflow",
+    "npm run smoke:doctor-fixtures",
+    "npm run package:quiver",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run package smoke from /private/tmp or another clean directory.",
+    "Confirm fixtures do not contain private tokens or unnecessary personal paths."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/src/create-quiver/commands/ai.js

@@ -3,6 +3,12 @@ const path = require('node:path');
 
 const { redactSecrets } = require('../lib/evidence');
 const { formatActionableError } = require('../lib/actionable-error');
+const {
+  assertProviderPromptWithinLimit,
+  compactRevisionInput,
+  extractCleanProviderOutput,
+  writeRawProviderArtifact,
+} = require('../lib/ai/artifacts');
 const { buildContextPackMetadata, normalizeRole } = require('../lib/ai/context-packs');
 const { runExecuteSlice, runPromptSlice } = require('../lib/ai/executor');
 const { runExecutePlan } = require('../lib/ai/execution-plan');
@@ -38,6 +44,7 @@ const {
 } = require('../lib/ai/run-state');
 const {
   agentProfilesPath,
+  buildAgentProfileState,
   getAgentProfile,
   listAgentProfiles,
   resolveProfileProvider,
@@ -298,15 +305,11 @@ function writeProviderOutput(result) {
   }
 }
 
-function getRedactedProviderText(result) {
-  return redactSecrets([result.stdout, result.stderr].filter(Boolean).join(''));
-}
-
 function normalizeText(value) {
   return String(value || '').replace(/\r\n/g, '\n');
 }
 
-function buildRevisionInput({ phase, feedbackPath, feedbackText, repoRoot }) {
+function buildRevisionInput({ phase, feedbackPath, feedbackText, repoRoot, compactionOptions = {} }) {
   const current = readPhaseApproval(repoRoot, phase);
   if (!current.draft) {
     throw new Error(formatError(`ai revise --phase ${phase} requires an existing draft; current status is ${current.status}. Run \`npx create-quiver ai plan --phase ${phase} --input <file>\` first.`));
@@ -327,7 +330,7 @@ function buildRevisionInput({ phase, feedbackPath, feedbackText, repoRoot }) {
     feedbackText.trimEnd(),
   );
 
-  return sections.join('\n\n');
+  return compactRevisionInput(sections.join('\n\n'), compactionOptions);
 }
 
 function buildManagedContextBlock(content) {
@@ -723,6 +726,7 @@ async function runPlan(repoRoot, options = {}) {
   const context = options.context || DEFAULT_PLAN_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   let inputPath = options.input || '';
+  let inputCompaction = null;
 
   if (phase === 'spec') {
     const resolved = resolveReviewedTechnicalPlanInput(repoRoot, inputPath || undefined);
@@ -781,12 +785,15 @@ async function runPlan(repoRoot, options = {}) {
       throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'`));
     }
     const feedbackText = readTextFile(inputPath, repoRoot);
-    inputText = buildRevisionInput({
+    const revisionInput = buildRevisionInput({
       phase,
       feedbackPath: inputPath,
       feedbackText,
       repoRoot,
+      compactionOptions: options,
     });
+    inputText = revisionInput.text;
+    inputCompaction = revisionInput.compaction;
   } else if (phase === 'technical-plan') {
     const resolved = resolveApprovedPlannerInput(repoRoot, phase, inputPath || undefined);
     inputPath = resolved.inputPath;
@@ -809,6 +816,7 @@ async function runPlan(repoRoot, options = {}) {
     revise: options.revise === true,
   });
   const prompt = contextInfo.prompt;
+  assertProviderPromptWithinLimit(prompt, options);
   let invocation;
 
   try {
@@ -871,12 +879,27 @@ async function runPlan(repoRoot, options = {}) {
     throw annotateProviderError(result.error || new Error('provider run failed'), 'plan', phase);
   }
 
-  const draft = savePlannerDraft(repoRoot, phase, inputPath, getRedactedProviderText(result));
   const lifecycleRun = ensureAiRun(repoRoot, {
     command: `ai plan --phase ${phase}`,
     input: inputPath,
     runId: options.runId,
   });
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, `ai-plan-${phase}`, result, {
+    metadata: {
+      phase,
+      input_path: inputPath,
+      prompt_bytes: invocation.promptLength,
+      clean_output_source: clean.source,
+      stripped_prompt_echo: clean.strippedPromptEcho,
+      input_compaction: inputCompaction,
+    },
+  });
+  const draft = savePlannerDraft(repoRoot, phase, inputPath, clean.cleanOutput, {
+    rawArtifactPath: rawArtifact.path,
+    outputSource: clean.source,
+    inputCompaction,
+  });
   updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-draft' : 'technical-plan-draft', {
     artifact: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
     command: `ai plan --phase ${phase}`,
@@ -911,6 +934,7 @@ async function runReviewPlan(repoRoot, options = {}) {
     inputText,
     inputPath,
   });
+  assertProviderPromptWithinLimit(built.prompt, options);
   let invocation;
 
   try {
@@ -993,11 +1017,31 @@ async function runReviewPlan(repoRoot, options = {}) {
     throw annotateProviderError(result.error || new Error('provider run failed'), 'review-plan');
   }
 
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai review-plan',
+    input: inputPath,
+    runId: options.runId,
+    phase: 'technical-plan-reviewed',
+  });
+  const clean = extractCleanProviderOutput(result, { prompt: built.prompt, projectRoot: repoRoot });
+  const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, 'ai-review-plan', result, {
+    metadata: {
+      phase: 'plan-review',
+      input_path: inputPath,
+      input_kind: resolved.kind,
+      input_version: resolved.version || null,
+      prompt_bytes: invocation.promptLength,
+      clean_output_source: clean.source,
+      stripped_prompt_echo: clean.strippedPromptEcho,
+    },
+  });
   const saved = savePlanReview(repoRoot, {
-    contents: getRedactedProviderText(result),
+    contents: clean.cleanOutput,
     inputPath,
     inputKind: resolved.kind,
     inputVersion: resolved.version,
+    outputSource: clean.source,
+    rawArtifactPath: rawArtifact.path,
   });
   const relativePath = path.relative(repoRoot, saved.filePath).split(path.sep).join('/');
   process.stdout.write(`AI plan review saved\nArtifact: ${relativePath}\nPrompt source: ${PLAN_REVIEW_PROMPT_SOURCE}\n`);
@@ -1261,6 +1305,21 @@ function formatAgentProfileList(profiles) {
   return `${lines.join('\n')}\n`;
 }
 
+function formatAgentProfileDryRun(repoRoot, result) {
+  const relativePath = path.relative(repoRoot, result.filePath).split(path.sep).join('/');
+  const verb = result.action === 'update' ? 'update' : 'create';
+  return [
+    'AI agent profile dry-run',
+    '- Writes: none',
+    `- Would ${verb}: ${relativePath}`,
+    '',
+    formatAgentProfile(result.profile).trimEnd(),
+    '',
+    'No secrets or provider credentials are stored in agent profiles.',
+    '',
+  ].join('\n');
+}
+
 function runAgent(repoRoot, options = {}) {
   const command = String(options.command || '').trim().toLowerCase();
 
@@ -1271,6 +1330,22 @@ function runAgent(repoRoot, options = {}) {
     if (!options.provider) {
       throw new Error(formatError('ai agent set requires --provider. Supported providers: codex, claude, gemini.'));
     }
+    if (options.dryRun) {
+      const preview = buildAgentProfileState(repoRoot, options.role, {
+        context: options.context,
+        label: options.label,
+        model: options.model,
+        provider: options.provider,
+      });
+      process.stdout.write(formatAgentProfileDryRun(repoRoot, preview));
+      return {
+        task: 'agent',
+        command,
+        dryRun: true,
+        profile: preview.profile,
+        filePath: path.relative(repoRoot, preview.filePath).split(path.sep).join('/'),
+      };
+    }
     const result = setAgentProfile(repoRoot, options.role, {
       context: options.context,
       label: options.label,