declare-cc 1.0.7 → 2.0.0

package/workflows/milestones.md

@@ -1,87 +0,0 @@
-# Milestone Derivation Workflow
-
-You are guiding a user through milestone derivation: starting from declared futures and working backward to milestones by asking "what must be true?" at each level.
-
-This workflow derives milestones only. Action plans are derived separately via `/declare:actions`.
-
-## Opening
-
-Show the declarations being processed:
-
-> Let's work backward from your declarations to concrete milestones.
->
-> Your declared futures:
-> - D-01: [statement]
-> - D-02: [statement]
-> ...
->
-> I'll take each declaration and ask: "For this to be true, what must be true?" Each answer becomes a milestone -- a condition that must hold for the declaration to be realized.
-
-If deriving for a specific declaration (argument provided), focus on just that one:
-
-> Let's derive milestones for:
-> - [D-XX]: [statement]
-
-## Re-Derivation Awareness
-
-If milestones already exist for a declaration being derived:
-
-> These milestones were previously derived for [D-XX]:
-> - M-01: [title]
-> - M-02: [title]
->
-> Do these still align with the declaration? Should we keep, adjust, or replace any of them?
-
-Only proceed with new derivation after the user confirms which existing milestones to keep. Do not auto-reconcile -- the user decides.
-
-## Per-Declaration Derivation Loop
-
-For each declaration D that needs derivation:
-
-### a. State the backward question explicitly
-
-Make the reasoning visible. This is the core teaching moment:
-
-> For "[D statement]" to be true, what must be true?
-
-### b. Propose milestones
-
-Propose 2-4 milestones. Present each with clear backward logic explaining WHY it must be true for the declaration to hold:
-
-> I see these conditions that must hold:
->
-> 1. **[Milestone A]** -- because [why this must be true for D to be true]
-> 2. **[Milestone B]** -- because [why this must be true for D to be true]
-> 3. **[Milestone C]** -- because [why this must be true for D to be true]
-
-These will be presented as checkboxes by the command for the user to select which to accept.
-
-### c. User selects milestones via checkboxes
-
-The command presents the proposed milestones as a checkbox list using AskUserQuestion. The user checks which milestones to accept. Persist each accepted milestone immediately.
-
-### d. Move to the next declaration
-
-After milestones for one declaration are confirmed and persisted, move to the next declaration.
-
-## Closing
-
-After all declarations have their milestones:
-
-> Milestone derivation complete.
->
-> From [N] declarations, we derived [X] milestones.
->
-> Run `/declare:actions` to derive action plans for each milestone.
-
-## Design Principles
-
-Follow these throughout the conversation:
-
-- **Make the backward logic visible and teachable.** Always state the question being asked ("For X to be true, what must be true?"). This teaches the user the thinking pattern.
-- **Milestones are confirmed via checkboxes.** Batch selection per declaration, not individual confirmation prompts.
-- **No action derivation in this workflow.** Actions are derived separately via `/declare:actions`.
-- **Flag inconsistencies, don't auto-fix.** When re-deriving for a declaration that already has milestones, show existing ones and let the user decide.
-- **Propose, don't dictate.** Present milestones as proposals. The user may have better ideas.
-- **Show your reasoning.** For each proposed milestone, explain why it must be true.
-- **Do not use emojis.** Keep the tone professional and grounded.

package/workflows/scope.md

@@ -1,94 +0,0 @@
-# Declaration Scope Review
-
-You are reviewing the full set of declared futures with the user before deriving milestones. This is a synthesis checkpoint — confirm the foundation is solid so milestone derivation builds on the right ground.
-
-## Purpose
-
-Before working backward to milestones, establish:
-1. The declarations collectively tell a coherent story
-2. The scope boundary is clear (what's in, what's out)
-3. No important futures are missing or redundant
-4. The framing reflects what the user actually intends to build
-
-## Opening
-
-Synthesize all declarations into a scope statement. Do not simply list them — draw out what they *mean together*:
-
-```
-Looking at your declarations as a whole:
-
-[D-01]: [statement]
-[D-02]: [statement]
-...
-
-Here's the scope I see:
-
-[2-3 sentence synthesis: what this project creates, who it serves, what fundamentally changes]
-
-In scope: [concrete things the declarations cover]
-Assumed out of scope: [what the declarations imply is NOT the focus]
-
-Does this framing match your intent?
-```
-
-Present this as text, then use AskUserQuestion:
-
-- header: "Scope"
-- question: "Does this framing capture what you're building?"
-- options:
-  - "Yes, this is right — derive milestones" (Recommended)
-  - "A declaration needs adjusting"
-  - "Something important is missing"
-  - "The scope feels off"
-
-## If "A declaration needs adjusting"
-
-Ask which declaration and what's off. Work through the refinement conversationally. If the updated statement is meaningfully different:
-
-```bash
-node dist/declare-tools.cjs add-declaration --title "[revised title]" --statement "[revised statement]"
-```
-
-Note: if removing the old version matters, flag it to the user — they can delete the old declaration or keep both if they serve different purposes.
-
-After the change, re-synthesize and confirm once more.
-
-## If "Something important is missing"
-
-Guide the user to state the missing future using the same language principles as in `/declare:future`: present-tense, stated as fact, not goal language. Validate and add:
-
-```bash
-node dist/declare-tools.cjs add-declaration --title "[title]" --statement "[statement]"
-```
-
-After adding, re-synthesize and confirm.
-
-## If "The scope feels off"
-
-Probe what specifically feels wrong:
-
-- Too broad? — Help identify which declarations to narrow or which to defer
-- Too narrow? — Something missing (redirect to above)
-- Wrong framing? — Rephrase the synthesis, not the declarations, and re-confirm
-
-One pass of adjustment is enough. After a second confirmation attempt, proceed.
-
-## After Confirmation
-
-Once framing is confirmed, briefly acknowledge it and move forward:
-
-```
-Scope confirmed.
-
-[N] declarations covering [core theme]. Deriving milestones by working backward from each.
-```
-
-Then immediately proceed to milestone derivation — do not ask more questions here.
-
-## Design Principles
-
-- **Synthesize, don't list.** The user already saw their declarations. Show what they mean together.
-- **Name what's out.** Explicit scope exclusions prevent milestone sprawl during derivation.
-- **One round of adjustment.** If the user modifies and re-confirms, proceed. Don't loop more than twice.
-- **Be concrete.** Don't say "the project creates value" — say "the project gives developers a self-hosted AI coding workflow that runs without a cloud dependency."
-- **No emojis.** Keep tone grounded.

package/workflows/verify.md

@@ -1,504 +0,0 @@
-<purpose>
-Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /declare:verify --gaps.
-
-User tests, Claude records. One test at a time. Plain text responses.
-</purpose>
-
-<philosophy>
-**Show expected, ask if reality matches.**
-
-Claude presents what SHOULD happen. User confirms or describes what's different.
-- "yes" / "y" / "next" / empty → pass
-- Anything else → logged as issue, severity inferred
-
-No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
-</philosophy>
-
-<template>
-@workflows/uat-template.md
-</template>
-
-<process>
-
-<step name="initialize" priority="first">
-If $ARGUMENTS contains a milestone identifier (e.g., M-08), load context:
-
-```bash
-INIT=$(node dist/declare-tools.cjs execute --milestone "${MILESTONE_ARG}" 2>/dev/null || echo "{}")
-```
-
-Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `milestone_found`, `milestone_dir`, `milestone_id`, `milestone_name`, `has_verification`.
-</step>
-
-<step name="check_active_session">
-**First: Check for active UAT sessions**
-
-```bash
-find .planning/milestones -name "*-UAT.md" -type f 2>/dev/null | head -5
-```
-
-**If active sessions exist AND no $ARGUMENTS provided:**
-
-Read each file's frontmatter (status, milestone) and Current Test section.
-
-Display inline:
-
-```
-## Active UAT Sessions
-
-| # | Milestone | Status | Current Test | Progress |
-|---|-----------|--------|--------------|----------|
-| 1 | M-04-comments | testing | 3. Reply to Comment | 2/6 |
-| 2 | M-05-auth | testing | 1. Login Form | 0/4 |
-
-Reply with a number to resume, or provide a milestone ID to start new.
-```
-
-Wait for user response.
-
-- If user replies with number (1, 2) → Load that file, go to `resume_from_file`
-- If user replies with milestone ID → Treat as new session, go to `create_uat_file`
-
-**If active sessions exist AND $ARGUMENTS provided:**
-
-Check if session exists for that milestone. If yes, offer to resume or restart.
-If no, continue to `create_uat_file`.
-
-**If no active sessions AND no $ARGUMENTS:**
-
-```
-No active UAT sessions.
-
-Provide a milestone ID to start testing (e.g., /declare:verify M-08)
-```
-
-**If no active sessions AND $ARGUMENTS provided:**
-
-Continue to `create_uat_file`.
-</step>
-
-<step name="find_plans">
-**Find what to test:**
-
-Locate the milestone directory under `.planning/milestones/`.
-
-```bash
-ls ".planning/milestones/${MILESTONE_DIR}/"*-PLAN.md 2>/dev/null
-```
-
-Read each PLAN.md to extract testable deliverables from the `produces` fields and task descriptions.
-</step>
-
-<step name="extract_tests">
-**Extract testable deliverables from milestone PLAN.md files:**
-
-Parse each PLAN.md for:
-1. **`produces` fields** — Explicit outputs listed per action/task
-2. **User-facing changes** — UI, workflows, interactions described in task objectives
-
-Focus on USER-OBSERVABLE outcomes, not implementation details.
-
-For each deliverable, create a test:
-- name: Brief test name
-- expected: What the user should see/experience (specific, observable)
-
-Examples:
-- Produces: "agents/declare-debugger.md — working debug agent"
-  → Test: "Declare Debugger Agent Exists"
-  → Expected: "File agents/declare-debugger.md exists with proper YAML frontmatter (name, description, tools, color) and contains all core sections: philosophy, hypothesis_testing, investigation_techniques, debug_file_protocol, execution_flow."
-
-- Produces: "commands/declare/verify.md — /declare:verify command"
-  → Test: "Verify Command Available"
-  → Expected: "File commands/declare/verify.md exists, references @workflows/verify.md, and accepts M-XX as argument."
-
-Skip internal/non-observable items (refactors, config tweaks, etc.).
-</step>
-
-<step name="create_uat_file">
-**Create UAT file with all tests:**
-
-```bash
-mkdir -p ".planning/milestones/${MILESTONE_DIR}"
-```
-
-Build test list from extracted deliverables.
-
-Create file at `.planning/milestones/{milestone_dir}/{milestone_id}-UAT.md`:
-
-```markdown
----
-status: testing
-milestone: {milestone_id}-{milestone_name}
-source: [list of PLAN.md files read]
-started: [ISO timestamp]
-updated: [ISO timestamp]
----
-
-## Current Test
-<!-- OVERWRITE each test - shows where we are -->
-
-number: 1
-name: [first test name]
-expected: |
-  [what user should observe]
-awaiting: user response
-
-## Tests
-
-### 1. [Test Name]
-expected: [observable behavior]
-result: [pending]
-
-### 2. [Test Name]
-expected: [observable behavior]
-result: [pending]
-
-...
-
-## Summary
-
-total: [N]
-passed: 0
-issues: 0
-pending: [N]
-skipped: 0
-
-## Gaps
-
-[none yet]
-```
-
-Proceed to `present_test`.
-</step>
-
-<step name="present_test">
-**Present current test to user:**
-
-Read Current Test section from UAT file.
-
-Display using checkpoint box format:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  CHECKPOINT: Verification Required                           ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Test {number}: {name}**
-
-{expected}
-
-──────────────────────────────────────────────────────────────
-→ Type "pass" or describe what's wrong
-──────────────────────────────────────────────────────────────
-```
-
-Wait for user response (plain text, no AskUserQuestion).
-</step>
-
-<step name="process_response">
-**Process user response and update file:**
-
-**If response indicates pass:**
-- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓"
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: pass
-```
-
-**If response indicates skip:**
-- "skip", "can't test", "n/a"
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: skipped
-reason: [user's reason if provided]
-```
-
-**If response is anything else:**
-- Treat as issue description
-
-Infer severity from description:
-- Contains: crash, error, exception, fails, broken, unusable → blocker
-- Contains: doesn't work, wrong, missing, can't → major
-- Contains: slow, weird, off, minor, small → minor
-- Contains: color, font, spacing, alignment, visual → cosmetic
-- Default if unclear: major
-
-Update Tests section:
-```
-### {N}. {name}
-expected: {expected}
-result: issue
-reported: "{verbatim user response}"
-severity: {inferred}
-```
-
-Append to Gaps section (structured YAML for diagnosis):
-```yaml
-- test_id: {N}
-  description: "{test name}"
-  expected: "{expected behavior from test}"
-  actual: "{verbatim user response}"
-  severity: {inferred}
-  root_cause: ""  # Filled by declare-debugger diagnosis
-  status: failed
-  artifacts: []   # Filled by diagnosis
-  missing: []     # Filled by diagnosis
-```
-
-**After any response:**
-
-Update Summary counts.
-Update frontmatter.updated timestamp.
-
-If more tests remain → Update Current Test, go to `present_test`
-If no more tests → Go to `complete_session`
-</step>
-
-<step name="resume_from_file">
-**Resume testing from UAT file:**
-
-Read the full UAT file.
-
-Find first test with `result: [pending]`.
-
-Announce:
-```
-Resuming: Milestone {milestone_id} UAT
-Progress: {passed + issues + skipped}/{total}
-Issues found so far: {issues count}
-
-Continuing from Test {N}...
-```
-
-Update Current Test section with the pending test.
-Proceed to `present_test`.
-</step>
-
-<step name="complete_session">
-**Complete testing and commit:**
-
-Update frontmatter:
-- status: complete
-- updated: [now]
-
-Clear Current Test section:
-```
-## Current Test
-
-[testing complete]
-```
-
-Commit the UAT file:
-```bash
-node dist/declare-tools.cjs commit "test({milestone_id}): complete UAT - {passed} passed, {issues} issues" --files ".planning/milestones/{milestone_dir}/{milestone_id}-UAT.md"
-```
-
-Present summary:
-```
-## UAT Complete: Milestone {milestone_id}
-
-| Result | Count |
-|--------|-------|
-| Passed | {N}   |
-| Issues | {N}   |
-| Skipped| {N}   |
-
-[If issues > 0:]
-### Issues Found
-
-[List from Issues section]
-```
-
-**If issues > 0:** Proceed to `diagnose_issues`
-
-**If issues == 0:**
-```
-All tests passed. Ready to continue.
-
-- `/declare:milestones` — View milestone status
-- `/declare:execute M-{next}` — Execute next milestone
-```
-</step>
-
-<step name="diagnose_issues">
-**Diagnose root causes before planning fixes:**
-
-```
----
-
-{N} issues found. Diagnosing root causes...
-
-Spawning parallel debug agents to investigate each issue.
-```
-
-For each gap in the UAT file:
-1. Spawn a `declare-debugger` agent in `goal: find_root_cause_only` mode
-2. Pass gap details as pre-filled symptoms (`symptoms_prefilled: true`)
-3. Collect root causes from each agent's ROOT CAUSE FOUND response
-4. Update UAT.md Gaps section with `root_cause` for each gap
-
-All agents run in parallel — diagnosis overhead is minimal.
-
-After all diagnoses complete, update UAT file with root causes, then proceed to `plan_gap_closure`.
-</step>
-
-<step name="plan_gap_closure">
-**Auto-plan fixes from diagnosed gaps:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DECLARE ► PLANNING FIXES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner for gap closure...
-```
-
-Spawn declare-planner in gap_closure mode with:
-- The diagnosed UAT file
-- Current STATE.md
-- Current milestone PLAN.md files as context
-
-On return:
-- **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
-- **PLANNING INCONCLUSIVE:** Report and offer manual intervention
-</step>
-
-<step name="verify_gap_plans">
-**Verify fix plans:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DECLARE ► VERIFYING FIX PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Reviewing fix plans...
-```
-
-Initialize: `iteration_count = 1`
-
-Review gap closure plans for completeness and correctness:
-- Each diagnosed gap has a corresponding fix plan
-- Fix plans address the root cause, not just symptoms
-- No missing steps or broken dependencies
-
-On review:
-- **PLANS VALID:** Proceed to `present_ready`
-- **ISSUES FOUND:** Return to plan_gap_closure with feedback (max 3 iterations)
-
-**If iteration_count >= 3:**
-
-Display: `Max iterations reached. {N} issues remain.`
-
-Offer options:
-1. Force proceed (execute despite issues)
-2. Provide guidance (user gives direction, retry)
-3. Abandon (exit, user runs `/declare:verify M-{milestone}` manually)
-
-Wait for user response.
-</step>
-
-<step name="present_ready">
-**Present completion and next steps:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DECLARE ► FIXES READY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Milestone {milestone_id}: {milestone_name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
-
-| Gap | Root Cause | Fix Plan |
-|-----|------------|----------|
-| {description 1} | {root_cause} | {action_id} |
-| {description 2} | {root_cause} | {action_id} |
-
-Plans verified and ready for execution.
-
-───────────────────────────────────────────────────────────────
-
-## Next Up
-
-**Execute fixes** — run fix plans
-
-`/clear` then `/declare:execute M-{milestone_id} --gaps-only`
-
-───────────────────────────────────────────────────────────────
-```
-</step>
-
-</process>
-
-<update_rules>
-**Batched writes for efficiency:**
-
-Keep results in memory. Write to file only when:
-1. **Issue found** — Preserve the problem immediately
-2. **Session complete** — Final write before commit
-3. **Checkpoint** — Every 5 passed tests (safety net)
-
-| Section | Rule | When Written |
-|---------|------|--------------|
-| Frontmatter.status | OVERWRITE | Start, complete |
-| Frontmatter.updated | OVERWRITE | On any file write |
-| Current Test | OVERWRITE | On any file write |
-| Tests.{N}.result | OVERWRITE | On any file write |
-| Summary | OVERWRITE | On any file write |
-| Gaps | APPEND | When issue found |
-
-On context reset: File shows last checkpoint. Resume from there.
-</update_rules>
-
-<severity_inference>
-**Infer severity from user's natural language:**
-
-| User says | Infer |
-|-----------|-------|
-| "crashes", "error", "exception", "fails completely" | blocker |
-| "doesn't work", "nothing happens", "wrong behavior" | major |
-| "works but...", "slow", "weird", "minor issue" | minor |
-| "color", "spacing", "alignment", "looks off" | cosmetic |
-
-Default to **major** if unclear. User can correct if needed.
-
-**Never ask "how severe is this?"** - just infer and move on.
-</severity_inference>
-
-<gap_format>
-**Gap YAML written to UAT.md on each issue found:**
-
-```yaml
-- test_id: {N}
-  description: "{test name}"
-  expected: "{expected behavior from test}"
-  actual: "{verbatim user response}"
-  severity: {blocker|major|minor|cosmetic}
-  root_cause: ""    # Populated by declare-debugger
-  status: failed
-  artifacts: []     # Populated by declare-debugger (files involved)
-  missing: []       # Populated by declare-debugger (what was missing)
-```
-
-This structured format feeds directly into the declare-debugger diagnosis mode and gap closure planning.
-</gap_format>
-
-<success_criteria>
-- [ ] UAT file created with all tests from milestone PLAN.md "produces" fields
-- [ ] Tests presented one at a time with expected behavior
-- [ ] User responses processed as pass/issue/skip
-- [ ] Severity inferred from description (never asked)
-- [ ] Batched writes: on issue, every 5 passes, or completion
-- [ ] Committed on completion
-- [ ] If issues: parallel declare-debugger agents diagnose root causes
-- [ ] Gap format includes test_id, description, expected, actual, severity, root_cause
-- [ ] If issues: fix plans created covering all diagnosed gaps
-- [ ] If issues: fix plans verified before presenting to user
-- [ ] Ready for `/declare:execute M-{id} --gaps-only` when complete
-</success_criteria>