plan-0-v2-constitution

name	plan-0-v2-constitution
description	Establish or refresh the project constitution and align the supporting norms documents before any planning phases begin. Re-entrant command that preserves user customizations during updates. Domain-aware v2.

Please deep think / ultrathink as this is a complex task.

plan-0-constitution (alias: phase-0-constitution)

Re-entrancy Support: This command is now re-entrant and will intelligently preserve user customizations when updating existing constitution files. Mark your custom content with <!-- USER CONTENT START --> and <!-- USER CONTENT END --> for guaranteed preservation across updates.

The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding (if not empty).

User input:

$ARGUMENTS

You are updating the project doctrine files in `docs/project-rules/`:
- `docs/project-rules/constitution.md`  (Constitution – guiding principles and governance)
- `docs/project-rules/rules.md`         (Rules – normative MUST/SHOULD statements)
- `docs/project-rules/idioms.md`        (Idioms – recurring patterns and examples)
- `docs/project-rules/architecture.md`  (Architecture – structure, boundaries, interaction contracts)

If any document uses placeholder tokens like `[ALL_CAPS_IDENTIFIER]`, your responsibility is to gather the values, fill or intentionally defer them, and keep all three files mutually consistent. Downstream templates or command prompts may reference these files; when they exist, update them last so they reflect the newly agreed doctrine.

--------------------------------
## Execution Flow (deterministic)
1) Resolve repository paths and detect mode
   - If your environment supplies a repository metadata helper (e.g., a prerequisites script defined in command front matter), run it once and parse the returned JSON. Otherwise derive values from the current working directory.
   - Set constants:
     CONST = `docs/project-rules/constitution.md`
     RULES = `docs/project-rules/rules.md`
     IDIOMS = `docs/project-rules/idioms.md`
     ARCH  = `docs/project-rules/architecture.md`
     TMPL  = `templates/`  # Optional helper content if present
   - Ensure parent directories exist; create them atomically when missing.

   **Domain Detection** (additive — skip if no domains present):
   - Check if `docs/domains/registry.md` exists → read all registered domains
   - Check if `docs/domains/domain-map.md` exists → read the domain architecture diagram
   - If domains directory exists but no registry → read `docs/domains/*/domain.md` files directly
   - If NO domain infrastructure exists: note "Domain system not yet initialized" — do NOT auto-create domain files (use `/plan-v2-extract-domain` when ready)
   - Store domain context for use in Steps 4 and 6 (governance and architecture sections)

   **Re-entrancy Detection**:
   - Check if any of CONST, RULES, IDIOMS, ARCH already exist
   - If ANY exist: **UPDATE MODE** - Will preserve user customizations
   - If NONE exist: **CREATE MODE** - Will create fresh documents
   - Display mode to user: "🔄 Updating existing constitution..." or "✨ Creating new constitution..."

2) Launch parallel context gatherers

**IMPORTANT**: Use **parallel subagent gatherers** for faster doctrine loading.

**Strategy**: Launch 4 parallel subagents (single message with 4 Task tool calls) to gather doctrine context concurrently.

**Subagent 1: Doctrine Loader (Re-entrancy Aware)**
"Load existing doctrine files and categorize content for preservation.

**Tasks**:
- For each of CONST, RULES, IDIOMS, ARCH:
  * If file exists:
    - Read fully and extract version number, [PLACEHOLDER] tokens, section headings, TODOs
    - Identify sections marked with `<!-- USER CONTENT START -->` and `<!-- USER CONTENT END -->`
    - Categorize each section as: 'generated' (safe to update), 'custom' (must preserve), or 'mixed' (needs merge)
    - Extract any filled placeholder values that replaced `[ALL_CAPS_TOKENS]`
    - Note custom sections not in standard template
  * If missing: Note for creation with minimal outline

**Categorization Rules**:
- Content between USER CONTENT markers = 'custom'
- Standard template sections without modifications = 'generated'
- Standard sections with significant user additions = 'mixed'
- Entirely new user-added sections = 'custom'

**Output**: JSON with {file_path, exists, version, placeholders[], headings[], todos[],
  sections[{name, type, content, preserve}], custom_additions[], filled_values{}}

**Return**: Results for all 4 files with preservation metadata."

**Subagent 2: Context Gatherer**
"Gather project governance and quality inputs from documentation.

**Priority order**: $ARGUMENTS > README.md > CONTRIBUTING.md > other handbooks

**Extract**:
- Guiding principles and values
- Quality/verification strategy and testing philosophy
- Delivery practices and governance rules
- Record source for each value (argument, README, etc.)

**Output**: JSON with {principles[], quality_strategy, delivery_practices, governance, sources{}}
Flag unknowns as 'UNKNOWN: <reason>' for TODO handling."

**Subagent 3: Template Scanner**
"Inventory templates and commands that reference doctrine.

**Scan**:
- skills/**/SKILL.md (and any `.claude/commands/*.md`) for references to constitution, rules, idioms, architecture
- templates/ directory for similar references

**Output**: JSON with {file_path, references_to[], link_format, expected_paths[]}
Note any hardcoded paths or placeholders that need updating."

**Subagent 4: Version Analyzer**
"Determine semantic version bump.

**Given**:
- Current versions from Subagent 1
- Changes from Subagent 2 ($ARGUMENTS and context)

**Apply rules**:
- MAJOR: Breaking changes to principles or governance
- MINOR: New principles/sections or materially expanded guidance
- PATCH: Clarifications or formatting adjustments

**Output**: JSON with {current_version, new_version, bump_type, rationale}
Include amendment date as ISO 8601."

**Wait for All Gatherers**: Block until all 4 subagents complete.

3) Synthesize gathered context and prepare merge strategy
   - Merge outputs from all 4 subagents into unified doctrine view
   - Conflict resolution: $ARGUMENTS > explicit docs > inferred > UNKNOWN
   - Build complete placeholder mapping: [TOKEN] → {value, source, confidence}
   - Validate version bump against actual changes detected
   - Create TODO list for any UNKNOWN values: "TODO(<FIELD>): <reason pending>"

   **Re-entrancy Merge Strategy** (if UPDATE MODE):
   - For each file, prepare merge plan:
     * Sections marked 'custom' → PRESERVE entirely
     * Sections marked 'generated' → UPDATE with new content
     * Sections marked 'mixed' → MERGE: Keep user additions, update framework
   - Preserve all filled placeholder values from existing files
   - Keep user-added sections not in template
   - Maintain existing TODOs that are still unresolved
   - Track what will change for user confirmation

   - Prepare inputs for Step 4 constitution drafting:
     * All placeholder values (filled or deferred, preferring existing)
     * Validated principles and practices (merging existing with new)
     * Quality strategy with tools/approaches
     * Template dependency map for Step 7 propagation
     * Final version number and Sync Impact Report data
     * Merge strategy per file with preservation instructions

4) Draft **docs/project-rules/constitution.md** (re-entrancy aware)
   **For CREATE MODE**:
   - Replace every placeholder. Standard sections:
     * Header with Title, Version, Ratification date, Last amended date
     * **Guiding Principles** – concise MUST/SHOULD statements with rationale
     * **Quality & Verification Strategy** – document how the team proves changes safe (tests, analysis, reviews). Highlight preferred tools per language when known; keep wording inclusive (examples are optional callouts).
     * **Delivery Practices** – planning cadence, documentation expectations, definition of done
     * **Governance** – amendment procedure, review cadence, compliance tracking
     * **Domain Governance** (include if domains detected OR project wants domain-based organization) –
       - Every source file belongs to a domain (or is uncategorized legacy)
       - Cross-domain imports use contracts only — no reaching into another domain’s internals
       - Domain boundaries are enforced by code review and plan structure
       - New domains are formalized via `/plan-v2-extract-domain` before code changes
       - Domain registry (`docs/domains/registry.md`) is the authoritative index
       - Domain map (`docs/domains/domain-map.md`) must stay current with contract edges
       - Business → infrastructure dependency: always allowed
       - Infrastructure → business dependency: never allowed
       - Business → business dependency: only via contracts
       - If no domains exist yet, note: "Domain governance applies once domains are established via `/plan-v2-extract-domain`"

   **For UPDATE MODE**:
   - Preserve all sections marked as 'custom' from Step 3 analysis
   - Update 'generated' sections with new framework content
   - For 'mixed' sections: Keep user additions, update framework parts
   - Maintain filled placeholder values from existing file
   - Add new standard sections if missing, mark with `<!-- NEWLY ADDED -->`
   - Keep user's custom sections even if not in template
   - Update version number appropriately (PATCH for clarifications, MINOR for new sections, MAJOR for breaking changes)

   - Prepend a **Sync Impact Report** HTML comment summarizing:
     * Mode: CREATE or UPDATE
     * Version bump: old → new with rationale
     * Sections preserved vs updated
     * Custom content retained
     * New sections added
     * Outstanding TODOs
     * Supporting docs/templates update status

5) Align **Rules & Idioms** (re-entrancy aware)
   **For UPDATE MODE**:
   - Apply same preservation strategy as constitution
   - Keep user's custom rules and examples
   - Update framework rules while preserving additions
   - Merge testing section carefully to keep project-specific policies

   - Write/update `rules.md` with enforceable statements ("MUST", "SHOULD") covering:
     * Source control hygiene and branching
     * Coding standards, naming, formatting
     * **Testing/verification expectations** (detailed guidance below)
     * Tooling or automation requirements (linters, CI, coverage, static analysis)

   - **Testing Section Requirements** (expand with TAD philosophy):
     The testing section in `rules.md` MUST include comprehensive guidance on:

     **1. Testing Philosophy**
     - Tests as executable documentation (TAD principles)
     - Quality over coverage: tests must "pay rent" via comprehension value
     - When to write tests vs when to skip them
     - Smart application of TDD (test-first when it adds value, not dogmatically)

     **2. Test Quality Standards**
     - Every test MUST explain **why it exists** (business/bug/regression reason)
     - Every test MUST document the **contract** it asserts (plain-English invariants)
     - Every test MUST include **usage notes** (how to call the API, gotchas)
     - Every test MUST describe its **quality contribution** (what failures it catches)
     - Every test SHOULD include a **worked example** (inputs/outputs summary)
     - Tests MUST use clear naming (Given-When-Then or equivalent behavioral format)

     **3. Scratch → Promote Workflow** (TAD approach)
     - Probe tests MAY be written in `tests/scratch/` for fast exploration/iteration
     - `tests/scratch/` MUST be excluded from CI (via .gitignore or CI config)
     - Tests MUST be promoted from scratch/ only if they add durable value
     - **Promotion heuristic**: Keep if Critical path, Opaque behavior, Regression-prone, or Edge case
     - Promoted tests MUST move to `tests/unit/` or `tests/integration/`
     - Promoted tests MUST include complete Test Doc comment blocks (5 required fields)
     - Non-valuable scratch tests MUST be deleted (keep learning notes in PR/log)

     **4. Test-Driven Development (TDD) Guidance**
     - TDD (test-first) SHOULD be used for: complex logic, algorithms, APIs, critical paths
     - TDD MAY be skipped for: simple operations, config changes, trivial wrappers
     - When using TDD, follow RED-GREEN-REFACTOR cycles
     - Tests written first MUST document expected behavior clearly
     - Avoid dogmatic TDD; apply when it adds value to design process

     **5. Test Reliability & Quality**
     - Tests MUST NOT use network calls (use fixtures/mocks for external dependencies)
     - Tests MUST NOT use sleep/timers (use time mocking if needed)
     - Tests MUST be deterministic (no flaky tests tolerated in main suite)
     - Tests SHOULD be reasonably fast to maintain quick feedback loops
     - Performance requirements (timing, resource limits) will be specified in the spec when needed

     **6. Test Organization**
     - `tests/scratch/` – fast probes, excluded from CI, temporary exploration
     - `tests/unit/` – isolated component tests with Test Doc blocks
     - `tests/integration/` – multi-component tests with Test Doc blocks
     - `tests/e2e/` or `tests/acceptance/` – full-system tests (if applicable)
     - `tests/fixtures/` – shared test data, realistic examples preferred

     **7. Mock Usage Policy**
     - Follow project-specific mock policy (Avoid | Targeted | Liberal - set in the spec's clarify pass, `/the-flow 1b`)
     - When mocking, document WHY the real dependency isn't used
     - Prefer real data/fixtures over mocks when practical
     - Mocks SHOULD be simple and behavior-focused, not implementation-focused

     **8. Test Documentation Format**
     Include language-appropriate Test Doc block format examples:

     ```typescript
     test('given_iso_date_when_parsing_then_returns_normalized_cents', () => {
       /*
       Test Doc:
       - Why: Prevent regression from #482 where AUD rounding truncated cents
       - Contract: parseInvoice returns {totalCents:number, date:ZonedDate} with exact cent accuracy
       - Usage Notes: Supply currency code; parser defaults to strict mode (throws on unknown fields)
       - Quality Contribution: Catches rounding/locale drift and date-TZ bugs; documents required fields
       - Worked Example: "1,234.56 AUD" → totalCents=123456; "2025-10-11+10:00" → ZonedDate(Australia/Brisbane)
       */
       // Arrange-Act-Assert with clear phases
     });
     ```

     ```python
     def test_given_iso_date_when_parsing_then_returns_normalized_cents():
         """
         Test Doc:
         - Why: Regression guard for rounding bug (#482)
         - Contract: Returns total_cents:int and timezone-aware datetime with exact cents
         - Usage Notes: Pass currency='AUD'; strict=True raises on unknown fields
         - Quality Contribution: Prevents silent money loss; showcases canonical call pattern
         - Worked Example: "1,234.56 AUD" -> 123_456; "2025-10-11+10:00" -> aware datetime
         """
         # Arrange-Act-Assert with clear phases
     ```

     **9. Complexity-First Estimation Policy (REQUIRED)**

     The constitution MUST enforce a **no-time policy** for all estimates and planning:

     - **Prohibition**: Never output or imply time, duration, or ETA in any form (hours, minutes, days, "quick", "fast", "soon", deadlines, etc.)
     - **Replacement**: All effort quantification MUST use the **Complexity Score (CS 1-5)** system
     - **Scoring rubric**: Compute points (0-2 each) for 6 factors, sum to CS:
       * **Surface Area (S)**: Files/modules touched; breadth of change (0=one file, 1=multiple files, 2=many files/cross-cutting)
       * **Integration Breadth (I)**: External libs/services/APIs/tooling (0=internal only, 1=one external, 2=multiple externals/unstable API)
       * **Data & State (D)**: Schema changes, migrations, concurrency (0=none, 1=minor tweaks, 2=non-trivial migration/concurrency)
       * **Novelty & Ambiguity (N)**: Requirements clarity, research needed (0=well-specified, 1=some ambiguity, 2=unclear specs/significant discovery)
       * **Non-Functional Constraints (F)**: Performance, security, compliance (0=standard gates, 1=moderate constraints, 2=strict/critical constraints)
       * **Testing & Rollout (T)**: Test depth, flags, staged rollout (0=unit only, 1=integration/e2e, 2=flags/staged rollout/backward compat)
     - **Mapping**: Total points P (0-12) maps to CS:
       * CS-1 (0-2): Trivial - isolated tweak, no new deps, unit test touchups
       * CS-2 (3-4): Small - few files, familiar code, maybe one internal integration
       * CS-3 (5-7): Medium - multiple modules, small migration or stable external API, integration tests
       * CS-4 (8-9): Large - cross-component, new dependency/service, meaningful migration, rollout plan
       * CS-5 (10-12): Epic - architectural change/new service, high uncertainty, phased rollout with flags

     **Mandatory output fields** wherever planning or reporting occurs:
     ```json
     {
       "complexity": {
         "score": 3,
         "label": "medium",
         "breakdown": {"surface": 1, "integration": 1, "data_state": 1, "novelty": 1, "nfr": 0, "testing_rollout": 1},
         "confidence": 0.75
       },
       "assumptions": ["Spec is final"],
       "dependencies": ["Payments service schema v2"],
       "risks": ["Downstream consumer expectations"],
       "phases": ["Design notes", "Implementation", "Tests", "Flagged rollout"]
     }
     ```

     **Enforcement rules**:
     - For CS ≥ 4, MUST include staged rollout, feature flags, and rollback plan in phases
     - Prefer complexity idioms: "scope", "risk", "breadth", "unknowns" over any time language
     - If uncertainty is high, ask clarifying questions and reflect in Novelty (N) + lower confidence
     - Self-check: If time words appear in drafts, replace with complexity reasoning or remove

     **Calibration examples** (include in idioms.md):
     - Rename a constant used in one file: S=0, I=0, D=0, N=0, F=0, T=0 → **CS-1 (trivial)**
     - Add new endpoint using existing service: S=1, I=1, D=1, N=1, F=0, T=1 → P=5 → **CS-3 (medium)**
     - Introduce new service with schema migration and staged rollout: S=2, I=2, D=2, N=2, F=1, T=2 → P=11 → **CS-5 (epic)**

   - Write `idioms.md` with illustrative patterns, directory conventions, and language-specific examples when relevant.
   - Keep references to the constitution explicit (e.g., link sections or quote identifiers). If any area is not yet defined, leave a TODO entry mirroring the constitution.

6) Maintain **architecture.md** (re-entrancy aware)
   **For UPDATE MODE**:
   - Preserve user's architectural decisions and custom diagrams
   - Update framework structure while keeping project-specific sections
   - Maintain technology stack choices and integration details
   - Keep custom anti-patterns and project-specific checklists

   - Capture/update the system's high-level structure: modules, services, layers, data flows, integration points.
   - Define boundaries and contracts (who may call whom, allowed dependencies, deployment targets).
   - **Domain Integration** (if domains detected): Reference `docs/domains/domain-map.md` for the authoritative domain architecture diagram. Architecture boundaries should align with domain boundaries. Document how domain contracts map to system-level interfaces.
   - Document technology-agnostic rules first; add stack-specific notes in dedicated subsections (e.g., "Example: Node service" / "Example: C# backend").
   - Track anti-patterns and reviewer checklists that should remain stable across implementations.

7) Propagate doctrine into helpers (if any)
   - For each file under `templates/` or command/skill directories (e.g. `skills/`, `.claude/commands/`) that references the constitution or rules, ensure links remain correct and language stays stack-neutral.
   - Where downstream workflows expect gates (e.g., "confirm plan aligns with rules"), keep the gate but phrase it generically.
   - Do not invent new templates; update only those already present.

8) Validate before writing
   - No document retains unresolved `[PLACEHOLDER]` tokens.
   - Version bumps and dates follow ISO `YYYY-MM-DD`.
   - Principles and rules are actionable, not vague aspirations.
   - Architecture doc reflects the latest agreed structure without contradicting Rules or Constitution.
   - Templates/commands (when touched) remain idempotent and reference the canonical paths exactly.

   **For UPDATE MODE - User Confirmation**:
   - Display summary of proposed changes:
     * "Will preserve: X custom sections, Y user values"
     * "Will update: Z framework sections"
     * "Will add: N new sections"
   - Show diff preview of significant changes
   - Ask: "Proceed with update? (backups will be created)"
   - If user declines, abort with no changes

9) Write files with intelligent merge
   **For CREATE MODE**:
   - Write CONST, RULES, IDIOMS, and ARCH with fresh content
   - Mark sections that users can customize with `<!-- USER CONTENT START -->` and `<!-- USER CONTENT END -->`

   **For UPDATE MODE**:
   - For each file, apply merge strategy from Step 3:
     * Preserve sections marked 'custom' completely
     * Update sections marked 'generated' with new content
     * Intelligently merge 'mixed' sections (keep user content, update framework)
   - Add protective markers around user content for future runs
   - Validate no user content was lost in the merge
   - Create backup of original files before writing (stored in `.constitution-backup/`)

   **For both modes**:
   - Apply the minimal set of edits needed for any templates or helper commands
   - Preserve contributor-authored content outside the edited blocks
   - Ensure all files remain internally consistent

10) Final summary (stdout)
   **For CREATE MODE**:
   - Report: "✨ Created new constitution and doctrine files"
   - Include version 1.0.0 and creation date
   - List all created files

   **For UPDATE MODE**:
   - Report: "🔄 Updated constitution and doctrine files"
   - Show version change: old → new with bump rationale
   - List what was preserved vs updated:
     * "Preserved: N custom sections, M filled values"
     * "Updated: X framework sections"
     * "Added: Y new sections"
   - If backups created, note location: `.constitution-backup/`

   **For both modes**:
   - List all modified paths with change type
   - Mention outstanding TODOs or follow-up owners if doctrine remains incomplete
   - Provide appropriate commit message:
     * CREATE: `docs: establish project constitution and doctrine files`
     * UPDATE: `docs: update constitution v{old} → v{new} while preserving customizations`

--------------------------------
## Synchronized doctrine (authoritative excerpts to enforce)

The following **must** be enforced across Constitution -> Rules & Idioms -> Plan/Tasks/Implementation:

1) **Documented Quality Strategy**
   - Capture how the team proves software is safe to release (automated tests, manual smoke tests, static analysis, runtime monitors).
   - Encourage technology-specific examples, but keep the core policy portable across stacks.

2) **Repeatable Tooling & Environments**
   - Specify required automation (CI jobs, linters, formatters, build scripts) and how contributors run them locally.
   - Note any cross-platform considerations (macOS, Linux, Windows/WSL).

3) **Coding & Review Standards**
   - Define expectations for naming, style, documentation, and code review checklists.
   - State how decisions trace back to the constitution (e.g., principle IDs or links).

4) **Architecture Guardrails**
   - Describe boundaries between major components, allowed dependencies, and integration hooks.
   - Include anti-patterns reviewers should watch for and escalation paths when architecture evolves.

5) **Domain Boundaries** (when domain system is active)
   - Cross-domain imports MUST use contracts (public interfaces) only.
   - Each plan phase should primarily target one domain.
   - Domain creation must be formalized before implementation begins.
   - Domain map must be updated when domain relationships change.
   - Business domains may depend on infrastructure; never the reverse.

6) **Change Governance**
   - Clarify who approves doctrine updates, how often reviews occur, and what evidence is required for compliance.

--------------------------------
## Acceptance Criteria (for this command)
- `docs/project-rules/constitution.md` is fully populated, versioned, and includes a Sync Impact Report.
- `docs/project-rules/{rules.md, idioms.md, architecture.md}` exist (or are created/updated) and reflect the same doctrine without contradictory guidance.
- **For UPDATE MODE**: All user customizations are preserved, no content is lost.
- **For CREATE MODE**: Files include protective markers for future customizations.
- Backups are created before updates (stored in `.constitution-backup/` with timestamp).
- No document retains unresolved placeholders; dates and versions adhere to the rules above.
- Any touched templates or command prompts reference the canonical doctrine paths and remain stack-neutral.
- If domains are detected, constitution includes Domain Governance section with cross-domain dependency rules.
- If domains are NOT detected, constitution works without domain references (domain governance is additive, not required).
- Final summary surfaces version bump, updated paths, preserved content metrics, and outstanding TODO follow-ups.
- User is shown preview and asked for confirmation before applying updates in UPDATE MODE.

--------------------------------
## Formatting & Style
- Use Markdown headings exactly as in templates; keep one blank line between sections; avoid trailing whitespace.
- Wrap rationale lines for readability (<100 chars where practical).
- Deterministic edits; idempotent if run twice without new inputs.

Canonical paths enforced by this command

• Constitution: docs/project-rules/constitution.md
• Rules: docs/project-rules/rules.md
• Idioms: docs/project-rules/idioms.md
• Architecture: docs/project-rules/architecture.md
• Templates directory: templates/
• Domain registry: docs/domains/registry.md (read-only — not created by this command)
• Domain map: docs/domains/domain-map.md (read-only — not created by this command)

Run this command once per project (or whenever the guiding principles change) before executing planning or implementation phases.

Next step (when happy): Run /the-flow 1a for research, /the-flow 1b to capture the feature specification, or /plan-v2-extract-domain to formalize existing code as a named domain.