maestro-flow-one 0.2.25 → 0.2.27

package/maestro-flow/commands/milestone/audit.md

@@ -21,6 +21,8 @@ Audit milestone completion using the artifact registry. Checks:
 
 Data source: `state.json.artifacts[]` filtered by current milestone.
 Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+
+Pipeline position: downstream of maestro-verify (all phases verified), upstream of maestro-milestone-complete.
 </purpose>
 
 <required_reading>
@@ -38,19 +40,60 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 - Plan scratch dirs — for task status verification
 
 **Adhoc milestone support (D-008):** When the target milestone has `type == "adhoc"` (or `type` field is missing, defaulting to `"standard"`), the audit skips roadmap.md parsing and phase coverage checks. It only validates artifact chain completeness (PLN→EXC exists) and runs integration checks.
+
+### Pre-load
+
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for integration checks
+2. **Specs**: `maestro spec load --category review` — load review standards for audit
+3. All optional — proceed without if unavailable
+
+### Role Knowledge
+
+1. Browse: `maestro wiki list --category review`
+2. Select entries relevant to milestone integration audit
+3. Load: `maestro wiki load <id1> [id2...]`
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/milestone-audit.md' completely.
 
 Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
-
-**Next-step routing on completion:**
-- Verdict PASS → `/maestro-milestone-complete {milestone}`
-- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
-- Verdict FAIL, incomplete execution → `/maestro-execute`
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== MILESTONE AUDIT READY ===
+Milestone: {milestone}
+Verdict: {PASS|FAIL}
+Phases audited: {N}
+Integration gaps: {N}
+Report: .workflow/milestones/{milestone}/audit-report.md
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence .workflow/milestones/{milestone}/audit-report.md]
+```
+
+Status verdicts:
+- **DONE** — Audit passed, no gaps found
+- **DONE_WITH_CONCERNS** — Audit passed with minor caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verdict PASS | `/maestro-milestone-complete {milestone}` |
+| Verdict FAIL, integration gaps | `/maestro-plan --gaps` |
+| Verdict FAIL, incomplete execution | `/maestro-execute` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|

package/maestro-flow/commands/milestone/complete.md

@@ -13,13 +13,23 @@ allowed-tools:
 ---
 
 <purpose>
-Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final knowhow, and advances to the next milestone.
+Mark a milestone as complete after its audit has passed. Performs 6-step archival:
+validation → directory archival → artifact history → knowhow extraction → state advancement → cleanup.
+
+Produces `milestones/{M}/artifacts/` archive and `specs/learnings.md` knowhow entries.
+Supports two milestone types: standard (advances to next milestone) and adhoc (self-contained, sets idle).
+
+Pipeline position: downstream of `maestro-milestone-audit` (requires PASS verdict). Upstream of `maestro-milestone-release` (cut a release) or next milestone planning (`maestro-analyze` / `maestro-plan`).
 </purpose>
 
 <required_reading>
 @~/.maestro/workflows/milestone-complete.md
 </required_reading>
 
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when updating milestone_history and advancing state
+</deferred_reading>
+
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
 
@@ -50,20 +60,52 @@ After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
 
 If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
 
-**Next-step routing on completion:**
-- Cut a release → `/maestro-milestone-release`
-- Next milestone → `/maestro-analyze` or `/maestro-plan 1` (standard milestones only)
-- View state → `/manage-status`
-
 **Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone_id}
+Status: ARCHIVED
+Artifacts archived: {count}
+Knowhow extracted: {count} entries
+Next milestone: {next_id | "none (adhoc)"}
+==============================
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Cut a release | `/maestro-milestone-release` |
+| Next milestone (standard) | `/maestro-analyze` or `/maestro-plan 1` |
+| View state | `/manage-status` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Milestone identifier required | Check arguments |
 | E002 | error | Audit not passed | Run maestro-milestone-audit first |
 | E003 | error | Incomplete artifacts remain | Complete remaining work first |
+| W001 | warning | Knowhow extraction produced 0 entries | Review milestone work for missed learnings |
+| W002 | warning | Wiki-connect found unlinked knowledge islands | Run `/manage-wiki --fix` manually |
 </error_codes>
 
 <success_criteria>

package/maestro-flow/commands/milestone/release.md

@@ -15,6 +15,8 @@ allowed-tools:
 
 <purpose>
 Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
+
+Pipeline position: downstream of `/maestro-milestone-complete` (consumes archived milestone + audit verdict). Terminal command — no downstream consumer.
 </purpose>
 
 <required_reading>
@@ -25,11 +27,14 @@ Package a completed milestone into a releasable version. Bumps the project versi
 $ARGUMENTS -- optional explicit version string and flags.
 
 **Flags:**
-- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
-- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
-- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
-- `--no-tag` -- skip git tag creation (version bump + changelog only)
-- `--no-push` -- skip `git push --follow-tags` after tagging
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `<version>` | Explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted | — |
+| `--bump patch\|minor\|major` | Semver bump relative to the current version | `minor` |
+| `--dry-run` | Compute the next version, changelog diff, and tag name without writing files or creating tags | `false` |
+| `--no-tag` | Skip git tag creation (version bump + changelog only) | `false` |
+| `--no-push` | Skip `git push --follow-tags` after tagging | `false` |
 
 **State files:**
 - `.workflow/state.json` -- current_milestone, previous release version
@@ -43,6 +48,13 @@ $ARGUMENTS -- optional explicit version string and flags.
 - Working tree must be clean (no uncommitted changes) unless `--dry-run`
 </context>
 
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
+**Scope guard**: only release decisions; do not prejudge next milestone scope
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/milestone-release.md' completely.
 
@@ -55,7 +67,12 @@ Follow '~/.maestro/workflows/milestone-release.md' completely.
 6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
 7. Push commit + tag to remote (unless `--no-push`)
 
-**Report format on completion:**
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<completion>
+### Standalone report
+
 ```
 === RELEASE COMPLETE ===
 Version:   v{previous} → v{new}
@@ -63,14 +80,28 @@ Milestone: {milestone_name}
 Tag:       v{new} {pushed|local-only}
 Changelog: {N} entries written to CHANGELOG.md
 Manifest:  {file_path} updated
+```
+
+### Ralph-invoked completion
 
-Next steps:
-  /maestro-plan {next_phase}   -- Start next milestone's first phase
-  /manage-status               -- View project dashboard
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 ```
 
-For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
-</execution>
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
+| Want to view project dashboard | `/manage-status` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"