create-quiver 0.10.0 → 0.12.1

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/pr.md

@@ -0,0 +1,77 @@
+## Title
+Quiver v25 - AI-First Lifecycle Orchestrator
+
+## Summary
+
+- Implements the Quiver v25 AI-first lifecycle orchestrator across CLI, state, planner approval gates, generated artifacts, controlled execution, worktrees/PRs, validation hardening, export, and migration dry-runs.
+- Adds durable `.quiver/` run state, agent profiles, prompt-only/provider adapter flows, phase-gated planning, reviewed technical-plan approval, generated specs/slices/handoffs/PR body, and one-slice execution closure.
+- Adds dashboard/agent-friendly lifecycle inspection and export commands for specs, slices, runs, agents, dependencies, blockers, progress, and migration state.
+
+## Scope
+
+- Product implementation for all v25 slices from `slice-01` through `slice-11`.
+- Documentation, templates, tests, smoke coverage, CLI help, generated npm scripts, and spec evidence.
+- No package release is included.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/**`
+- `package.json`
+- `scripts/ci/**`
+- `src/create-quiver/**`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/**`
+- `tests/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- Git checkout with the v25 branch.
+- No provider CLI credentials are required for dry-run/prompt-only validations.
+
+### Worktree Access
+
+- Run commands from the repository root.
+- This PR does not require a running app server.
+
+### Run the Project
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:doctor-fixtures
+```
+
+### Use Cases
+
+- Create and inspect AI lifecycle runs with `ai run create`, `ai status`, and `ai resume`.
+- Prepare docs-only context with `ai prepare-context --dry-run`.
+- Generate planner drafts, revise them, approve concrete versions, and create specs only after reviewed approval.
+- Execute or print slice prompts with `ai prompt-slice`, `ai execute-slice`, and `ai execute-plan`.
+- Inspect/export lifecycle state with `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report`.
+
+### Technical Verification
+
+```bash
+git diff --check
+node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); JSON.parse(require('fs').readFileSync('specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/slice.json','utf8'));"
+```
+
+## Evidence
+
+- See `specs/quiver-v25-ai-first-lifecycle-orchestrator/EVIDENCE_REPORT.md`.
+
+## Rollback
+
+- Revert the v25 slice commits in reverse order.
+- No migration or PR command writes unless invoked explicitly; dry-runs remain available for recovery.
+
+## Risks / Notes
+
+- Source-of-truth docs should not claim npm publication unless publication has been verified.
+- `CHANGELOG.md`/`ROADMAP.md` still need release-version sync before npm publishing.
+- The lifecycle export JSON is `schema_version: 1`; dashboard consumers should pin expectations.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Summary of Work
+
+- Created the v25 planning package.
+- Added spec, status, evidence report, execution plan, PR body, slice definitions, and handoffs.
+- Synced source-of-truth planning docs with v25 as planned work.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec folder created.
+- [x] `slice-00` created.
+- [x] Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- [x] JSON validation captured.
+- [x] `git diff --check` captured.
+- [x] No product code modified.
+
+## Relevant Changes
+
+- New folder: `specs/quiver-v25-ai-first-lifecycle-orchestrator/`.
+- Source-of-truth planning docs updated.
+
+## Pending
+
+- Execute implementation slices from `slice-01` onward.
+- Implement `slice-01` onward.
+
+## Remaining Risks
+
+- Release status wording for v24/v0.11-v0.12 should be verified before claiming npm publication in source docs.
+
+## Future Recommendations
+
+- Execute slices according to `EXECUTION_PLAN.md`.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Context
+
+This slice publishes the v25 planning package generated from approved acceptance criteria and a production-readiness review.
+
+## Objective
+
+Create the durable spec foundation for Quiver v25 without changing product behavior.
+
+## Scope
+
+- Create `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, and `pr.md`.
+- Create every slice folder with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Update `README_FOR_AI.md` and `ROADMAP.md` so source-of-truth docs mention v25 as planned work.
+
+## Acceptance Criteria
+
+- Spec folder exists.
+- Mandatory `slice-00` exists.
+- Every slice has required handoff files.
+- Every `slice.json` parses.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Write documentation only, following the existing `specs/quiver-v24-dx-onboarding-hardening/` structure.
+
+## Suggested Execution Steps
+
+1. Create the spec folder and top-level spec files.
+2. Create all slice folders and handoffs.
+3. Sync source-of-truth planning docs.
+4. Validate JSON and whitespace.
+
+## Restrictions
+
+- Do not edit CLI source.
+- Do not modify tests.
+- Do not publish or open a PR from this slice.
+
+## Risks
+
+- Source-of-truth docs could accidentally imply v25 is implemented. Keep wording as planned only.
+
+## Completion Checklist
+
+- [x] Spec files created.
+- [x] Slice handoffs created.
+- [x] Source-of-truth docs synced.
+- [x] JSON parse validation captured.
+- [x] `git diff --check` captured.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-25-00",
+  "type": "docs",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Create the documentation foundation for the AI-first lifecycle orchestrator spec before product implementation starts.",
+  "description": "Publish the v25 spec, status, evidence report, execution plan, PR body, slice definitions, handoffs, and source-of-truth planning references.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-first-lifecycle-orchestrator-spec-foundation",
+    "branch_name": "feature/QUIVER-25-00-ai-first-lifecycle-orchestrator-spec-foundation"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every implementation slice.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Sync README_FOR_AI.md and ROADMAP.md with v25 as planned work only.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing CLI behavior.",
+    "Changing package behavior.",
+    "Running AI providers.",
+    "Publishing a package.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v25-ai-first-lifecycle-orchestrator.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "README_FOR_AI.md and ROADMAP.md mention v25 as planned, not implemented.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v25-ai-first-lifecycle-orchestrator -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-01: CLI contract and compatibility
+
+## Summary of Work
+
+- Added top-level CLI version support for `--version` and `-V`.
+- Preserved `ai approve --version <n>` as the planner draft-version option.
+- Added CLI contract tests for version output and unsupported command guidance.
+- Documented `npx create-quiver --version` in the README command table and generated commands template.
+
+## Validation Against Acceptance Criteria
+
+- [x] Version commands verified.
+- [x] Alias behavior verified through shared binary entrypoint and package bin contract.
+- [x] Unknown command behavior verified.
+- [x] Docs updated.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `src/create-quiver/index.js`
+- `tests/commands/cli-contract.test.js`
+- `README.md`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/slice.json`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- The `quiver` alias itself is covered through package bin metadata and shared entrypoint behavior, not by installing a real local package binary during the test.
+
+## Future Recommendations
+
+- Keep top-level `--version` limited to the commandless case so `ai approve --version <n>` remains unambiguous.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-01: CLI contract and compatibility
+
+## Context
+
+Every later AI lifecycle feature depends on a clear command surface. This slice stabilizes command naming before state, approvals, agents, and execution are added.
+
+## Objective
+
+Make `create-quiver`, local `quiver`, generated `quiver:*` scripts, version reporting, and unknown-command errors consistent.
+
+## Scope
+
+- CLI routing and binary alias behavior.
+- `--version` support.
+- Documentation for canonical bootstrap vs local shortcut.
+- Tests for command compatibility and ambiguity.
+
+## Acceptance Criteria
+
+- `npx create-quiver --version` works.
+- Local `quiver --version` works when installed.
+- Unknown commands fail clearly.
+- Docs do not contradict `README_FOR_AI.md`.
+- Generated scripts target supported commands.
+
+## Technical Plan Summary
+
+Audit CLI entrypoints, normalize version handling, harden unknown command routing, and update docs/tests.
+
+## Suggested Execution Steps
+
+1. Read current CLI entrypoint and command router.
+2. Add/adjust version handling.
+3. Verify alias behavior.
+4. Update docs.
+5. Add focused tests.
+
+## Restrictions
+
+- Do not add new AI workflow behavior in this slice.
+- Do not change spec/slice generation behavior.
+
+## Risks
+
+- Changing routing may break legacy `npx create-quiver --name` usage.
+
+## Completion Checklist
+
+- [ ] Tests added or updated.
+- [ ] Docs updated.
+- [ ] Existing init behavior preserved.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-01-cli-contract-compatibility",
+  "ticket": "QUIVER-25-01",
+  "type": "feature",
+  "title": "CLI contract and compatibility",
+  "objective": "Make command naming, aliases, version reporting, and generated script behavior explicit and consistent.",
+  "description": "Define and implement the contract between canonical `npx create-quiver`, local `quiver`, and generated `quiver:*` scripts before adding more AI lifecycle commands.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "cli-contract-compatibility",
+    "branch_name": "feature/QUIVER-25-01-cli-contract-compatibility"
+  },
+  "files": [
+    "bin/**",
+    "package.json",
+    "src/create-quiver/**",
+    "docs/**",
+    "README.md",
+    "README_FOR_AI.md",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Establishes shared CLI routing and naming contracts used by all later slices.",
+  "must": [
+    "Preserve `npx create-quiver` as the canonical bootstrap path.",
+    "Keep `quiver` as local alias behavior where installed.",
+    "Make `--version` work for both command surfaces.",
+    "Document whether `ia` is supported or intentionally not supported.",
+    "Ensure unknown commands fail with actionable guidance."
+  ],
+  "not_included": [
+    "Run state persistence.",
+    "Agent execution.",
+    "Spec generation."
+  ],
+  "acceptance": [
+    "`npx create-quiver --version` prints the installed version without error.",
+    "Local `quiver --version` prints the installed version when the binary alias is available.",
+    "Docs explain bootstrap vs local alias without contradiction.",
+    "Unknown commands are not treated as project names.",
+    "Generated scripts target supported command names."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/CLOSURE_BRIEF.md

@@ -0,0 +1,43 @@
+# CLOSURE BRIEF - slice-02: Run state, phase gates, and locks
+
+## Summary of Work
+
+- Added persistent AI lifecycle run state under `.quiver/runs/<run-id>/`.
+- Added `ai run create`, `ai status`, and `ai resume` command behavior.
+- Added approvals metadata for lifecycle runs.
+- Added run/slice lock helpers with stale-lock metadata in `.quiver/locks/`.
+- Connected `ai plan` and `ai approve` to lifecycle phase updates.
+- Added phase guard helpers for blocking future-phase work with next-command guidance.
+
+## Validation Against Acceptance Criteria
+
+- [x] Run creation inspected.
+- [x] Resume verified.
+- [x] Invalid phase blocked.
+- [x] Locks verified.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `src/create-quiver/lib/ai/run-state.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/init-layout.js`
+- `tests/lib/ai-run-state.test.js`
+- `tests/commands/ai-run-state.test.js`
+- `tests/lib/init-layout.test.js`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/COMMANDS.md.template`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Locks are implemented as file locks with owner metadata. Process liveness cleanup is intentionally manual for now to avoid unsafe deletion.
+
+## Future Recommendations
+
+- Later slices should wire `assertAiRunPhaseAllows` into spec generation, execution planning, slice execution, and PR creation.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-02: Run state, phase gates, and locks
+
+## Context
+
+The lifecycle must survive interruptions, multiple agents, and multiple terminal sessions. Chat memory is not a safe state store.
+
+## Objective
+
+Add persistent run state, phase validation, approvals metadata, status/resume, and locks.
+
+## Scope
+
+- `.quiver/runs/<run-id>/state.json`.
+- `.quiver/runs/<run-id>/approvals.json`.
+- Run status and resume commands or command paths.
+- Phase transition validation.
+- Run/slice locks and stale-lock recovery.
+
+## Acceptance Criteria
+
+- Run state persists and can be resumed.
+- Future-phase commands are blocked.
+- Locks prevent concurrent mutation.
+- Stale locks are recoverable with metadata.
+
+## Technical Plan Summary
+
+Create state helpers and phase transition guards before adding higher-level planner or executor flows.
+
+## Suggested Execution Steps
+
+1. Define state schema and phase enum.
+2. Add read/write helpers.
+3. Add phase guard utility.
+4. Add lock helpers.
+5. Wire status/resume commands.
+6. Test phase and lock behavior with temp fixtures.
+
+## Restrictions
+
+- Do not execute provider CLIs.
+- Do not generate specs in this slice.
+
+## Risks
+
+- State schema drift can break future runs. Keep it versioned or migration-ready.
+
+## Completion Checklist
+
+- [ ] State helpers implemented.
+- [ ] Phase guards implemented.
+- [ ] Locks implemented.
+- [ ] Tests passing.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-02-run-state-phase-locks",
+  "ticket": "QUIVER-25-02",
+  "type": "feature",
+  "title": "Run state, phase gates, and locks",
+  "objective": "Persist AI lifecycle state and prevent invalid phase transitions or concurrent run corruption.",
+  "description": "Introduce `.quiver/runs/<run-id>/` state, approvals metadata, status/resume behavior, phase validation, and locks for runs and slices.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "run-state-phase-locks",
+    "branch_name": "feature/QUIVER-25-02-run-state-phase-locks"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-contract-compatibility"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Creates shared state machinery required by later slices.",
+  "must": [
+    "Create and load `.quiver/runs/<run-id>/state.json`.",
+    "Persist approvals metadata.",
+    "Add status and resume behavior.",
+    "Block commands that do not match the current phase.",
+    "Add run and slice locks with stale-lock metadata."
+  ],
+  "not_included": [
+    "Provider execution.",
+    "Generating specs from planner output.",
+    "Git worktree lifecycle."
+  ],
+  "acceptance": [
+    "A run can be created, inspected, and resumed.",
+    "Invalid future-phase commands are blocked with next-command guidance.",
+    "Run and slice locks prevent concurrent mutation.",
+    "Stale lock recovery shows metadata before removal.",
+    "State can be read without chat memory."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-03: Safe AI onboarding documentation
+
+## Summary of Work
+
+Implemented safe docs-only AI context preparation for new and existing projects.
+
+## Validation Against Acceptance Criteria
+
+- [x] New project fixture validated.
+- [x] Existing project fixture validated.
+- [x] Dry-run validated.
+- [x] Snapshot validated.
+- [x] Conflict reporting validated.
+
+## Relevant Changes
+
+- `ai prepare-context --dry-run` now reports proposed doc actions, compact diffs, assumptions, risks, contradictions, omitted paths, and uncertainty markers without writing.
+- Write mode snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` before updating docs.
+- Existing human-authored docs are preserved; Quiver appends or refreshes a managed context-prep block instead of replacing the full file.
+- Context prep now targets `INDEX`, `PROJECT_MAP`, `AI_CONTEXT`, `AI_ONBOARDING_PROMPT`, `CONTEXTO`, `WORKFLOW`, `ARCHITECTURE`, `STATUS`, and `DECISIONS`.
+- Context prep advances the lifecycle run to `onboarding-ready` after successful docs writes.
+- README and command docs describe diff preview, snapshots, and contradiction reporting.
+
+## Pending
+
+No pending implementation for this slice.
+
+## Remaining Risks
+
+- Diff snippets are previews; full review should still use `git diff`.
+- Contradiction detection is conservative and should expand with more real project signals in future hardening.
+
+## Future Recommendations
+
+- Dogfood this slice on Quiver itself and on a small generated project.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-03: Safe AI onboarding documentation
+
+## Context
+
+Quiver should reduce manual onboarding work by letting AI complete project context docs, but this must be safe in existing projects.
+
+## Objective
+
+Generate and update onboarding documentation with dry-run, snapshots, assumptions, and conflict reporting.
+
+## Scope
+
+- Docs-only onboarding generation.
+- New project and existing project behavior.
+- Dry-run previews and snapshots.
+- Uncertainty markers and contradiction reports.
+
+## Acceptance Criteria
+
+- New projects get generated onboarding docs.
+- Existing docs are preserved unless explicitly updated.
+- `--dry-run` writes nothing.
+- Snapshots are saved before writes.
+- Unknowns and contradictions are visible.
+
+## Technical Plan Summary
+
+Extend analyzer/context preparation into a safe doc writer that separates inferred facts from assumptions and uses the run state created in slice-02.
+
+## Suggested Execution Steps
+
+1. Define allowed docs and write policy.
+2. Add dry-run diff output.
+3. Add snapshot creation.
+4. Add uncertainty/conflict reporting.
+5. Cover project-new, project-existing, and old-Quiver fixtures.
+
+## Restrictions
+
+- Do not modify product code in target projects.
+- Do not read or log secret values from `.env` files.
+
+## Risks
+
+- AI text may sound more certain than evidence supports. Force uncertainty labels.
+
+## Completion Checklist
+
+- [ ] Dry-run implemented.
+- [ ] Snapshot behavior implemented.
+- [ ] Existing docs preservation tested.
+- [ ] Conflict reporting tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-03-safe-ai-onboarding-docs",
+  "ticket": "QUIVER-25-03",
+  "type": "feature",
+  "title": "Safe AI onboarding documentation",
+  "objective": "Let Quiver use AI to generate and update project onboarding docs safely for new, existing, and older Quiver projects.",
+  "description": "Implement docs-only onboarding generation with dry-run, diffs, snapshots, assumptions, risks, and conflict reporting.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "safe-ai-onboarding-docs",
+    "branch_name": "feature/QUIVER-25-03-safe-ai-onboarding-docs"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "templates/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-02-run-state-phase-locks"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run beside agent adapter work if command/state files do not overlap.",
+  "must": [
+    "Support onboarding generation with `--dry-run`.",
+    "Generate or update docs such as CONTEXTO, WORKFLOW, ARCHITECTURE, STATUS, INDEX, AI_CONTEXT, and PROJECT_MAP where applicable.",
+    "Mark uncertain content as TODO, Assumption, or Pending confirmation.",
+    "Preserve human-authored content and show diffs before writing.",
+    "Snapshot touched docs before writing.",
+    "Report contradictions instead of silently resolving them."
+  ],
+  "not_included": [
+    "Provider adapter implementation unless needed for prompt-only output.",
+    "Spec generation from approved plans.",
+    "Product code modification in target projects."
+  ],
+  "acceptance": [
+    "New projects receive useful onboarding docs from inferred stack/scripts/structure.",
+    "Existing projects update only approved docs without deleting useful content.",
+    "`--dry-run` writes nothing and reports proposed changes.",
+    "Snapshots are stored before writes.",
+    "Contradictions and unknowns are reported clearly.",
+    "No product code files are modified by onboarding generation."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "completed_at": "2026-05-22T16:31:18-0300",
+  "blocked_reason": null
+}