constitution

# /constitution — Update Engineering Principles

<context>
**User Input**: $ARGUMENTS

**Current Git Status**: !`git status --short 2>/dev/null || echo "clean"`

**Current Branch**: !`git branch --show-current 2>/dev/null || echo "none"`

**Principles File Exists**: !`test -f docs/project/engineering-principles.md && echo "Yes" || echo "No"`

**Principles File**: @docs/project/engineering-principles.md

**Recent Constitution Commits**: !`git log --oneline --grep="constitution:" -5 2>/dev/null || echo "none"`
</context>

<objective>
Update the canonical engineering principles file (docs/project/engineering-principles.md) with atomic, auditable changes to the 8 core standards that govern feature development.

**Purpose**: Modify quality gates, add/update/remove principles, and maintain governance metadata with version control.

**When to use**:
- Add, remove, or revise a principle
- Tighten quality gates (security, accessibility, performance, tests)
- Align standards with new evidence or incidents
- Bump principle document version

**Workflow position**: Project governance command. Downstream gates (`/optimize`, `/validate`, `/ship`) enforce these principles.
</objective>

## Anti-Hallucination Rules

**CRITICAL**: Follow these rules to prevent implementation errors.

1. **Never modify the file without reading it first**
   - Always Read docs/project/engineering-principles.md before making changes
   - Verify file structure matches canonical template
   - Quote current content when analyzing changes

2. **Verify file existence before proceeding**
   - Use Grep to check file exists
   - If not found, instruct user to run /init-project first
   - Don't assume file structure - read and verify

3. **Validate principle structure after changes**
   - Check for required headers (## Principles)
   - Verify principle IDs match pattern: `### [ID] Title`
   - Ensure all required fields present (Policy, Rationale, Measurable checks, Evidence, Last updated)

4. **Quote arguments exactly**
   - Parse $ARGUMENTS precisely without adding interpretation
   - If arguments unclear, show usage examples and ask for clarification
   - Never guess at action types or field values

5. **Verify git operations succeeded**
   - Check git commit with rev-parse after committing
   - Confirm file staged with git status
   - Quote actual commit hash in output

**Why this matters**: Principles file governs all quality gates. Incorrect changes break downstream automation and enforce wrong standards.

---

## Mental Model

You are modifying the **8 core standards** that every feature must satisfy. Changes are **atomic**, **auditable**, and **measurable**.

- **Source of truth**: `docs/project/engineering-principles.md`
- **Principles must be**:
  - **Named** (short ID like `[A11Y]` or `[SECURITY]`)
  - **Policy** (project rule statement)
  - **Rationale** (why this matters)
  - **Measurable checks** (how we verify compliance)
  - **Evidence/links** (standards or internal ADRs)
  - **Last updated** (ISO date)

---

<process>

### Step 1: Verify Prerequisites

**Check that principles file exists:**
1. Read docs/project/engineering-principles.md
2. If not found, display error:
   ```
   ❌ Not found: docs/project/engineering-principles.md

   Run /init-project first or create the file with the canonical structure.
   See "Canonical File Structure" section below.
   ```
3. If found, confirm:
   ```
   ✅ Found: docs/project/engineering-principles.md
   ```

### Step 2: Parse Arguments

**If $ARGUMENTS is empty**, display usage:

```
Usage: /constitution "<action>: <description>"

Actions:
  add: <Principle ID> - <Title> | policy=<...> | metrics=<...> | evidence=<...>
  update: <Principle ID> | policy=<...> | metrics=<...> | evidence=<...>
  remove: <Principle ID>
  set: version=<major|minor|patch>        # bumps principles doc version
  set: owner=@team-platform                # optional governance metadata

Examples:
  /constitution "add: A11Y - Accessibility | policy=WCAG 2.2 AA | metrics=axe CI pass; keyboard nav; color contrast AA | evidence=link:WCAG"
  /constitution "update: SECURITY | policy=OWASP ASVS L2 | metrics=threat model per feature; SAST; DAST | evidence=link:ASVS"
  /constitution "remove: DO-NOT-OVERENGINEER"
  /constitution "set: version=minor"
```

**If $ARGUMENTS provided**, parse the action type:
- Extract action: `add`, `update`, `remove`, or `set`
- Extract principle ID if applicable
- Extract field values (policy, metrics, evidence) from pipe-delimited format
- Display parsed change request:
  ```
  Change request:
    {$ARGUMENTS}
  ```

### Step 3: Determine Change Type

**Supported actions:**

- **add**: Create a new principle block if ID not already present
  - Check if principle ID exists using Grep
  - If exists, display error and stop
  - If not, proceed to add new principle section

- **update**: Replace fields on existing principle ID
  - Locate principle by ID using Grep
  - If not found, display error and stop
  - Update specified fields only (policy, metrics, evidence)
  - Preserve other fields unchanged

- **remove**: Delete entire principle block by ID
  - Locate principle by ID
  - Remove from `### [ID]` to next `---` separator or next principle
  - Decrease principle count in header

- **set: version**: Bump document version (SemVer)
  - Parse version field in file header
  - Apply major/minor/patch increment
  - Update version field

- **set: owner**: Update governance metadata
  - Update Owner field in file header

**Idempotency**: Re-running the same command yields no diff.

### Step 4: Create Git Checkpoint

**Before making changes:**
1. Stage the current principles file:
   ```bash
   git add docs/project/engineering-principles.md
   ```

2. Create checkpoint commit (allow failure if no changes):
   ```bash
   git commit -m "constitution: checkpoint before update" --no-verify
   ```
   *(Ignore errors if nothing to commit)*

### Step 5: Apply Changes to File

**Edit docs/project/engine