declare-cc 1.0.8 → 2.0.0

package/commands/declare/execute.md

@@ -1,521 +0,0 @@
----
-description: Execute actions for a milestone with wave-based scheduling and upward verification
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-argument-hint: "[M-XX] [--confirm]"
----
-
-Execute all pending actions for a milestone using wave-based scheduling, parallel agent spawning, per-wave verification, and automatic milestone completion.
-
-**Step 1: Determine milestone scope.**
-
-Parse `$ARGUMENTS` for a milestone ID (matching pattern `M-XX`) and a `--confirm` flag.
-
-If `$ARGUMENTS` contains a milestone ID, use it directly and proceed to Step 2.
-
-If `$ARGUMENTS` is empty or contains no milestone ID (interactive mode):
-- Run the milestone picker:
-
-```bash
-node dist/declare-tools.cjs execute
-```
-
-- Parse the JSON output. It contains a `milestones` array with `{id, title, status, actionCount, doneCount}` objects.
-- Display a numbered list:
-
-```
-## Select a Milestone to Execute
-
-1. M-01: [title] — [status] ([doneCount]/[actionCount] actions done)
-2. M-02: [title] — [status] ([doneCount]/[actionCount] actions done)
-```
-
-- Ask the user: "Which milestone would you like to execute? Provide the ID (e.g., M-01)."
-- Wait for the user's response, then use their provided ID in Step 2.
-
-Check if `--confirm` is present in `$ARGUMENTS`. If so, pause between waves for user review.
-
-**Step 2: Load execution data.**
-
-Run:
-
-```bash
-node dist/declare-tools.cjs execute --milestone M-XX
-```
-
-Parse the JSON output.
-
-If `allDone` is true:
-- Display: "All actions for M-XX are already complete. Milestone status: [status]"
-- Exit.
-
-Display a banner:
-
-```
-## Executing: M-XX — [milestoneTitle]
-
-**Declarations:** [for each declaration: "D-XX (title)"]
-**Actions:** [pendingCount] pending of [totalActions] total | **Waves:** [waves.length]
-```
-
-**Step 2.5: Check for drift.**
-
-Before executing waves, check whether any nodes have drifted from the declared future.
-
-Run:
-
-```bash
-node dist/declare-tools.cjs check-drift
-```
-
-Parse the JSON output.
-
-If `hasDrift` is true:
-- Display a drift warning:
-
-```
-## Drift Detected
-
-The following nodes have no causation path to any declaration:
-```
-
-For each drifted node in `driftedNodes`, display:
-```
-- [type] [id]: [title] (status: [status])
-  Suggestions:
-  - Connect to [suggestion.target] ([suggestion.targetTitle]) -- [suggestion.reason]
-```
-
-Then ask: "Drifted nodes detected. Continue execution anyway? (yes/no/fix)"
-- "yes" -> proceed with execution
-- "no" -> abort execution
-- "fix" -> suggest the user run /declare:milestones or manually edit MILESTONES.md/PLAN.md to reconnect orphaned nodes, then retry
-
-This is a SOFT BLOCK -- warn but allow continuation.
-
-If `hasDrift` is false: proceed silently.
-
-**Step 3: For each wave, execute actions.**
-
-Iterate over each wave in the `waves` array:
-
-**3a. Generate exec plans (on-demand, per wave):**
-
-For each action in the wave:
-
-```bash
-node dist/declare-tools.cjs generate-exec-plan --action A-XX --milestone M-XX --wave N
-```
-
-Parse the JSON output and note the `outputPath` for each action.
-
-If any generation returns an error, display it and suggest fixes (e.g., "Run /declare:actions first to create the milestone plan folder").
-
-**3b. Display wave banner:**
-
-```
---- Wave N of [total waves] ---
-**Actions:** A-XX ([title]), A-XX ([title])
-Spawning [count] agent(s)...
-```
-
-**3c. Spawn executor agents in parallel using the Task tool:**
-
-For each action in the wave, spawn a Task with `model: "opus"` and instructions like:
-
-```
-Execute the plan at [outputPath].
-
-Read the EXEC-PLAN file at the path above. Follow all tasks described in it.
-Make atomic commits per task. When complete, report:
-- What was done
-- Files created or modified
-- Commit hashes
-- Any issues encountered
-
-Context: This action is part of milestone M-XX ([milestoneTitle]).
-```
-
-Use one Task tool call per action. If the wave has multiple actions, spawn them all in the same response so they execute in parallel.
-
-**3d. After all agents in the wave complete, verify:**
-
-Run:
-
-```bash
-node dist/declare-tools.cjs verify-wave --milestone M-XX --actions "A-01,A-02"
-```
-
-(Use the comma-separated list of action IDs from the current wave.)
-
-Parse the verification JSON output.
-
-Display automated check results:
-
-```
-### Wave N Verification
-
-| Action | Check        | Result |
-| ------ | ------------ | ------ |
-| A-XX   | action-exists | PASS   |
-| A-XX   | produces-exist| PASS   |
-```
-
-Perform AI review: Given the trace context from the verification result (`traceContext.whyChain` and `traceContext.declarations`), assess whether the completed work meaningfully advances the milestone. Produce a 1-2 sentence assessment.
-
-If `passed` is false (verification failed):
-- Identify which actions failed and what checks failed.
-- Retry up to 2 times: re-spawn the failed action's Task agent with the failure context appended:
-
-```
-Previous attempt failed verification. Failure details:
-- Check [check-name] failed for action A-XX
-- [Details from allChecks]
-
-Please fix the issues and try again.
-```
-
-- After 2 retries with continued failure, surface to user:
-  "Action A-XX failed verification after 2 retries. Details: [failure info]. What would you like to do?"
-- Wait for user guidance before continuing.
-
-If `--confirm` flag was set, pause after successful verification:
-- "Wave N complete and verified. Proceed to Wave N+1? (yes/no)"
-- Wait for user confirmation before continuing.
-
-**3e. Propagate statuses after each wave:**
-
-After successful wave verification, run sync-status to update PLAN.md, MILESTONES.md, and FUTURE.md atomically. This keeps the dashboard live as waves complete:
-
-```bash
-node dist/declare-tools.cjs sync-status
-```
-
-Do not manually edit PLAN.md or MILESTONES.md — sync-status handles all of it correctly.
-
-**Step 4: After all waves complete, propagate statuses.**
-
-Run sync-status to propagate action → milestone → declaration completion automatically:
-
-```bash
-node dist/declare-tools.cjs sync-status
-```
-
-Parse the result. It will show which actions, milestones, and declarations were marked DONE.
-Display: "Status propagated — [summary from sync-status result]."
-
-Proceed to Step 5. Do NOT display a completion banner yet — that happens in Step 8 after verification.
-
-**Step 5: Milestone truth verification.**
-
-After marking the milestone DONE in Step 4, verify whether the milestone truth actually holds.
-
-**5a. Run programmatic verification:**
-
-```bash
-node dist/declare-tools.cjs verify-milestone --milestone M-XX
-```
-
-Parse the JSON result. It contains `criteria` (array of `{id, type, passed, description, evidence}`), `programmaticPassed`, `aiAssessmentNeeded`, and `traceContext`.
-
-**5b. Display programmatic check results:**
-
-```
-### Milestone Verification: M-XX
-
-| Criterion | Type | Result | Evidence |
-| --------- | ---- | ------ | -------- |
-| SC-01     | artifact | PASS | File found at path (NNN bytes) |
-| SC-02     | test | PASS | npm test exited with code 0 |
-| SC-03     | ai   | (pending) | |
-```
-
-For each criterion in the result, show its id, type, result (PASS if `passed === true`, NOT YET MET if `passed === false`, `(pending)` if `passed === null`), and evidence.
-
-**5c. Perform AI assessment:**
-
-If `programmaticPassed` is false, skip AI assessment -- programmatic criteria not yet met are definitive. Proceed directly to remediation (Step 6).
-
-If `programmaticPassed` is true, perform the AI assessment for the criterion with `type: "ai"`:
-
-- Read the milestone title and the trace context (`traceContext.declarations` and `traceContext.whyChain`) from the verify-milestone result.
-- Review the work completed across all waves (the actions executed, their produces, the wave verification results).
-- Assess: "Given that all actions for this milestone have completed, does the milestone truth statement hold? Is '[milestone title]' actually true?"
-- If the AI assessment is positive: mark the AI criterion as passed with a 1-2 sentence evidence summary.
-- If the AI assessment is negative: mark the AI criterion as not yet met with evidence explaining what is missing.
-
-Use restoration-focused language throughout: "criterion met" / "criterion not yet met" (never "passed" / "failed" in user-facing output).
-
-**5d. Determine verification outcome:**
-
-- ALL criteria met (including AI): proceed to mark KEPT (Step 5e).
-- ANY criterion not yet met: proceed to remediation loop (Step 6).
-
-**5e. All criteria met -- mark milestone KEPT:**
-
-1. Read `.planning/MILESTONES.md`, change M-XX status from DONE to KEPT.
-2. Write the updated MILESTONES.md back.
-3. Write VERIFICATION.md to the milestone folder using the `writeVerificationFile` format:
-   - State: `KEPT`
-   - Criteria: all criteria with their pass/fail status, descriptions, and evidence
-   - History: one attempt entry with `passed: true`, `remediationTriggered: false`, `stateTransition: "DONE -> KEPT"`
-4. Display (3-5 lines):
-
-```
-Milestone M-XX verified as KEPT -- "[milestone title]" holds true.
-[Brief summary of what was verified: N artifact checks, test suite, AI assessment all met.]
-```
-
-5. Skip to completion banner (Step 8).
-
-**Step 6: Remediation loop (max 2 attempts).**
-
-If verification in Step 5 found criteria not yet met:
-
-**6a. Update MILESTONES.md status to BROKEN for M-XX.**
-
-Read `.planning/MILESTONES.md`, change M-XX status from DONE to BROKEN, write back.
-
-**6b. Write initial VERIFICATION.md to the milestone folder.**
-
-Write VERIFICATION.md with:
-- State: `BROKEN`
-- Criteria: all criteria with current results
-- History: one attempt entry with `passed: false`, `remediationTriggered: true`, `stateTransition: "DONE -> BROKEN"`, checks summary (which criteria not yet met)
-
-**6c. For each remediation attempt (max 2):**
-
-**i. Derive remediation actions.** Analyze the criteria not yet met. For each criterion not yet met, derive 1-3 targeted remediation actions using AI reasoning:
-
-```
-Given these verification results for milestone M-XX ("[milestone title]"):
-
-Criteria not yet met:
-- SC-XX: [description] -- Evidence: [evidence]
-
-Derive remediation actions. Rules:
-- Each action targets exactly one criterion not yet met
-- Do not modify code that already meets its criteria
-- Maximum 3 actions per remediation attempt
-- Each action needs: title, produces field, description
-```
-
-**ii. Append remediation actions to PLAN.md.** For each derived action:
-- Read the existing PLAN.md from the milestone folder (use `milestoneFolderPath` from Step 2).
-- Add a new action section at the bottom with the next available A-XX ID.
-- Mark it with `**Derived:** remediation (attempt N)` instead of a creation date.
-- Write the updated PLAN.md.
-
-**iii. Generate exec plans for remediation actions:**
-
-```bash
-node dist/declare-tools.cjs generate-exec-plan --action A-XX --milestone M-XX --wave remediation
-```
-
-**iv. Display remediation banner:**
-
-```
---- Remediation Attempt N ---
-**Criteria not yet met:** SC-XX, SC-YY
-**Actions:** A-XX ([title]), A-YY ([title])
-Spawning [count] agent(s)...
-```
-
-**v. Spawn executor agents for remediation actions using the Task tool** (same pattern as Step 3c).
-
-**vi. After remediation agents complete, re-run verification:**
-
-```bash
-node dist/declare-tools.cjs verify-milestone --milestone M-XX
-```
-
-Re-perform AI assessment for the AI criterion (same process as Step 5c).
-
-**vii. If ALL criteria now met:**
-- Read `.planning/MILESTONES.md`, change M-XX status from BROKEN to HONORED.
-- Write the updated MILESTONES.md back.
-- Update VERIFICATION.md: use `appendAttempt` to add the successful attempt with `passed: true`, `remediationTriggered: false`, `stateTransition: "BROKEN -> HONORED"`, and update the header state to HONORED.
-- Display (3-5 lines):
-
-```
-Milestone M-XX verified as HONORED -- "[milestone title]" now holds true.
-Remediation: [brief description of what was fixed]. [N] criteria now met.
-```
-
-- Skip to completion banner (Step 8).
-
-**viii. If criteria still not met after attempt 2:** proceed to escalation (Step 7).
-
-**Step 7: Escalation.**
-
-After 2 remediation attempts with criteria still not met:
-
-**7a. Update VERIFICATION.md** with the final attempt (attempt 2) results using `appendAttempt`.
-
-**7b. Display diagnosis report:**
-
-```
-## Verification: M-XX requires attention
-
-**Milestone:** [milestone title]
-**Remediation attempts:** 2 (criteria still not yet met)
-
-### What was tried
-
-**Attempt 1:** [actions taken] -- [which criteria still not yet met]
-**Attempt 2:** [actions taken] -- [which criteria still not yet met]
-
-### Criteria still not yet met
-
-| Criterion | Evidence |
-| --------- | -------- |
-| SC-XX     | [latest evidence] |
-
-### Suggestions
-
-- [Specific suggestion per criterion not yet met, e.g., "Consider narrowing SC-02 to check only the main export" or "The test in SC-03 may need a mock for external service X"]
-
-### Options
-
-1. **Adjust** the milestone statement or success criteria, then I will retry verification
-2. **Accept** the current state and continue to the next milestone
-```
-
-**7c. Wait for user response.**
-
-If user chooses to **adjust**:
-- Apply the user's adjustments to the milestone statement or success criteria.
-- Re-run verification (Step 5).
-- If all criteria now met: change M-XX status from BROKEN to RENEGOTIATED in MILESTONES.md.
-- Update VERIFICATION.md with a new attempt entry with `stateTransition: "BROKEN -> RENEGOTIATED"`.
-- Display: "Milestone M-XX renegotiated and verified -- adjusted criteria now hold."
-- Proceed to Step 8.
-
-If user chooses to **accept**:
-- Leave M-XX status as BROKEN in MILESTONES.md.
-- Add a note to VERIFICATION.md: "User accepted current state. Milestone remains BROKEN."
-- Proceed to Step 8.
-
-**Step 8: Occurrence check at milestone completion.**
-
-After execution and verification, check whether declarations still occur as declared.
-
-Run:
-
-```bash
-node dist/declare-tools.cjs check-occurrence
-```
-
-Parse the JSON output. For each declaration in the `declarations` array:
-
-Perform AI assessment: Given the declaration statement and its connected milestones/actions, assess:
-1. Does this declaration still occur as what was declared? (Is it still true/relevant?)
-2. Has any work drifted from the declaration's intent?
-3. Rate alignment: HIGH / MEDIUM / LOW
-
-Display the assessment:
-
-```
-### Occurrence Check: [declarationId] -- [statement]
-
-**Statement:** "[statement]"
-**Connected milestones:** [milestoneCount] ([count of verified] verified)
-**Assessment:** [AI assessment of whether this still occurs as declared]
-**Alignment:** [HIGH/MEDIUM/LOW]
-```
-
-If the AI assessment determines a declaration is "no longer true" or alignment is LOW:
-- Ask the user: "Declaration [declarationId] appears to no longer occur as declared. Renegotiate? (yes/no)"
-- If "yes" -> enter renegotiation flow (Step 9a)
-- If "no" -> note it and continue
-
-**Step 9a: Renegotiation flow (if triggered).**
-
-Ask the user: "Why is this declaration no longer true?" and capture their reason.
-
-Run:
-
-```bash
-node dist/declare-tools.cjs renegotiate --declaration D-XX --reason "[user's reason]"
-```
-
-Parse the JSON output.
-
-Display:
-
-```
-### Renegotiation Complete: [archived.id]
-
-**Archived to:** FUTURE-ARCHIVE.md
-**Reason:** [reason]
-```
-
-If `orphanedMilestones` is non-empty, display them grouped:
-
-```
-**Orphaned milestones requiring review:**
-```
-
-For each orphaned milestone:
-```
-- [id]: [title] ([status])
-  Actions: [action.id] ([action.status]), ...
-  Options:
-  1. Reassign to another declaration
-  2. Archive this milestone
-  3. Leave for now (will appear as drift)
-```
-
-"Which milestones would you like to reassign? Provide IDs or 'skip' to leave for later."
-
-If user provides IDs, guide them through reassignment (edit MILESTONES.md to update the Realizes column). If "skip", acknowledge and continue.
-
-Then prompt: "Would you like to create a replacement declaration now? (yes/no)"
-- If "yes": suggest running `/declare:future` to add a new declaration
-- If "no": continue
-
-**Step 9: Completion banner.**
-
-Display the final execution summary:
-
-```
-## Execution Complete: M-XX -- [milestoneTitle]
-
-**Actions completed:** [count of actions executed, including remediation actions]
-**Waves executed:** [count of waves]
-**Verification:** [KEPT | HONORED | RENEGOTIATED | BROKEN (user accepted)]
-**Milestone status:** [final status in MILESTONES.md]
-**Occurrence check:** [Performed — X declarations assessed / Skipped (if no declarations affected)]
-```
-
-**Error handling:**
-
-- If any CJS command returns a JSON with an `error` field, display it clearly and suggest fixes.
-- If milestone folder not found, suggest running `/declare:actions` first to create the milestone plan.
-- If no pending actions, report the milestone is already complete.
-- If a Task agent fails (non-verification failure), display the error and ask the user how to proceed.
-
-**Key patterns:**
-
-- Execution scope is per-milestone (never cross-milestone).
-- Wave scheduling is automatic from the action graph.
-- Auto-advance between waves by default; `--confirm` pauses for user review.
-- GSD-style banners with progress at each stage.
-- Atomic commits per task (handled by executor agents).
-- Two-layer verification: automated checks (CJS tool) then AI review (this slash command).
-- Max 2 retries on verification failure before escalating to user.
-- Milestone truth verification after all waves: DONE is intermediate, KEPT/HONORED/RENEGOTIATED are final.
-- Auto-remediation derives targeted actions, appends to PLAN.md, executes, and re-verifies.
-- Escalation provides diagnosis with specific suggestions, never judgment.
-- Language is restoration-focused: "criterion not yet met" not "failed", "requires attention" not "broken".
-- State transitions: DONE -> KEPT (all criteria met first try), DONE -> BROKEN -> HONORED (remediated), DONE -> BROKEN -> RENEGOTIATED (user adjusted criteria).
-- VERIFICATION.md written to milestone folder with full attempt history and audit trail.
-- Drift pre-check (Step 2.5): soft-block warning before wave execution if orphaned nodes detected.
-- Occurrence checks (Step 9): AI assessment of each declaration after milestone completion.
-- Renegotiation flow (Step 9a): archives declaration to FUTURE-ARCHIVE.md, presents orphans for reassignment.
-- FUTURE.md is the shared future document referenced as the source of truth for all alignment checks.

package/commands/declare/future.md

@@ -1,72 +0,0 @@
----
-description: Declare futures through guided conversation
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-argument-hint: "[--add]"
----
-
-Guide the user through declaring their project's future as present-tense truth statements.
-
-**Step 1: Load current graph state.**
-
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-Parse the JSON output. If the output contains an `error` field (e.g., "No Declare project found"), tell the user to run `/declare:init` first and stop.
-
-Note the existing declarations from the graph (if any) -- the workflow needs this context.
-
-**Step 2: Determine mode.**
-
-- If `$ARGUMENTS` contains `--add`, skip the intro and go directly to the per-declaration loop (adding to existing declarations).
-- If the graph already has declarations and `--add` is NOT present, show existing declarations and ask: "Would you like to add to these, or start fresh?"
-
-**Step 3: Follow the declaration capture workflow.**
-
-Read and follow the full workflow instructions:
-
-@workflows/future.md
-
-Pass the loaded graph state into the workflow so it knows about existing declarations.
-
-**Step 4: Persist each confirmed declaration.**
-
-After each declaration passes language detection and NSR validation and the user confirms it, persist it:
-
-```bash
-node dist/declare-tools.cjs add-declaration --title "Short Title" --statement "Full present-tense declaration statement"
-```
-
-Parse the JSON output to confirm the declaration was created and note its assigned ID (e.g., D-01).
-
-**Step 5: Launch dashboard and show summary.**
-
-After all declarations are captured:
-
-1. Start the dashboard server (if not already running):
-
-```bash
-node dist/declare-tools.cjs serve --port 3847 > /tmp/declare-dashboard.log 2>&1 &
-sleep 1 && curl -sf http://localhost:3847/api/graph -o /dev/null && echo "RUNNING" || echo "FAILED"
-```
-
-If RUNNING, open it:
-```bash
-open http://localhost:3847 2>/dev/null || true
-```
-
-2. List all declarations with their IDs and statements.
-
-3. Suggest next step:
-
-```
-Your declarations are live in the dashboard → http://localhost:3847
-The graph updates every 5 seconds as you add milestones and actions.
-
-Run /declare:milestones to work backward from these declarations.
-```

package/commands/declare/health.md

@@ -1,92 +0,0 @@
----
-description: Diagnose .planning/ directory health and optionally repair issues
-argument-hint: [--repair]
-allowed-tools:
-  - Read
-  - Bash
-  - Write
----
-
-Validate `.planning/` directory integrity and report actionable issues.
-
-**Step 1: Parse arguments.**
-
-Check `$ARGUMENTS` for the `--repair` flag.
-
-**Step 2: Run health check.**
-
-If `--repair` was passed:
-
-```bash
-node dist/declare-tools.cjs health-check --repair
-```
-
-Otherwise:
-
-```bash
-node dist/declare-tools.cjs health-check
-```
-
-Parse the JSON output. It contains:
-- `healthy`: boolean — whether all checks passed
-- `issues`: array of `{ type, message, path, fixable }` objects
-- `repaired`: array of strings describing what was fixed (only present when `--repair` was used)
-
-**Step 3: Display results.**
-
-**If healthy (no issues):**
-
-```
-.planning/ health: OK
-
-All checks passed:
-  FUTURE.md            — exists and parseable
-  MILESTONES.md        — exists and parseable
-  config.json          — exists and parseable
-  Milestone folders    — all referenced milestones have folders
-  Orphan check         — no orphaned milestone folders
-```
-
-**If there are issues:**
-
-Show a header with the count:
-
-```
-.planning/ health: [N] issue(s) found
-```
-
-Then list each issue clearly:
-
-```
-  [type indicator] [message]
-  Path: [path]
-  Fixable: yes / no
-```
-
-Use these type indicators:
-- `missing_file` → "MISSING"
-- `parse_error` → "PARSE ERROR"
-- `missing_folder` → "MISSING FOLDER"
-- `orphaned_folder` → "ORPHAN"
-
-**If `--repair` was used and repairs were made:**
-
-```
-Repaired [N] issue(s):
-  - [repair description]
-  ...
-
-Remaining issues: [N] (require manual intervention)
-```
-
-**Step 4: Suggest next steps.**
-
-If there are unfixable issues, suggest:
-- Missing FUTURE.md or MILESTONES.md: "Run `/declare:init` to recreate missing files"
-- Parse errors: "Manually inspect and fix the file at [path]"
-- Orphaned folders: "Remove or reconnect the folder: [path]"
-
-If there are fixable issues and `--repair` was NOT passed:
-```
-Run `/declare:health --repair` to automatically fix [N] fixable issue(s).
-```