ariadna 1.3.0 → 2.0.0

data/data/ariadna/workflows/verify-work.md

@@ -1,570 +1,33 @@
-<purpose>
-Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /ariadna:plan-phase --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>
-@~/.claude/ariadna/templates/UAT.md
-</template>
-
-<process>
-
-<step name="initialize" priority="first">
-If $ARGUMENTS contains a phase number, load context:
-
-```bash
-INIT=$(ariadna-tools init verify-work "${PHASE_ARG}")
-```
-
-Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
-</step>
-
-<step name="check_active_session">
-**First: Check for active UAT sessions**
-
-```bash
-find .ariadna_planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
-```
-
-**If active sessions exist AND no $ARGUMENTS provided:**
-
-Read each file's frontmatter (status, phase) and Current Test section.
-
-Display inline:
-
-```
-## Active UAT Sessions
-
-| # | Phase | Status | Current Test | Progress |
-|---|-------|--------|--------------|----------|
-| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
-| 2 | 05-auth | testing | 1. Login Form | 0/4 |
-
-Reply with a number to resume, or provide a phase number 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 phase number → Treat as new session, go to `create_uat_file`
-
-**If active sessions exist AND $ARGUMENTS provided:**
-
-Check if session exists for that phase. 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 phase number to start testing (e.g., /ariadna:verify-work 4)
-```
-
-**If no active sessions AND $ARGUMENTS provided:**
-
-Continue to `create_uat_file`.
-</step>
-
-<step name="find_summaries">
-**Find what to test:**
-
-Use `phase_dir` from init (or run init if not already done).
-
-```bash
-ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
-```
-
-Read each SUMMARY.md to extract testable deliverables.
-</step>
-
-<step name="extract_tests">
-**Extract testable deliverables from SUMMARY.md:**
-
-Parse for:
-1. **Accomplishments** - Features/functionality added
-2. **User-facing changes** - UI, workflows, interactions
-
-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:
-- Accomplishment: "Added comment threading with infinite nesting"
-  → Test: "Reply to a Comment"
-  → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
-
-Skip internal/non-observable items (refactors, type changes, etc.).
-</step>
-
-<step name="create_uat_file">
-**Create UAT file with all tests:**
-
-```bash
-mkdir -p "$PHASE_DIR"
-```
-
-Build test list from extracted deliverables.
-
-Create file:
-
-```markdown
 ---
-status: testing
-phase: XX-name
-source: [list of SUMMARY.md files]
-started: [ISO timestamp]
-updated: [ISO timestamp]
+name: verify-work
+description: Validate that a phase or milestone achieved its goals — goal-backward, not task-backward
 ---
 
-## 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]
-```
-
-Write to `.ariadna_planning/phases/XX-name/{phase}-UAT.md`
-
-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 plan-phase --gaps):
-```yaml
-- truth: "{expected behavior from test}"
-  status: failed
-  reason: "User reported: {verbatim user response}"
-  severity: {inferred}
-  test: {N}
-  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]`.
+## Goal
+Confirm that what was built actually delivers the phase or milestone goal, not merely that tasks were completed. Produces a VERIFICATION.md with pass/fail/gap status and feeds gaps back into planning.
 
-Announce:
-```
-Resuming: Phase {phase} 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:
+## Context Loading
 ```bash
-ariadna-tools commit "test({phase}): complete UAT - {passed} passed, {issues} issues" --files ".ariadna_planning/phases/XX-name/{phase}-UAT.md"
-```
-
-Present summary:
-```
-## UAT Complete: Phase {phase}
-
-| 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.
-
-- `/ariadna:plan-phase {next}` — Plan next phase
-- `/ariadna:execute-phase {next}` — Execute next phase
-```
-</step>
-
-<step name="diagnose_issues">
-**Diagnose root causes before planning fixes:**
-
+INIT=$(ariadna-tools init verify-work "${PHASE_OR_MILESTONE_ARG}")
 ```
----
-
-{N} issues found. Diagnosing root causes...
-
-Spawning parallel debug agents to investigate each issue.
-```
-
-- Load diagnose-issues workflow
-- Follow @~/.claude/ariadna/workflows/diagnose-issues.md
-- Spawn parallel debug agents for each issue
-- Collect root causes
-- Update UAT.md with root causes
-- Proceed to `plan_gap_closure`
-
-Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
-</step>
-
-<step name="plan_gap_closure">
-**Auto-plan fixes from diagnosed gaps:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Ariadna ► PLANNING FIXES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner for gap closure...
-```
-
-Spawn ariadna-planner in --gaps mode:
-
-```
-Task(
-  prompt="""
-<planning_context>
-
-**Phase:** {phase_number}
-**Mode:** gap_closure
-
-**UAT with diagnoses:**
-@.ariadna_planning/phases/{phase_dir}/{phase}-UAT.md
-
-**Project State:**
-@.ariadna_planning/STATE.md
-
-**Roadmap:**
-@.ariadna_planning/ROADMAP.md
-
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /ariadna:execute-phase
-Plans must be executable prompts.
-</downstream_consumer>
-""",
-  subagent_type="ariadna-planner",
-  model="{planner_model}",
-  description="Plan gap fixes for Phase {phase}"
-)
-```
-
-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 with checker:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Ariadna ► VERIFYING FIX PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning plan checker...
-```
-
-Initialize: `iteration_count = 1`
-
-Spawn ariadna-plan-checker:
-
-```
-Task(
-  prompt="""
-<verification_context>
-
-**Phase:** {phase_number}
-**Phase Goal:** Close diagnosed gaps from UAT
-
-**Plans to verify:**
-@.ariadna_planning/phases/{phase_dir}/*-PLAN.md
-
-</verification_context>
-
-<expected_output>
-Return one of:
-- ## VERIFICATION PASSED — all checks pass
-- ## ISSUES FOUND — structured issue list
-</expected_output>
-""",
-  subagent_type="ariadna-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} fix plans"
-)
-```
-
-On return:
-- **VERIFICATION PASSED:** Proceed to `present_ready`
-- **ISSUES FOUND:** Proceed to `revision_loop`
-</step>
-
-<step name="revision_loop">
-**Iterate planner ↔ checker until plans pass (max 3):**
-
-**If iteration_count < 3:**
-
-Display: `Sending back to planner for revision... (iteration {N}/3)`
-
-Spawn ariadna-planner with revision context:
-
-```
-Task(
-  prompt="""
-<revision_context>
-
-**Phase:** {phase_number}
-**Mode:** revision
-
-**Existing plans:**
-@.ariadna_planning/phases/{phase_dir}/*-PLAN.md
-
-**Checker issues:**
-{structured_issues_from_checker}
-
-</revision_context>
-
-<instructions>
-Read existing PLAN.md files. Make targeted updates to address checker issues.
-Do NOT replan from scratch unless issues are fundamental.
-</instructions>
-""",
-  subagent_type="ariadna-planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
-```
-
-After planner returns → spawn checker again (verify_gap_plans logic)
-Increment iteration_count
-
-**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 /ariadna:plan-phase manually)
-
-Wait for user response.
-</step>
-
-<step name="present_ready">
-**Present completion and next steps:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Ariadna ► FIXES READY ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
-
-| Gap | Root Cause | Fix Plan |
-|-----|------------|----------|
-| {truth 1} | {root_cause} | {phase}-04 |
-| {truth 2} | {root_cause} | {phase}-04 |
-
-Plans verified and ready for execution.
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Execute fixes** — run fix plans
-
-`/clear` then `/ariadna:execute-phase {phase} --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:**
+Returns: `summary_paths[]` (SUMMARY.md files to verify against), `phase_dir`, `memory_dir`, `verifier_model`, `phase_number`, `phase_name`, `has_verification`.
 
-| 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 |
+Also read: `@~/.claude/skills/rails-backend/SKILL.md` for expected Rails patterns, and load security + performance Skills in the verifier prompt for non-functional checks.
 
-Default to **major** if unclear. User can correct if needed.
+## Constraints
+- Spawn `ariadna-verifier` agent; verifier checks goal achievement against the codebase, not just SUMMARY.md claims
+- Load security Skills (`@~/.claude/skills/rails-security/SKILL.md`) and performance Skills (`@~/.claude/skills/rails-performance/SKILL.md`) in the verifier prompt
+- Phase scope: verify one phase goal; milestone scope: verify all phases in the milestone — same workflow, different `--scope` argument
+- Verifier must check `must_haves` from plan frontmatter against actual files on disk — no credit for "plan says done"
+- If `has_verification: true`, offer to re-verify or show existing report
 
-**Never ask "how severe is this?"** - just infer and move on.
-</severity_inference>
+## Success Criteria
+- VERIFICATION.md exists in `phase_dir` with `status: passed | human_needed | gaps_found`
+- No critical gaps left unaddressed (minor gaps acceptable with notes)
+- Human-needed items listed explicitly so the user knows what to test manually
 
-<success_criteria>
-- [ ] UAT file created with all tests from SUMMARY.md
-- [ ] 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 debug agents diagnose root causes
-- [ ] If issues: ariadna-planner creates fix plans (gap_closure mode)
-- [ ] If issues: ariadna-plan-checker verifies fix plans
-- [ ] If issues: revision loop until plans pass (max 3 iterations)
-- [ ] Ready for `/ariadna:execute-phase --gaps-only` when complete
-</success_criteria>
+## On Completion
+- Update `memory/progress.md` with verification status and gap count
+- If `gaps_found`: display gap summary and offer `/ariadna:plan-phase {N} --gaps` to create fix plans
+- If `human_needed`: present items for manual testing; wait for user confirmation before marking verified
+- If `passed`: mark phase/milestone verified in STATE.md and ROADMAP.md

data/data/commands/ariadna/add-phase.md

@@ -7,33 +7,22 @@ allowed-tools:
   - Write
   - Bash
 ---
-
 <objective>
 Add a new integer phase to the end of the current milestone in the roadmap.
 
-Routes to the add-phase workflow which handles:
-- Phase number calculation (next sequential integer)
-- Directory creation with slug generation
-- Roadmap structure updates
-- STATE.md roadmap evolution tracking
+Handles: next phase number calculation, directory creation, roadmap entry insertion, STATE.md roadmap evolution tracking.
 </objective>
 
-<execution_context>
-@.ariadna_planning/ROADMAP.md
-@.ariadna_planning/STATE.md
-@~/.claude/ariadna/workflows/add-phase.md
-</execution_context>
+<context>
+Description: $ARGUMENTS
 
-<process>
-**Follow the add-phase workflow** from `@~/.claude/ariadna/workflows/add-phase.md`.
+Follow the workflow in `~/.claude/ariadna/workflows/add-phase.md` end-to-end.
+</context>
 
-The workflow handles all logic including:
-1. Argument parsing and validation
-2. Roadmap existence checking
-3. Current milestone identification
-4. Next phase number calculation (ignoring decimals)
-5. Slug generation from description
-6. Phase directory creation
-7. Roadmap entry insertion
-8. STATE.md updates
+<process>
+1. Validate $ARGUMENTS provided; error with usage if missing.
+2. Run `ariadna-tools init phase-op "0"` — check `roadmap_exists`.
+3. Run `ariadna-tools phase add "$ARGUMENTS"` — calculates next number, creates directory, updates ROADMAP.md.
+4. Update STATE.md "Roadmap Evolution" section with entry.
+5. Display new phase number, directory, and next step: `/ariadna:plan-phase {N}`.
 </process>