qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/references/phase-argument-parsing.md

@@ -1,61 +0,0 @@
-# Phase Argument Parsing
-
-Parse and normalize phase arguments for commands that operate on phases.
-
-## Extraction
-
-From `$ARGUMENTS`:
-- Extract phase number (first numeric argument)
-- Extract flags (prefixed with `--`)
-- Remaining text is description (for insert/add commands)
-
-## Using qualia-tools
-
-The `find-phase` command handles normalization and validation in one step:
-
-```bash
-PHASE_INFO=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js find-phase "${PHASE}")
-```
-
-Returns JSON with:
-- `found`: true/false
-- `directory`: Full path to phase directory
-- `phase_number`: Normalized number (e.g., "06", "06.1")
-- `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
-
-## Manual Normalization (Legacy)
-
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
-
-```bash
-# Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validation
-
-Use `roadmap get-phase` to validate phase exists:
-
-```bash
-PHASE_CHECK=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js roadmap get-phase "${PHASE}")
-if [ "$(echo "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
-  echo "ERROR: Phase ${PHASE} not found in roadmap"
-  exit 1
-fi
-```
-
-## Directory Lookup
-
-Use `find-phase` for directory lookup:
-
-```bash
-PHASE_DIR=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js find-phase "${PHASE}" --raw)
-```

package/framework/qualia-framework/references/planning-config.md

@@ -1,195 +0,0 @@
-<planning_config>
-
-Configuration options for `.planning/` directory behavior.
-
-<config_schema>
-```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "qualia/phase-{phase}-{slug}",
-  "milestone_branch_template": "qualia/{milestone}-{slug}"
-}
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"qualia/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"qualia/{milestone}-{slug}"` | Branch template for milestone strategy |
-</config_schema>
-
-<commit_docs_behavior>
-
-**When `commit_docs: true` (default):**
-- Planning files committed normally
-- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
-- Full history of planning decisions preserved
-
-**When `commit_docs: false`:**
-- Skip all `git add`/`git commit` for `.planning/` files
-- User must add `.planning/` to `.gitignore`
-- Useful for: OSS contributions, client projects, keeping planning private
-
-**Using qualia-tools.js (preferred):**
-
-```bash
-# Commit with automatic commit_docs + gitignore checks:
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: update state" --files .planning/STATE.md
-
-# Load config via state load (returns JSON):
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js state load)
-# commit_docs is available in the JSON output
-
-# Or use init commands which include commit_docs:
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init execute-phase "1")
-# commit_docs is included in all init command outputs
-```
-
-**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
-
-**Conditional git operations:**
-
-```bash
-if [ "$COMMIT_DOCS" = "true" ]; then
-  git add .planning/STATE.md
-  git commit -m "docs: update state"
-fi
-```
-
-</commit_docs_behavior>
-
-<search_behavior>
-
-**When `search_gitignored: false` (default):**
-- Standard rg behavior (respects .gitignore)
-- Direct path searches work: `rg "pattern" .planning/` finds files
-- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
-
-**When `search_gitignored: true`:**
-- Add `--no-ignore` to broad rg searches that should include `.planning/`
-- Only needed when searching entire repo and expecting `.planning/` matches
-
-**Note:** Most Qualia operations use direct file reads or explicit paths, which work regardless of gitignore status.
-
-</search_behavior>
-
-<setup_uncommitted_mode>
-
-To use uncommitted mode:
-
-1. **Set config:**
-   ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
-   ```
-
-2. **Add to .gitignore:**
-   ```
-   .planning/
-   ```
-
-3. **Existing tracked files:** If `.planning/` was previously tracked:
-   ```bash
-   git rm -r --cached .planning/
-   git commit -m "chore: stop tracking planning docs"
-   ```
-
-</setup_uncommitted_mode>
-
-<branching_strategy_behavior>
-
-**Branching Strategies:**
-
-| Strategy | When branch created | Branch scope | Merge point |
-|----------|---------------------|--------------|-------------|
-| `none` | Never | N/A | N/A |
-| `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
-
-**When `git.branching_strategy: "none"` (default):**
-- All work commits to current branch
-- Standard Qualia behavior
-
-**When `git.branching_strategy: "phase"`:**
-- `execute-phase` creates/switches to a branch before execution
-- Branch name from `phase_branch_template` (e.g., `qualia/phase-03-authentication`)
-- All plan commits go to that branch
-- User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
-
-**When `git.branching_strategy: "milestone"`:**
-- First `execute-phase` of milestone creates the milestone branch
-- Branch name from `milestone_branch_template` (e.g., `qualia/v1.0-mvp`)
-- All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
-
-**Template variables:**
-
-| Variable | Available in | Description |
-|----------|--------------|-------------|
-| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
-| `{slug}` | Both | Lowercase, hyphenated name |
-| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
-
-**Checking the config:**
-
-Use `init execute-phase` which returns all config as JSON:
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init execute-phase "1")
-# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
-```
-
-Or use `state load` for the config values:
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js state load)
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
-```
-
-**Branch creation:**
-
-```bash
-# For phase strategy
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-
-# For milestone strategy
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-```
-
-**Merge options at complete-milestone:**
-
-| Option | Git command | Result |
-|--------|-------------|--------|
-| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
-| Merge with history | `git merge --no-ff` | Preserves all individual commits |
-| Delete without merging | `git branch -D` | Discard branch work |
-| Keep branches | (none) | Manual handling later |
-
-Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
-
-**Use cases:**
-
-| Strategy | Best for |
-|----------|----------|
-| `none` | Solo development, simple projects |
-| `phase` | Code review per phase, granular rollback, team collaboration |
-| `milestone` | Release branches, staging environments, PR per version |
-
-</branching_strategy_behavior>
-
-</planning_config>

package/framework/qualia-framework/references/questioning.md

@@ -1,141 +0,0 @@
-<questioning_guide>
-
-Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
-
-<philosophy>
-
-**You are a thinking partner, not an interviewer.**
-
-The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
-
-Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
-
-</philosophy>
-
-<the_goal>
-
-By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-
-- **Research** needs: what domain to research, what the user already knows, what unknowns exist
-- **Requirements** needs: clear enough vision to scope v1 features
-- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
-- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-
-A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-</the_goal>
-
-<how_to_question>
-
-**Start open.** Let them dump their mental model. Don't interrupt with structure.
-
-**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
-
-**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
-
-**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
-
-**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
-
-**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
-
-</how_to_question>
-
-<question_types>
-
-Use these as inspiration, not a checklist. Pick what's relevant to the thread.
-
-**Motivation — why this exists:**
-- "What prompted this?"
-- "What are you doing today that this replaces?"
-- "What would you do if this existed?"
-
-**Concreteness — what it actually is:**
-- "Walk me through using this"
-- "You said X — what does that actually look like?"
-- "Give me an example"
-
-**Clarification — what they mean:**
-- "When you say Z, do you mean A or B?"
-- "You mentioned X — tell me more about that"
-
-**Success — how you'll know it's working:**
-- "How will you know this is working?"
-- "What does done look like?"
-
-</question_types>
-
-<using_askuserquestion>
-
-Use AskUserQuestion to help users think by presenting concrete options to react to.
-
-**Good options:**
-- Interpretations of what they might mean
-- Specific examples to confirm or deny
-- Concrete choices that reveal priorities
-
-**Bad options:**
-- Generic categories ("Technical", "Business", "Other")
-- Leading options that presume an answer
-- Too many options (2-4 is ideal)
-
-**Example — vague answer:**
-User says "it should be fast"
-
-- header: "Fast"
-- question: "Fast how?"
-- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
-
-**Example — following a thread:**
-User mentions "frustrated with current tools"
-
-- header: "Frustration"
-- question: "What specifically frustrates you?"
-- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
-
-</using_askuserquestion>
-
-<context_checklist>
-
-Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
-
-- [ ] What they're building (concrete enough to explain to a stranger)
-- [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (observable outcomes)
-
-Four things. If they volunteer more, capture it.
-
-</context_checklist>
-
-<decision_gate>
-
-When you could write a clear PROJECT.md, offer to proceed:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-</decision_gate>
-
-<anti_patterns>
-
-- **Checklist walking** — Going through domains regardless of what they said
-- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
-- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
-- **Interrogation** — Firing questions without building on answers
-- **Rushing** — Minimizing questions to get to "the work"
-- **Shallow acceptance** — Taking vague answers without probing
-- **Premature constraints** — Asking about tech stack before understanding the idea
-- **User skills** — NEVER ask about user's technical experience. Claude builds.
-
-</anti_patterns>
-
-</questioning_guide>

package/framework/qualia-framework/references/tdd.md

@@ -1,263 +0,0 @@
-<overview>
-TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
-
-**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
-
-**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
-</overview>
-
-<when_to_use_tdd>
-## When TDD Improves Quality
-
-**TDD candidates (create a TDD plan):**
-- Business logic with defined inputs/outputs
-- API endpoints with request/response contracts
-- Data transformations, parsing, formatting
-- Validation rules and constraints
-- Algorithms with testable behavior
-- State machines and workflows
-- Utility functions with clear specifications
-
-**Skip TDD (use standard plan with `type="auto"` tasks):**
-- UI layout, styling, visual components
-- Configuration changes
-- Glue code connecting existing components
-- One-off scripts and migrations
-- Simple CRUD with no business logic
-- Exploratory prototyping
-
-**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
-→ Yes: Create a TDD plan
-→ No: Use standard plan, add tests after if needed
-</when_to_use_tdd>
-
-<tdd_plan_structure>
-## TDD Plan Structure
-
-Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
-
-```markdown
----
-phase: XX-name
-plan: NN
-type: tdd
----
-
-<objective>
-[What feature and why]
-Purpose: [Design benefit of TDD for this feature]
-Output: [Working, tested feature]
-</objective>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@relevant/source/files.ts
-</context>
-
-<feature>
-  <name>[Feature name]</name>
-  <files>[source file, test file]</files>
-  <behavior>
-    [Expected behavior in testable terms]
-    Cases: input → expected output
-  </behavior>
-  <implementation>[How to implement once tests pass]</implementation>
-</feature>
-
-<verification>
-[Test command that proves feature works]
-</verification>
-
-<success_criteria>
-- Failing test written and committed
-- Implementation passes test
-- Refactor complete (if needed)
-- All 2-3 commits present
-</success_criteria>
-
-<output>
-After completion, create SUMMARY.md with:
-- RED: What test was written, why it failed
-- GREEN: What implementation made it pass
-- REFACTOR: What cleanup was done (if any)
-- Commits: List of commits produced
-</output>
-```
-
-**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
-</tdd_plan_structure>
-
-<execution_flow>
-## Red-Green-Refactor Cycle
-
-**RED - Write failing test:**
-1. Create test file following project conventions
-2. Write test describing expected behavior (from `<behavior>` element)
-3. Run test - it MUST fail
-4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
-
-**GREEN - Implement to pass:**
-1. Write minimal code to make test pass
-2. No cleverness, no optimization - just make it work
-3. Run test - it MUST pass
-4. Commit: `feat({phase}-{plan}): implement [feature]`
-
-**REFACTOR (if needed):**
-1. Clean up implementation if obvious improvements exist
-2. Run tests - MUST still pass
-3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
-
-**Result:** Each TDD plan produces 2-3 atomic commits.
-</execution_flow>
-
-<test_quality>
-## Good Tests vs Bad Tests
-
-**Test behavior, not implementation:**
-- Good: "returns formatted date string"
-- Bad: "calls formatDate helper with correct params"
-- Tests should survive refactors
-
-**One concept per test:**
-- Good: Separate tests for valid input, empty input, malformed input
-- Bad: Single test checking all edge cases with multiple assertions
-
-**Descriptive names:**
-- Good: "should reject empty email", "returns null for invalid ID"
-- Bad: "test1", "handles error", "works correctly"
-
-**No implementation details:**
-- Good: Test public API, observable behavior
-- Bad: Mock internals, test private methods, assert on internal state
-</test_quality>
-
-<framework_setup>
-## Test Framework Setup (If None Exists)
-
-When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
-
-**1. Detect project type:**
-```bash
-# JavaScript/TypeScript
-if [ -f package.json ]; then echo "node"; fi
-
-# Python
-if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
-
-# Go
-if [ -f go.mod ]; then echo "go"; fi
-
-# Rust
-if [ -f Cargo.toml ]; then echo "rust"; fi
-```
-
-**2. Install minimal framework:**
-| Project | Framework | Install |
-|---------|-----------|---------|
-| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
-| Node.js (Vite) | Vitest | `npm install -D vitest` |
-| Python | pytest | `pip install pytest` |
-| Go | testing | Built-in |
-| Rust | cargo test | Built-in |
-
-**3. Create config if needed:**
-- Jest: `jest.config.js` with ts-jest preset
-- Vitest: `vitest.config.ts` with test globals
-- pytest: `pytest.ini` or `pyproject.toml` section
-
-**4. Verify setup:**
-```bash
-# Run empty test suite - should pass with 0 tests
-npm test  # Node
-pytest    # Python
-go test ./...  # Go
-cargo test    # Rust
-```
-
-**5. Create first test file:**
-Follow project conventions for test location:
-- `*.test.ts` / `*.spec.ts` next to source
-- `__tests__/` directory
-- `tests/` directory at root
-
-Framework setup is a one-time cost included in the first TDD plan's RED phase.
-</framework_setup>
-
-<error_handling>
-## Error Handling
-
-**Test doesn't fail in RED phase:**
-- Feature may already exist - investigate
-- Test may be wrong (not testing what you think)
-- Fix before proceeding
-
-**Test doesn't pass in GREEN phase:**
-- Debug implementation
-- Don't skip to refactor
-- Keep iterating until green
-
-**Tests fail in REFACTOR phase:**
-- Undo refactor
-- Commit was premature
-- Refactor in smaller steps
-
-**Unrelated tests break:**
-- Stop and investigate
-- May indicate coupling issue
-- Fix before proceeding
-</error_handling>
-
-<commit_pattern>
-## Commit Pattern for TDD Plans
-
-TDD plans produce 2-3 atomic commits (one per phase):
-
-```
-test(08-02): add failing test for email validation
-
-- Tests valid email formats accepted
-- Tests invalid formats rejected
-- Tests empty input handling
-
-feat(08-02): implement email validation
-
-- Regex pattern matches RFC 5322
-- Returns boolean for validity
-- Handles edge cases (empty, null)
-
-refactor(08-02): extract regex to constant (optional)
-
-- Moved pattern to EMAIL_REGEX constant
-- No behavior changes
-- Tests still pass
-```
-
-**Comparison with standard plans:**
-- Standard plans: 1 commit per task, 2-4 commits per plan
-- TDD plans: 2-3 commits for single feature
-
-Both follow same format: `{type}({phase}-{plan}): {description}`
-
-**Benefits:**
-- Each commit independently revertable
-- Git bisect works at commit level
-- Clear history showing TDD discipline
-- Consistent with overall commit strategy
-</commit_pattern>
-
-<context_budget>
-## Context Budget
-
-TDD plans target **~40% context usage** (lower than standard plans' ~50%).
-
-Why lower:
-- RED phase: write test, run test, potentially debug why it didn't fail
-- GREEN phase: implement, run test, potentially iterate on failures
-- REFACTOR phase: modify code, run tests, verify no regressions
-
-Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
-
-Single feature focus ensures full quality throughout the cycle.
-</context_budget>