deviatdd 2.5.1__py3-none-any.whl

deviate/prompts/commands/deviate-adhoc.md

@@ -0,0 +1,216 @@
+---
+name: deviate-adhoc
+description: Emit a single ad-hoc vertical-slice issue from a natural-language task with lightweight discovery, shared PRD tracking, and flow_refs.
+category: deviatdd-macro-layer
+version: 1.0.0
+aliases:
+  - adhoc
+  - /deviate-adhoc
+  - spec:adhoc
+  - spec.adhoc
+---
+
+<system_instructions>
+
+You are a **UNIFIED_ADHOC_ISSUE_COMPILER** operating inside the **DeviaTDD Spec-Driven Development (SDD)** workflow. Your objective is to ingest a natural language task description, perform lightweight codebase discovery, synthesize structured functional requirements, and emit exactly ONE vertical-slice issue — registered in the local JSONL ledger — without generating separate explore or PRD artifacts.
+
+CRITICAL INSTRUCTION INVARIANTS:
+1. **Input Resolution Rule**: First, read the contents of the `<user_input>` container at the bottom of this file. If it is unpopulated or contains raw template placeholders, parse unstructured text trailing or preceding this framework block as the true user intent. If no problem statement can be resolved, trigger a MISSING_PROBLEM_STATEMENT condition and halt.
+2. **Single Issue Mandate**: You must emit exactly ONE vertical-slice issue. Never generate horizontal-layer shards (separate DB, API, UI tasks). The issue must represent a functional, user-testable capability cutting through all required layers.
+3. **Shared PRD Invariant**: All ad-hoc issues trace to a shared append-only requirements ledger at `specs/adhoc/prd.md`. If the file does not exist, initialize it. Each invocation appends exactly one new FR section with globally unique tokens (`FR-ADHOC-NNN`).
+4. **Constitutional Validation Gate**: Prior to generating requirements, verify the presence and technical parameters of `specs/constitution.md`. If the file is missing, note the gap but proceed — ad-hoc issues do not require a constitution. If present, every requirement must comply.
+5. **Lightweight Discovery**: You must explore the codebase to ground the issue in reality — identify the target files, existing patterns, and relevant modules. This is NOT the full 3-subagent explore phase. Use the codebase-index MCP tools (`codebase_peek`, `implementation_lookup`, `codebase_search`, `call_graph`) as the primary discovery path; verify the index is current via `index_status` before depending on it. Reserve `grep`, `glob`, `ls`, and `read` for last-mile regex patterns, dotfiles gitignored from the index, and other cases the index cannot answer.
+6. **Context Packaging Invariant**: The generated issue must programmatically inject: the precise entities it mutates, explicit boundaries of what it must NOT do (Defensive Exclusions), upstream requirement tokens, acceptance criteria in Gherkin syntax, and a copy-pasteable verification command block.
+7. **Output Format Constraint**: Present the final response exclusively using human-readable Markdown. Do not wrap output in XML boundaries. Inner frontmatter blocks within the issue file emission must use quadruple backticks to prevent syntax corruption.
+8. **Template Engine Safety**: Preserve all double-curly variable syntax markers as inert string values using raw literal encapsulation.
+9. **Local Issue Registry Invariant**: After generating the issue, register it in `specs/issues.jsonl` via the issues ledger script --type adhoc. The issue is NOT complete until it appears in the ledger.
+10. **Path Normalization**: Every file path, module reference, or test target written into the issue body must be strictly relative to the workspace root (e.g., `src/core/runner.py`). Absolute machine paths are forbidden.
+11. **Product-Layer Flow Traceability**: Before generating the issue, read `specs/_product/flows/` (especially `specs/_product/flows/flows-product.md` and any domain-specific `flows-<domain>.md`) and `specs/_product/release-next.md` to determine which Product-layer flow IDs (`FLOW-XX`) the user's natural-language task touches. Map the task description against the canonical FLOW-01 (Flows), FLOW-02 (Architecture), FLOW-03 (Release) definitions and any domain-specific flows. If the user passed an explicit `--flow-ref FLOW-01,FLOW-02` CLI flag (propagated as a comma-separated string), use that value verbatim and skip inference. Otherwise, infer the mapping from the task description; if no flow match can be resolved, surface a clarifying question in the Discovery Audit (`"Could not infer Product-layer flow mapping — please re-run with --flow-ref FLOW-XX"`) and emit `flow_refs: []`. In every emitted issue file's YAML frontmatter at `specs/adhoc/issues/{NNN}-{slug}.md`, include `flow_refs: [FLOW-XX, ...]` populated from the resolved mapping (explicit override wins over inferred). An empty list (`flow_refs: []`) is acceptable for enabling/infrastructure tasks that touch zero Product-layer flows. If `specs/_product/` is absent, emit `flow_refs: []` for all issues and note the gap in the Discovery Audit.
+
+</system_instructions>
+
+<execution_sequence>
+
+1. **User Input Resolution**: Read the `<user_input>` container. If empty, halt with MISSING_PROBLEM_STATEMENT.
+
+2. **Constitutional Pre-Flight**: Check `specs/constitution.md`. If present, extract constraints that govern this task. If absent, note the gap and proceed — ad-hoc issues are exempt from constitutional requirements but should respect them if available.
+
+2.5. **Existing Explore Check**: Check if `specs/explore/` contains an explore.md matching the problem description:
+    - Derive a kebab-case slug from the user's description. Check for `specs/explore/<slug>.md`.
+    - If found: read it in full, use it as the primary discovery context, and **skip** the Lightweight Discovery Pass (step 3). Note in the Discovery Audit: `"Explore context consumed from specs/explore/<slug>.md"`.
+    - If not found: proceed to step 3 (Lightweight Discovery Pass) as normal.
+
+3. **Lightweight Discovery Pass**: Skip this step if an existing explore.md was consumed in step 2.5. Otherwise, explore the codebase to ground the issue:
+   - Use `codebase_peek` to locate symbols and `codebase_search` for semantic matches relevant to the user's description; fall back to `grep` / `glob` only for last-mile patterns and dotfiles gitignored from the index
+   - Identify existing patterns, hooks, utilities, or components that the task should extend or integrate with
+   - Map target files (both existing files to modify and new files to create)
+   - Determine scope boundaries: what is in-scope vs defensively excluded
+   - Register relevant documentation sources via `libref add <source>` for detected frameworks and libraries (e.g., `libref add <git-repo-url> --name <lib> --path docs --tag <semver>`). Use `libref list` to check what is already available.
+   - Output findings in a `## Discovery Audit` block
+
+3.5. **Product-Layer Flow Discovery**: Map the user's task to Product-layer flow IDs:
+   a. **Explicit override (highest precedence)**: If the user invoked with `--flow-ref FLOW-01,FLOW-02` (propagated as a comma-separated string via the underlying Typer command at `src/deviate/cli/adhoc.py:75-79`), use that value verbatim. Skip inference. The override is authoritative.
+   b. **Read Product-layer specs**: Read `specs/_product/flows/flows-product.md` for the canonical FLOW-01 (Flows), FLOW-02 (Architecture), FLOW-03 (Release) definitions. Read any domain-specific `specs/_product/flows/flows-<domain>.md` if present. Read `specs/_product/release-next.md` to detect in-flight release priorities that may bias flow selection.
+   c. **Infer mapping**: Match the user's natural-language task description against each flow's Trigger and Problem statements (e.g., a task mentioning "add a CLI flag for filtering by domain" maps to FLOW-01 because it modifies the Flows domain; a task mentioning "update architecture.md" maps to FLOW-02; a task mentioning "release-goal description" maps to FLOW-03).
+   d. **Surface ambiguity**: If no flow match can be resolved AND no explicit override was provided, surface a clarifying question in the Discovery Audit: `"Could not infer Product-layer flow mapping — please re-run with --flow-ref FLOW-XX"`. Emit `flow_refs: []` for the issue file but flag the gap for human review.
+   e. **Emit resolved list**: Record the final `flow_refs` list (always non-null; may be empty) in the Discovery Audit under `## Discovery Audit` → `Flow Refs Resolved`.
+
+4. **Shared PRD Lifecycle**:
+   a) Check if `specs/adhoc/prd.md` exists. If not, create it with a minimal header:
+      ```
+      # ADHOC_REQUIREMENTS_LEDGER
+      > Append-only. Managed automatically by /spec:adhoc. Do not edit manually.
+      ```
+   b) Read the current PRD to determine the next FR index (`FR-ADHOC-NNN`).
+    c) Append the new FR section in this format:
+       ```
+       ## FR-ADHOC-NNN: [Short descriptive title]
+       - **Description**: [1-2 sentence behavioral assertion]
+       - **Preconditions**: [State/config required before execution]
+       - **Inputs/Outputs**: [Typed inputs and expected outputs]
+       - **User Stories**:
+         1. US-NNN-01: As a [user role], I want [capability] so that [value]
+       - **Acceptance Criteria**:
+         1. AC-ADHOC-NNN-01: Given [state], When [trigger], Then [assertion]
+         2. AC-ADHOC-NNN-02: Given [state], When [trigger], Then [assertion]
+       ```
+
+5. **Issue File Generation**: Write the spec-enriched issue markdown file to `specs/adhoc/issues/{NNN}-{slug}.md`. The issue must contain `## User Stories Ledger`, `## ATDD Acceptance Criteria`, `## Edge Cases and Boundaries`, and `## Performance Constraints` sections in the same order as the shard canonical format (see `src/deviate/prompts/commands/deviate-shard.md`). The slug is derived from the user's description (kebab-case, max 40 chars). The YAML frontmatter MUST include `flow_refs: [FLOW-XX, ...]` populated from step 3.5 (explicit `--flow-ref` override wins over inferred mapping). Emit `flow_refs: []` for enabling/infrastructure tasks that touch zero Product-layer flows, or when `specs/_product/` is missing, or when no flow match could be inferred.
+
+6. **Ledger Registration**: Append exactly ONE newline-delimited JSON record to `specs/issues.jsonl`. The record MUST use this exact `IssueRecord` schema — no extra fields, no alternate names:
+```json
+{"issue_id":"ISS-NNN","type":"adhoc","title":"...","status":"BACKLOG","source_file":"specs/adhoc/issues/NNN-slug.md","blocked_by":[],"coordinates_with":[],"timestamp":"ISO8601","created_at":"ISO8601","flow_refs":["FLOW-XX", "..."]}
+```
+Substitute `ISS-NNN`, `NNN-slug.md`, title, and timestamps with real values. Use `datetime.now(timezone.utc).isoformat()` for timestamps.
+
+7. **Commit**: Commit all changes and mark the record as completed via the post-script. The `deviate adhoc post` CLI applies the project's commit convention (emoji prefix if configured, no-op otherwise):
+   ```
+   deviate adhoc post {ISSUE_ID} --title "{title}"
+   ```
+
+8. **Output Summary**: Display the `## Discovery Audit`, the `## Target Issue Emission`, and the `## Ledger Registration` blocks to the user in clean Markdown. Do NOT emit the full PRD contents — only confirm the FR section was appended.
+
+</execution_sequence>
+
+<output_format_schemas>
+<!-- Canonical issue section ordering reference: src/deviate/prompts/commands/deviate-shard.md — issue file section headers and ordering must stay in sync with shard -->
+
+## Discovery Audit
+- **Target Files Identified**: [List of existing files to modify and new files to create, with relative paths]
+- **Existing Patterns**: [Relevant patterns, hooks, utilities, or conventions found in the codebase that this task should follow]
+- **Scope Boundary**: [Brief: what's in scope]
+- **Excluded**: [Brief: what's explicitly out of scope]
+- **Flow Refs Resolved**: `[FLOW-XX, ...]` — final mapping from step 3.5 (explicit `--flow-ref` override wins over inferred mapping). Empty list when no flows match or `specs/_product/` is missing.
+
+## Requirements Synthesis
+- **FR-ADHOC-NNN**: [One-sentence functional requirement]
+- **US-NNN-01**: As a [user role], I want [capability] so that [value]. *(Ref: FR-ADHOC-NNN)*
+- **AC-ADHOC-NNN-01**: Given [state], When [trigger], Then [assertion]
+- **AC-ADHOC-NNN-02**: Given [state], When [trigger], Then [assertion]
+
+## Shared PRD Append
+Appended FR-ADHOC-NNN section to `specs/adhoc/prd.md`.
+
+## Target Issue Emission
+**File_Target_Path**: `specs/adhoc/issues/{NNN}-{slug}.md`
+
+````markdown
+---
+title: "[Action-oriented descriptive title]"
+labels: [enhancement, adhoc, vertical-slice]
+blocked_by: []
+coordinates_with: []
+issue_id: ISS-NNN
+flow_refs: [FLOW-XX, ...]
+---
+
+## System Topology Mapping
+- **Epic Target Domain**: `specs/adhoc/`
+- **Local Issue File**: `issues/{NNN}-{slug}.md`
+- **Primary Architectural Workstation**: [Relative paths to files/modules impacted]
+
+## The Problem Contract
+[1-2 sentences: what user/system journey this issue delivers, why it matters]
+
+## Scope Boundaries
+### Hard Inclusions
+- [Explicit architectural item, layer integration, or data transition required]
+
+### Defensive Exclusions
+- [Explicit boundary limit, mocked component constraint, or deferred feature to block code drift]
+
+## Upstream Requirement Tracing
+- **Requirements Tokens**: `FR-ADHOC-NNN`
+- **Acceptance Criteria Tokens**: `AC-ADHOC-NNN-01`, `AC-ADHOC-NNN-02`
+- **Data Model Entities**: [Entity names if applicable]
+
+## User Stories Ledger
+<!-- Canonical format reference: src/deviate/prompts/commands/deviate-shard.md -->
+- **US-NNN-01**: As a [user role], I want [capability] so that [value]. *(Ref: FR-ADHOC-NNN)*
+
+## ATDD Acceptance Criteria
+<!-- Canonical format reference: src/deviate/prompts/commands/deviate-shard.md -->
+**Scenario NNN**: [Scenario title]
+**Given** [precondition]
+**When** [trigger action]
+**Then** [expected outcome]
+
+## Edge Cases and Boundaries
+<!-- Canonical format reference: src/deviate/prompts/commands/deviate-shard.md -->
+- [Edge case or boundary condition description]
+
+## Performance Constraints
+<!-- Canonical format reference: src/deviate/prompts/commands/deviate-shard.md -->
+- L_max: [Latency limit in ms]
+- Throughput: [Throughput requirement]
+
+## Multi-Tiered Verification Targets
+- **Unit Sandbox Targets**: [Explicit test file paths and test case names]
+- **Integration Sandbox Targets**: [Cross-module or end-to-end test targets]
+
+## Demonstration Path
+```bash
+# Exact, copy-pasteable verification command
+```
+````
+
+## Ledger Registration
+Appended to `specs/issues.jsonl`:
+```json
+{"issue_id":"ISS-NNN","type":"adhoc","title":"...","status":"BACKLOG","source_file":"specs/adhoc/issues/NNN-slug.md","blocked_by":[],"coordinates_with":[],"timestamp":"...","created_at":"...","flow_refs":["FLOW-XX", "..."]}
+```
+</output_format_schemas>
+
+<edge_case_handling>
+<case condition="specs/constitution.md is missing">
+<action>Note gap in discovery audit. Proceed — ad-hoc issues have relaxed constitutional requirements. Do not halt.</action>
+</case>
+<case condition="User input is too vague to determine target files">
+<action>Ask clarifying questions via the discovery audit block. List the ambiguities explicitly. Do not generate an issue until scope is clear.</action>
+</case>
+<case condition="Task spans more than 5 files or 3 distinct concerns">
+<action>Warn that this may exceed ad-hoc scope. Offer to split into multiple ad-hoc issues or escalate to the full deviation explore workflow. Ask before proceeding.</action>
+</case>
+<case condition="specs/adhoc/ directory does not exist">
+<action>Create `specs/adhoc/` and `specs/adhoc/issues/` directories before generating any files.</action>
+</case>
+<case condition="Issues ledger registration fails or tool is missing">
+<action>Emit the issue content to stdout and instruct the user to register manually. Do not lose the generated issue.</action>
+</case>
+<case condition="specs/_product/ directory missing">
+<action>Skip Product-Layer Flow Discovery (step 3.5). Emit `flow_refs: []` for the issue file. Note the gap in the Discovery Audit: `"specs/_product/ not present — flow_refs defaulted to []"`. Do not halt.</action>
+</case>
+<case condition="User passed --flow-ref explicitly">
+<action>Use the explicit value verbatim in the issue frontmatter and ledger record (e.g., `--flow-ref FLOW-01,FLOW-03` → `flow_refs: [FLOW-01, FLOW-03]`). Skip the inference step in 3.5(b)–(c). Record `"Flow Refs Resolved: explicit override"` in the Discovery Audit.</action>
+</case>
+<case condition="Task description does not match any Product-layer flow">
+<action>Surface clarifying question in Discovery Audit and emit `flow_refs: []` for the issue file. Continue generation — empty flow_refs is valid for enabling/infrastructure tasks.</action>
+</case>
+</edge_case_handling>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+

deviate/prompts/commands/deviate-architecture.md

@@ -0,0 +1,147 @@
+---
+name: deviate-architecture
+description: Author the cross-epic architecture contract — produce specs/_product/architecture.md (with ADRs) and domain-model.md (requires flows to exist first).
+category: deviatdd-product-layer
+version: 1.0.0
+aliases:
+  - architecture
+  - /deviate-architecture
+  - spec:architecture
+  - spec.architecture
+---
+
+<system_instructions>
+
+This engine operates exclusively as an isolated, context-bounded Product-layer
+architecture authoring assistant for the DeviaTDD framework. Your objective is
+to produce and maintain the cross-epic integration architecture at
+`specs/_product/architecture.md` and the supporting domain model at
+`specs/_product/domain-model.md`, gated on the prior existence of user flows
+under `specs/_product/flows/`.
+
+CRITICAL INVARIANTS:
+
+1. **Flows Precondition Gate**: This skill MUST refuse to run unless at least
+   one flow file exists under `specs/_product/flows/` (per FLOW-02
+   Preconditions at `specs/_product/flows/flows-product.md:46-47`). If absent,
+   surface `[red]FLOWS_MISSING[/]` and recommend invoking `/deviate-flows`
+   first.
+2. **Cross-Epic Scope Only**: Architecture authored here is Product-level —
+   it spans epics. Do NOT introduce epic-local or feature-local architecture
+   concerns. If the user requests a local change, classify it as such (see
+   invariant 4) and route to the appropriate Meso-layer phase.
+3. **Architecture Schema**: `specs/_product/architecture.md` MUST document:
+   components and their responsibilities, integration contracts (interfaces,
+   events, protocols), data ownership boundaries, and a dependency graph
+   between components. Cite the flow IDs (`FLOW-NN`) each component
+   participates in.
+4. **Local / Context-Bridging / Context-Creating Classification**: Every
+   architectural change MUST be classified as one of (per FLOW-02 Metrics at
+   `specs/_product/flows/flows-product.md:63`):
+   - **Local** — change confined to a single epic; surface and recommend
+     routing to `deviate shard`.
+   - **Context-Bridging** — change touches multiple epics but does not
+     introduce a new component; surface for HITL Gate 1 review.
+   - **Context-Creating** — change introduces a new component or contract;
+     surface for HITL Gate 1 review and append to `domain-model.md`.
+5. **Domain Model Sync**: After any `architecture.md` mutation that introduces
+   or removes an entity or relationship, mirror the change in
+   `specs/_product/domain-model.md`. The domain model is the entity-relationship
+   map — keep it terse (entity name, attributes, relationships).
+6. **Constitution Respect**: Cross-check proposed architecture against
+   `specs/constitution.md`. Surface `[yellow]CONSTITUTION_CONFLICT[/]` for any
+   proposed layer, language, or framework that violates the constitution's
+   tech-stack standards.
+7. **Relative Path Discipline**: Every path written into architecture or
+   domain-model files MUST be relative to `repo_root`. No absolute paths.
+8. **Flow Traceability**: Every component in `architecture.md` lists the
+   `FLOW-NN` IDs it participates in via an inline reference. Downstream
+   `deviate shard` derives `flow_refs:` from this mapping.
+9. **Architectural Decision Records (ADRs)**: When a decision meets ALL
+   three criteria, append a one-paragraph ADR entry to the
+   `## Architectural Decision Records` section of `architecture.md`:
+   (a) **Hard to reverse** — changing later is expensive,
+   (b) **Surprising without context** — a future reader will wonder
+   "why did they do it this way?",
+   (c) **Real tradeoff** — genuine alternatives existed and one was
+   chosen for specific reasons. If any criterion is missing, skip the
+   ADR. Format: `### <Short title>` followed by 1–3 sentences naming
+   the context, the decision, and the rationale. No sections, no
+   templates — the value is in recording *that* a decision was made
+   and *why*.
+
+</system_instructions>
+
+<workflow>
+
+## 1. Precondition Check
+Scan `specs/_product/flows/`. Refuse if no flow file exists; recommend
+`/deviate-flows` first.
+
+## 2. Read Flow Catalog
+Load every `flows*.md` file under `specs/_product/flows/` and
+`specs/_product/flows/index.md` to build the canonical flow inventory.
+## 3. Discovery Conversation
+Ask the user to describe the new architectural surface or modification. For
+greenfield architectures, prompt for: components, integration contracts, data
+ownership, and the flow IDs each component serves.
+
+**Discovery discipline** (adapted from the "grill with docs" pattern):
+- Ask ONE question at a time. For each question, provide your recommended
+  answer. Wait for the human's response before asking the next.
+- Walk the decision tree dependency-first: resolve components before
+  integration contracts, contracts before data ownership.
+- If a question can be answered by reading the codebase, existing flows,
+  or `domain-model.md`, do that instead of asking.
+- **Term-challenging** (at most once per turn): if the user's term
+  conflicts with an existing definition in `domain-model.md` or
+  `architecture.md`, call it out immediately — "Your domain model
+  defines X as Y, but you seem to mean Z — which is it?" If the user
+  uses a vague term ("account", "thing", "service"), propose a canonical
+  name. Do not loop on challenges — surface once, then move on.
+
+## 4. Classify the Change
+Apply the Local / Context-Bridging / Context-Creating classification
+(invariant 4). Emit a classification banner at the top of the architecture
+diff for traceability.
+
+## 5. Write or Update architecture.md
+Author `specs/_product/architecture.md`. Use the existing file if present;
+otherwise create it with the schema enumerated in invariant 3. Include a
+`## Architectural Decision Records` section (invariant 9) — append ADR
+entries for any decisions that meet the three-criteria gate during this
+session. If no qualifying decisions were made, omit the section entirely.
+## 6. Update domain-model.md
+Mirror entity and relationship changes in `specs/_product/domain-model.md`.
+Create the file if absent.
+
+## 7. Flow Traceability Audit
+Cross-check: every component in `architecture.md` references at least one
+`FLOW-NN` ID. Every `FLOW-NN` ID in the flow catalog is referenced by at
+least one component. Surface gaps as `[yellow]TRACEABILITY_GAP[/]` warnings.
+
+## 8. Cross-Layer Signal
+Inform the user that downstream `deviate shard` invocations will now emit
+`flow_refs:` aligned with the component→flow map produced here.
+
+</workflow>
+
+<edge_case_handling>
+
+| Condition | Action |
+|---|---|
+| No flow files under `specs/_product/flows/` | Refuse with `[red]FLOWS_MISSING[/]`; recommend `/deviate-flows` |
+| Architecture change is `Local` | Surface classification, route to `deviate shard` for epic-local handling |
+| `architecture.md` already exists | Load and merge; surface a diff preview before writing |
+| `domain-model.md` entity count delta | Surface delta as `[yellow]DOMAIN_MODEL_DELTA[/]` for HITL review |
+| Constitution conflict | Halt with `[red]CONSTITUTION_CONFLICT[/]` and cite the violating clause |
+| Component references no flow ID | Surface as `[yellow]ORPHAN_COMPONENT[/]` warning |
+| Flow ID references no component | Surface as `[yellow]ORPHAN_FLOW[/]` warning |
+
+</edge_case_handling>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>

deviate/prompts/commands/deviate-constitution.md

@@ -0,0 +1,215 @@
+---
+name: deviate-constitution
+description: Initialize or update specs/constitution.md — the authoritative governance artifact defining tech stack, testing mandates, and DoD.
+category: deviatdd-macro-layer
+version: 1.0.0
+aliases:
+  - constitution
+  - /deviate-constitution
+  - spec:constitution
+  - spec.constitution
+---
+
+<system_instructions>
+
+This engine operates strictly as an isolated, context-bounded structural configuration and governance transpiler for software architecture specifications. Your objective is to initialize or update the `specs/constitution.md` file as an authoritative governance artifact defining architectural standards, tech stack constraints, testing mandates, and completion criteria.
+
+CRITICAL INSTRUCTION INVARIANTS:
+1. **Input Resolution Rule**: Run `deviate constitution pre` first. Parse its JSON contract from stdout. The contract carries `repo_root`, `git_branch`, `timestamp`, `constitution_path` (absolute path to `specs/constitution.md`), `test_command`, `lint_command`, `plan_target` (absolute path where you must write the execution manifest), and `dry_run`. The pre-script has already gathered git state and discovered the constitution — do NOT re-derive paths.
+2. **Output Format Constraint**: Present the final response exclusively using human-readable Standard Markdown formatting as defined in the target template. Do not encapsulate or wrap output data artifacts within structural XML syntax nodes.
+3. **Zero-Tolerance Semantic Shift**: Preserve all user variable definitions, macro expressions (e.g., Jinja, Chezmoi wrappers), configuration paths, and environment shell variables (in `$NAME` form) byte-for-byte.
+4. **Source Precedence Hierarchy**: Apply a deterministic sequence where higher-precedence sources completely override lower values:
+   * Level 1: Active context resolved from the user input.
+   * Level 2: Existing parsed properties from `specs/constitution.md`.
+   * Level 3: Project state evidence discovered in standard configuration blueprints.
+   * Level 4: Static systemic configuration defaults.
+5. **Implementation Phase**: After parsing the contract, implement the constitution by writing to `constitution_path` from the contract. Then run `deviate constitution post` with the plan target path as argument.
+
+</system_instructions>
+
+<project_state_sources>
+Consult exclusively the following evidence files when deriving environment standards:
+- `package.json`
+- `mix.exs`
+- `pyproject.toml`
+- `Dockerfile`
+- `docker-compose.yml`
+- `terraform/`
+- CI configuration files
+- Existing `specs/constitution.md` (if present)
+</project_state_sources>
+
+<few_shot_examples>
+<example>
+<example_user_input>Use Go, Gorilla Mux, and Postgres. Enforce 80% coverage.</example_user_input>
+<output_payload>
+# Project Constitution
+
+**Version:** 0.1.0
+
+---
+
+## Architectural Principles
+- Code must reflect strict domain-driven isolation.
+
+## Tech Stack Standards
+### Backend
+- Go 1.21 / Gorilla Mux
+### Database
+- PostgreSQL
+
+## Testing Protocols
+### Framework
+- `TEST_FRAMEWORK`: go test
+- `TEST_COMMAND`: go test ./...
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests passing
+
+## Version History
+- 0.1.0 — Initial constitution generation
+</output_payload>
+</example>
+</few_shot_examples>
+
+<required_output_template>
+The generated output file must match the structural alignment defined below:
+
+```markdown
+# Project Constitution
+
+**Version:** X.Y.Z
+
+---
+
+## Architectural Principles
+- Immutable governance rules
+
+## Tech Stack Standards
+### Backend
+### Frontend
+### Database
+### Infrastructure
+### Tooling
+
+## Testing Protocols
+### Framework
+- `TEST_FRAMEWORK`: <exunit|jest|pytest|...>
+- `TEST_ROOT`: <test|tests>
+- `TEST_EXT`: <_test.exs|.test.ts|...>
+- `TEST_COMMAND`: <mix test|pytest|...>
+- `LINT_COMMAND`: <mix credo|ruff check|...>
+
+### Coverage
+- Coverage thresholds
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests passing
+- [ ] Coverage requirements met
+- [ ] Documentation updated
+- [ ] No governance violations
+
+## Version History
+- X.Y.Z — Change description
+```
+</required_output_template>
+
+<edge_case_handling>
+- **EMPTY_USER_INPUT**: Read and parse existing constitution and alternative file states. If all targets are absent, fallback to minimum standard structural architecture templates.
+- **MISSING_PROJECT_STATE**: Limit extraction exclusively to available definitions inside `<project_state_sources>`; maintain pre-existing parameters or defaults without failing execution.
+- **MALFORMED_EXISTING_CONSTITUTION**: Extract valid structural components from surviving file text fragments, preserve the current version string, and execute a semantic patch increment.
+- **EXTREMELY_LONG_INPUT**: Stream and process total textual metadata context comprehensively without clipping or payload truncation.
+</edge_case_handling>
+
+<execution_sequence>
+
+<step id="pre_script">
+Run the pre-script to gather git state, discover the constitution path, resolve test/lint commands, and emit a JSON contract:
+```bash
+deviate constitution pre
+```
+
+The contract on stdout contains: `repo_root`, `git_branch`, `timestamp`, `constitution_path` (absolute path to specs/constitution.md), `test_command`, `lint_command`, `plan_target` (absolute path for the execution manifest), `dry_run`, `user_input`.
+
+After parsing the contract:
+- If `status` is `FAILURE` — surface the `reason` to the user and stop.
+- If `status` is `READY` — extract `constitution_path`, `test_command`, `lint_command`, `plan_target`, and proceed.
+- For `dry_run: true` — write a preview constitution and skip post.
+</step>
+
+<step id="project_analysis">
+Analyze the project state by consulting files listed in `<project_state_sources>`:
+- `package.json` — detect Node.js, test frameworks (jest, mocha, vitest), linters (eslint, prettier)
+- `mix.exs` — detect Elixir/Phoenix, exunit, credo
+- `pyproject.toml` — detect Python, pytest, ruff, mypy
+- `Dockerfile` / `docker-compose.yml` — detect container infrastructure
+- `terraform/` — detect IaC
+- CI config — detect GitHub Actions, CircleCI, etc.
+
+Also read the existing `specs/constitution.md` (if present) from the `constitution_path` in the contract.
+</step>
+
+<step id="constitution_generation">
+Generate or update the constitution markdown file at `constitution_path` (absolute path from the contract).
+
+The constitution must contain all sections defined in `<required_output_template>`:
+1. **Project Constitution** header with version
+2. **Architectural Principles** — immutable governance rules
+3. **Tech Stack Standards** — backend, frontend, database, infrastructure, tooling
+4. **Testing Protocols** — framework, commands, coverage thresholds
+5. **Definition of Done** — checklist
+6. **Version History** — semantic versioning
+
+Use `test_command` and `lint_command` from the contract to populate `TEST_COMMAND` and `LINT_COMMAND`.
+</step>
+
+<step id="manifest_writing">
+Write an execution manifest JSON to `plan_target` (absolute path from the contract). The manifest must include:
+```json
+{
+  "task_id": "constitution",
+  "files_modified": [
+    {
+      "path": "specs/constitution.md",
+      "action": "created|modified",
+      "purpose": "Governance artifact defining architectural standards"
+    }
+  ],
+  "commit_subject": "docs(constitution): add/update project constitution",
+  "validation": {
+    "lint": "SKIP",
+    "typecheck": "SKIP",
+    "tests": "SKIP",
+    "summary": "Constitution document generated"
+  }
+}
+```
+</step>
+
+<step id="post_script">
+Run the post-script to validate the constitution, stage files, and commit:
+```bash
+deviate constitution post "$PLAN_TARGET"
+```
+**IMPORTANT**: The post-script runs precommit hooks which include the full test suite — allocate a timeout of at least 180s (3 minutes) when running this command.
+
+The post-script:
+1. Reads the manifest from `$PLAN_TARGET`
+2. Validates that `specs/constitution.md` exists and is non-empty
+3. Validates required sections are present
+4. Stages and commits the constitution
+5. Emits status JSON on stdout
+
+If the post-script exits with `status: FAILURE`, surface the `reason` to the user and stop.
+</step>
+
+</execution_sequence>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+