pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/explore-usage.md

@@ -0,0 +1,93 @@
+# Explore Usage
+
+```bash
+maestro explore "FIND: <target + condition>\nSCOPE: <paths>" [more prompts...] [options]
+```
+
+Lightweight read-only codebase search. 1 prompt = 1 agent.
+**Not for**: write-mode, long sessions, follow-ups — use `delegate`.
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-e, --endpoint <names>` | Endpoint name(s), comma-separated | First available |
+| `--all` | Fan out each prompt to all endpoints | — |
+| `--max-turns <n>` | Max agent turns per job | Config or `6` |
+| `-f, --file <path>` | Load prompts from JSON or text file | — |
+| `--cd <dir>` | Working directory | Current |
+| `--json` | Output results as JSON | — |
+
+Endpoint resolution: `--endpoint` > `--all` > first available.
+
+## Prompt Rules
+
+**FIND + SCOPE is minimum standard.** Bare FIND produces unfocused results.
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `FIND` | **Yes** | Precise target — what exactly + condition |
+| `SCOPE` | **Yes** | File patterns or directories to search |
+| `EXCLUDE` | No | What to skip |
+| `ATTENTION` | No | Edge cases to watch |
+| `EXPECTED` | Recommended | Output format (`file:line` list, summary, JSON) |
+
+### Bad vs Good
+
+```
+# ❌ Vague — no actionable target
+FIND: database patterns
+FIND: error handling
+
+# ✅ Specific target + condition + scope
+FIND: Functions that execute SQL queries without parameterized inputs
+SCOPE: src/db/**/*.ts, src/api/**/*.ts
+
+FIND: catch blocks that swallow errors silently (empty catch or catch-and-log-only)
+SCOPE: src/services/
+EXPECTED: file:line list with severity
+```
+
+### Multi-Prompt
+
+**Decompose by angle, not by keyword.** Each prompt gets one focused question + scope.
+
+```
+# ❌ Keyword dump in one prompt
+"database error handling auth patterns"
+
+# ✅ One angle per prompt
+maestro explore \
+  "FIND: N+1 query patterns\nSCOPE: src/db/" \
+  "FIND: Unparameterized SQL\nSCOPE: src/db/, src/api/" \
+  "FIND: Missing error propagation\nSCOPE: src/services/"
+```
+
+Input formats: inline strings, JSON file (`-f`), text file (`-f`), or mixed.
+JSON supports per-prompt endpoint override:
+
+```json
+[{ "prompt": "FIND: auth bypass\nSCOPE: src/api/", "endpoint": "deepseek" }]
+```
+
+## Session
+
+```bash
+maestro explore show                  # list sessions
+maestro explore output <id>           # view results
+maestro explore output <id> --json    # JSON output
+```
+
+## Execution Rules
+
+Multi-prompt — **background**:
+
+```
+Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
+```
+
+Single quick lookup — foreground:
+
+```
+Bash({ command: "maestro explore \"Where is X defined?\"" })
+```

package/workflows/finish-work.md

@@ -0,0 +1,124 @@
+# Workflow: finish-work
+
+## Inputs
+
+`SESSION_DIR`, `SESSION_TYPE` (grill | brainstorm | analyze | blueprint | plan | execute | verify), `SESSION_ID`, `LINKED_MILESTONE` (optional).
+
+## Steps
+
+### 1. Detect outputs
+
+Scan `SESSION_DIR` for known files. Missing file → log W0xx, flag [LOW CONFIDENCE]. None found → skip to Step 4 with `extraction.harvested = false`.
+
+| File | Session types | Yields |
+|------|---------------|--------|
+| `context-package.json` | grill/brainstorm/analyze/blueprint | constraints + insights |
+| `terminology.md` | grill | domain terms |
+| `grill-report.md` | grill | decisions + risk register |
+| `conclusions.json` | analyze | decisions + recommendations |
+| `reflection-log.md` | execute | lessons + pitfalls |
+| `{role}/analysis.md` | brainstorm | role decisions |
+
+### 2. Extract fragments
+
+Build `fragments[]` from detected files. Each: `{ kind, category, title, content, keywords[], confidence, ref }`.
+
+**Routing table** — `locked` status or `priority ≥ medium` required unless noted:
+
+| Source | → Store | Category |
+|--------|---------|----------|
+| `context-package.json#constraints[locked]` | spec (rule) | `arch` if module/layer/boundary, else `coding` |
+| `context-package.json#insights[]` | knowhow (`DCS`/`RCP`) | `arch` for decisions, `coding` for patterns |
+| `conclusions.json#decisions[locked]` | spec (rule) | `arch` |
+| `conclusions.json#recommendations[≥medium]` | knowhow (`REF`) | area-derived |
+| `reflection-log.md` §Lessons/§Pitfalls | < 200 chars → spec (`learning`), else knowhow (`KNW`) | `learning` |
+| `{role}/analysis.md` §Decisions[locked] | spec (rule) | role-derived |
+| `grill-report.md` §Synthesis[locked] | spec (rule) | `arch` if scope/integration/security, else `coding` |
+| `grill-report.md` §Risk Register[≥medium] | knowhow (`REF`) | `debug` |
+| `terminology.md` locked terms | knowhow (`REF`) | `coding` |
+
+**Confidence** (drop if < 0.5): locked/decisions heading +0.3 · ≥3 keywords +0.2 · has rationale +0.2 · length 50-2000 +0.2 · has ref +0.1
+
+**Keywords**: 3-5 lowercased domain terms, frequency-ranked nouns/identifiers, stop words filtered.
+
+**Dedup**: hash `(kind, content[:100])` — skip if existing entry matches. MANDATORY via `maestro spec list --json` + `maestro knowhow list --json`.
+
+**Relationship to existing knowledge**: for `kind == "rule"` fragments, search existing spec in the same category (`maestro search "<keywords>" --type spec --json`, note each hit's `sid`). Classify against the closest existing entry — the two outcomes are distinct, do NOT conflate:
+- **supersedes** (evolution): the new rule replaces the old on the same topic — the old is now outdated, not merely disputed. Attach `supersedes = <old-sid>`.
+- **conflicts** (contradiction): both rules are plausible and a human must adjudicate which wins. Attach `conflicting_entry = { file, line }` + `conflict_note`.
+- **independent**: no strong overlap → no metadata.
+
+Never drop — proceed with whatever metadata attached.
+
+### 3. Route fragments
+
+Prompt once (unless `-y` auto mode):
+```
+Found {N} fragments — {S_spec} spec / {S_knowhow} knowhow. Apply? (auto | spec-only | knowhow-only | skip)
+```
+
+Routing — all CLI calls MANDATORY, NOT SUBSTITUTABLE:
+
+- **spec**: `maestro spec add <category> "<title>" "<content>" --keywords {csv} --description "<summary>" --source finish-work --json` → capture returned `sid` + id into `spec_ids[]` (the `--json` output carries the new entry's `sid`, needed for supersession).
+- **spec that supersedes** (evolution): after adding the new entry, retire the old one: `maestro spec supersede <old-sid> --by <new-sid>`. Old entry → `status="deprecated"` (excluded from search + agent injection), chain preserved and inspectable via `maestro spec history <sid>`. Record into `supersede_marks[]`.
+- **spec that conflicts** (contradiction): after adding, mark the old entry for human review: `maestro spec conflict mark <file> <line> --note "<note>"` → `confidence="contested"` (search ×0.5, `[CONTESTED]` badge, still injected). Resolution deferred to `/manage-knowledge-audit`. Record into `conflict_marks[]`.
+- **knowhow**: `maestro knowhow add --type {DCS|RCP|REF|KNW} --title "<title>" --body "<content>" --keywords {csv}` → capture id into `knowhow_ids[]`
+- **below threshold**: increment `skipped_count`
+- **CLI failure**: log W002, continue; flag [LOW CONFIDENCE]
+
+### 3.5 Domain term extraction
+
+Skip if `.workflow/domain/` absent or no term sources or all candidates already registered.
+
+Sources (priority order): `terminology.md` → `context-package.json#domain.terminology[]` → `conclusions.json#recommendations` with domain keywords.
+
+Process: collect candidates → filter registered terms → interactive confirm (always, `-y` does NOT bypass) → MANDATORY `maestro domain add` → record in `extraction.domain_ids[]`.
+
+### 4. Write archive.json
+
+Idempotent overwrite. Schema `session-archive/1.0`:
+
+```jsonc
+{
+  "$schema": "session-archive/1.0",
+  "session_id": "", "session_type": "", "session_path": "",
+  "lifecycle": { "status": "sealed", "sealed_at": "", "archived_at": null, "linked_milestone": null },
+  "content_refs": [/* { type, path } per detected file */],
+  "extraction": {
+    "harvested": true, "harvested_at": "",
+    "spec_ids": [], "knowhow_ids": [], "domain_ids": [],
+    "supersede_marks": [/* { old_sid, new_sid } — old entry deprecated, chain preserved */],
+    "conflict_marks": [/* { file, line, note } — old entry contested, pending audit */],
+    "skipped_count": 0
+  },
+  "pruned": null
+}
+// No fragments or user skip: "extraction": { "harvested": false, "reason": "no-signal | user-skip | harvest-failed" }
+```
+
+### 5. Report
+
+```
+=== SESSION SEALED ===
+Session:    {SESSION_ID} ({SESSION_TYPE})
+Knowledge:  {spec} spec / {knowhow} knowhow extracted, {skipped} skipped
+Superseded: {supersede_count} old entries deprecated (chain preserved — maestro spec history <sid>)
+Conflicts:  {conflict_count} entries marked [CONTESTED] — resolve via /manage-knowledge-audit
+Next:       /maestro-milestone-complete → archive + prune
+```
+
+## Boundary
+
+- Does NOT flip `archived_at` or move files (milestone-complete Step 2.3)
+- Does NOT prune `context-package.json` (milestone-complete only)
+- Does NOT touch `state.json` (caller handles)
+- Does NOT create issues (use `/manage-harvest` or `/manage-issue-discover`)
+
+## Errors
+
+| Code | Condition |
+|------|-----------|
+| E001 | SESSION_DIR missing |
+| E002 | SESSION_TYPE unknown |
+| W001 | No substantive outputs (seals with empty content_refs) |
+| W002 | CLI invocation failed (continue with remaining) |

package/workflows/fork.md

@@ -0,0 +1,162 @@
+# Workflow: fork
+
+---
+
+## Step 1: Parse Arguments and Flags
+
+```
+Timestamps use UTC+8 ISO format throughout.
+
+Parse from $ARGUMENTS:
+  --sync          → syncMode (sync existing worktree instead of forking)
+  --base <ref>    → baseBranch (default: HEAD)
+  -m <N> or bare <N> → milestoneNum (1-based)
+```
+
+---
+
+## Step 2: Validate Prerequisites
+
+```
+Require: .workflow/state.json (E001), .workflow/roadmap.md (E002), milestoneNum (E004).
+Reject: .workflow/worktree-scope.json present (E003 — cannot fork from inside a worktree).
+
+Read projectState from state.json, config from config.json (defaults if missing).
+worktreeRoot = config.worktree?.root ?? ".worktrees"
+branchPrefix = config.worktree?.branch_prefix ?? "milestone/"
+```
+
+---
+
+## Step 3: Resolve Milestone
+
+```
+Lookup milestoneEntry from projectState.milestones[milestoneNum - 1] (1-based).
+E005 if no milestones array; E006 if index out of range (list available milestones).
+
+Extract: milestoneName (.name), milestoneTitle (.title), milestonePhases (.phases).
+milestoneSlug = kebab-case of milestoneName, max 40 chars.
+```
+
+---
+
+## Step 4: Sync Mode (--sync)
+
+If `syncMode` is true, treat as sync operation on existing worktree, not a fork.
+
+```
+IF syncMode:
+  Find active worktree entry for milestoneNum in worktrees.json → E007 if not found.
+  Git merge main into worktree → warn and exit on conflict.
+  Re-copy shared context: project.md, roadmap.md, config.json (if exists), specs/ (if exists).
+  Display sync confirmation. EXIT.
+```
+
+---
+
+## Step 5: Validate & Confirm
+
+```
+Derive phase statuses from artifact registry (execute artifacts → completed/in_progress/pending).
+Reject if all phases completed (nothing to fork).
+Reject if milestone already has active worktree (E008).
+
+Display milestone info and phase list with statuses.
+Confirm with user → exit if declined.
+```
+
+---
+
+## Step 6: Create Worktree
+
+```
+forkSessionId = "fork-{UTC8_compact_timestamp}"
+baseCommit = git rev-parse HEAD
+branch = {branchPrefix}{milestoneSlug}
+wtPath = {worktreeRoot}/m{milestoneNum}-{milestoneSlug}
+
+6a: Clean up stale worktree/branch at wtPath if exists (ignore errors).
+6b: git worktree add -b {branch} {wtPath} {baseBranch}
+6c: mkdir -p {wtPath}/.workflow/scratch
+
+6d: Copy shared context → wtPath/.workflow/:
+    project.md, roadmap.md, config.json (if exists), specs/ (if exists)
+
+6e: Copy milestone artifacts — all artifacts matching milestoneName.
+6f: Copy dependency artifacts — phases from milestoneEntry.depends_on not in owned phases.
+
+6g: Build phase_dependencies map (external deps per owned phase).
+```
+
+Write `{wtPath}/.workflow/worktree-scope.json`:
+
+```json
+{
+  "worktree": true,
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "phase_dependencies": "{phaseDeps}",
+  "main_worktree": "{resolve(cwd)}",
+  "branch": "{branch}",
+  "base_commit": "{baseCommit}",
+  "created_at": "{UTC8_ISO}"
+}
+```
+
+```
+6i: Write scoped state.json — clone mainState with current_milestone set,
+    artifacts filtered to milestone-owned phases only.
+```
+
+---
+
+## Step 7: Update Main Registry
+
+```
+Load or initialize .workflow/worktrees.json (default: { version:"1.0", worktrees:[], fork_sessions:[] }).
+
+Append to worktrees[]:
+  { milestone_num, milestone, slug, branch, path:wtPath, base_commit, status:"active",
+    created_at, owned_phases, fork_session:forkSessionId }
+
+Append to fork_sessions[]:
+  { session_id:forkSessionId, created_at, milestone_num, milestone, base_branch, base_commit }
+
+Write worktrees.json. Update mainState.last_updated, write state.json.
+Note: worktrees.json owned_phases tracks forked state — no per-phase marking needed.
+```
+
+---
+
+## Step 8: Display Summary
+
+```
+Display:
+  === FORK COMPLETE ===
+  Session:    {forkSessionId}
+  Base:       {baseBranch} ({baseCommit.substring(0, 7)})
+  Milestone:  M{milestoneNum} — {milestoneName} ({milestoneTitle})
+  Branch:     {branch}
+  Path:       {wtPath}
+  Phases:     {ownedPhaseNumbers.join(', ')}
+
+  Next steps (run in the worktree):
+    cd {wtPath}
+
+    # Sequential lifecycle for each phase:
+    /maestro-analyze {firstPending.phase}
+    /maestro-plan {firstPending.phase}
+    /maestro-execute {firstPending.phase}
+    /quality-review {firstPending.phase}
+    # ... repeat for next phases in milestone
+
+  Or delegate (automated):
+    maestro delegate "run full lifecycle for milestone" --cd {wtPath} --mode write
+
+  Sync worktree with main (REQUIRED before merge):
+    /maestro-fork -m {milestoneNum} --sync
+
+  When all phases in milestone complete:
+    /maestro-merge -m {milestoneNum}
+```