CascadingDev/Docs/DESIGN.md

# AI–Human Collaboration System
## Process & Architecture Design Document (v2.0)
- Feature ID: FR_2025-10-21_initial-feature-request
- Status: Design Approved (Ready for Implementation)
- Date: 2025-10-21
- Owners: Rob (maintainer), AI_Moderator (process steward)
- Contributors: AI_Claude, AI_Deepseek, AI_Junie, AI_Chat-GPT, AI_GitHubCopilot

## Table of Contents
- Executive Summary
- Repository Layout
- Stage Model & Operational Procedure
- Voting, Quorum & Etiquette
- Cascading Rules System
- Orchestration Architecture
- Moderator Protocol
- Error Handling & Resilience
- Security & Secrets Management
- Performance & Scale Considerations
- Testing Strategy
- Implementation Plan
- Risks & Mitigations
- Template Evolution
- Roles & Agent Personas
- Glossary
- Appendices

## Executive Summary

We are implementing a Git-native, rules-driven workflow that enables seamless collaboration between humans and multiple AI agents across the entire software development lifecycle. The system uses cascading .ai-rules.yml configurations and a thin Bash pre-commit hook to automatically generate and maintain development artifacts (discussions, design docs, reviews, diagrams, plans). A Python orchestrator provides structured checks and status reporting while preserving the fast Bash execution path.

### Core Principles
- Lightweight & Fast: Everything stored in Git as Markdown; minimal external dependencies
- Single Source of Truth: Repository contains all conversations, decisions, and code artifacts
- Self-Driving with Human Safety: AI agents can propose and vote; humans must approve critical stages
- Deterministic & Reversible: All automated actions are diffed, logged, and easily revertible
- Composable Rules: Nearest-folder precedence via cascading .ai-rules.yml configurations

### Key Innovations
- Stage-Per-Discussion Model: Separate conversation threads for each development phase
- Automated Artifact Generation: Discussions automatically drive corresponding documentation
- Integrated Bug Sub-Cycles: Test failures automatically spawn bug reports with their own mini-lifecycle
- Intelligent Promotion Gates: Status-based transitions with configurable voting thresholds
- Multi-Agent Role Specialization: Different AI personas with stage-specific responsibilities

## Repository Layout

### Canonical Structure (Option A: Per-Feature Folders)
```text
/ (repository root)
├─ .ai-rules.yml                          # Global defaults + file associations
├─ automation/                            # Orchestrator & adapters
│  ├─ workflow.py                         # Python status/reporting (v1 non-blocking)
│  ├─ adapters/
│  │  ├─ claude_adapter.py                # Model interface (future)
│  │  ├─ gitea_adapter.py                 # Gitea API integration (future)
│  │  └─ agent_coordinator.py             # Role routing & task allocation (future)
│  ├─ agents.yml                          # Role → stages mapping
│  └─ config.yml                          # Configuration (future)
├─ process/                               # Process documentation & templates
│  ├─ design.md                           # This document
│  ├─ policies.md                         # Human-friendly policy documentation
│  ├─ policies.yml                        # Machine-readable policy configuration
│  └─ templates/
│     ├─ feature_request.md
│     ├─ discussion.md
│     ├─ design_doc.md
│     └─ implementation_plan.md
├─ Docs/
│  ├─ features/
│  │  ├─ .ai-rules.yml                    # Folder-scoped rules for all features
│  │  ├─ FR_YYYY-MM-DD_<slug>/           # Individual feature folders
│  │  │  ├─ request.md                    # Original feature request
│  │  │  ├─ discussions/                  # Stage-specific conversations
│  │  │  │  ├─ feature.discussion.md      # Discuss the request
│  │  │  │  ├─ design.discussion.md       # Discuss the design
│  │  │  │  ├─ implementation.discussion.md # Track implementation
│  │  │  │  ├─ testing.discussion.md      # Plan/track testing
│  │  │  │  └─ review.discussion.md       # Final review
│  │  │  ├─ design/                       # Design artifacts
│  │  │  │  ├─ design.md                  # Evolving design document
│  │  │  │  └─ diagrams/                  # Architecture diagrams
│  │  │  ├─ implementation/               # Implementation artifacts
│  │  │  │  ├─ plan.md                    # Implementation plan
│  │  │  │  └─ tasks.md                   # Task checklist
│  │  │  ├─ testing/                      # Testing artifacts
│  │  │  │  ├─ testplan.md                # Test strategy
│  │  │  │  └─ checklist.md               # Test checklist
│  │  │  ├─ review/                       # Review artifacts
│  │  │  │  └─ findings.md                # Review findings
│  │  │  └─ bugs/                         # Auto-generated bug reports
│  │  │     └─ BUG_YYYYMMDD_<slug>/
│  │  │        ├─ report.md
│  │  │        ├─ discussion.md
│  │  │        └─ fix/
│  │  │           ├─ plan.md
│  │  │           └─ tasks.md
│  ├─ discussions/
│  │  └─ reviews/                         # Code reviews from hook
│  └─ diagrams/
│     └─ file_diagrams/                   # PlantUML from source files
├─ src/                                   # Application source code
└─ tests/                                 # System test suite
   ├─ unit/
   ├─ integration/
   └─ bin/
```

Note: Each stage discussion has a companion summary maintained automatically next to it (e.g., feature.summary.md, design.summary.md, implementation.summary.md, testing.summary.md, review.summary.md) to provide a live, scannable state of the thread.

### Naming Conventions
- Feature Folder: Docs/features/FR_YYYY-MM-DD_<slug>/
- Discussion Files: {stage}.discussion.md in discussions/ subfolder
- Bug Reports: bugs/BUG_YYYYMMDD_<slug>/ with standardized contents
- Source Files: Maintain existing patterns in src/

### Template Variables
Supported in path resolution:

- {basename}: Filename without extension
- {date}: Current date in YYYY-MM-DD format
- {rel}: Repository-relative path to source file
- {dir}: Directory containing the source file (NEW)

## Stage Model & Operational Procedure

### Complete Stage Lifecycle
```text
Request → Feature Discussion → Design Discussion → Implementation Discussion → Testing Discussion → Review Discussion → Release
```
### Stage 1: Request
#### Entry Criteria
- Docs/features/FR_*/request.md created from template
- Template completeness: intent, motivation, constraints, open questions

#### Artifacts Generated
- request.md: Source feature request document

#### Automated Actions
- Creates discussions/feature.discussion.md with standard header
- Adds Summary and Participation sections
- Appends initial AI comment with vote

#### Exit Criteria
- Discussion file created and populated
- Ready for feature discussion phase

### Stage 2: Feature Discussion
- File: discussions/feature.discussion.md

#### Header Template

```yaml
---
type: discussion
stage: feature
status: OPEN  # OPEN | READY_FOR_DESIGN | REJECTED
feature_id: FR_YYYY-MM-DD_<slug>
created: YYYY-MM-DD

promotion_rule:
  allow_agent_votes: true
  ready_min_eligible_votes: all
  reject_min_eligible_votes: 1

participation:
  instructions: |
    - Append your input at the end as: "YourName: your comment…"
    - Every comment must end with a vote line: "VOTE: READY|CHANGES|REJECT"
    - Agents/bots must prefix names with "AI_"    

voting:
  values: [READY, CHANGES, REJECT]
---
```
#### Operational Flow
- Participants append comments ending with vote lines
- Latest vote per participant counts toward thresholds
- AI_Moderator tracks unanswered questions and missing votes
- When READY threshold met: status → READY_FOR_DESIGN

#### Promotion Actions
- Creates discussions/design.discussion.md (OPEN)
- Creates design/design.md seeded from request + feature discussion
- Creates design/diagrams/ folder

### Stage 3: Design Discussion
- File: discussions/design.discussion.md

#### Header

```yaml
---
type: discussion
stage: design
status: OPEN  # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
# ... same promotion_rule, participation, voting as feature
---
```

#### Operational Flow
- AI_Architect updates design/design.md on each commit
- Design doc evolves with discussion: options, decisions, risks, acceptance criteria
- Participants vote on design completeness
- When READY threshold met: status → READY_FOR_IMPLEMENTATION

#### Design Document Structure
- Context & Goals
- Non-Goals & Constraints
- Options Considered with Trade-offs
- Decision & Rationale
- Architecture Diagrams
- Risks & Mitigations
- Measurable Acceptance Criteria

#### Promotion Actions
- Creates discussions/implementation.discussion.md (OPEN)
- Creates implementation/plan.md and implementation/tasks.md
- Tasks are checkboxes aligned to acceptance criteria

### Stage 4: Implementation Discussion
- File: discussions/implementation.discussion.md

#### Header

```yaml
---
type: discussion
stage: implementation
status: OPEN  # OPEN | READY_FOR_TESTING
promotion_rule:
  allow_agent_votes: true
  ready_min_eligible_votes: 1_human  # HUMAN GATE
  reject_min_eligible_votes: 1
# ...
---
```

#### Operational Flow
- AI_Implementer syncs implementation/tasks.md with discussion
- Parse checkboxes and PR mentions from discussion posts
- Link commits/PRs to tasks when mentioned ([#123], commit shas)
- When all required tasks complete: status → READY_FOR_TESTING

#### Task Management
- Tasks.md maintained as single source of truth
- Checkbox completion tracked automatically
- PR and commit references linked automatically

#### Promotion Actions
- Creates discussions/testing.discussion.md (OPEN)
- Creates testing/testplan.md and testing/checklist.md
- Test checklist derived from acceptance criteria + edge cases

### Stage 5: Testing Discussion
- File: discussions/testing.discussion.md

#### Header

```yaml
---
type: discussion
stage: testing
status: OPEN  # OPEN | READY_FOR_REVIEW
promotion_rule:
  allow_agent_votes: true
  ready_min_eligible_votes: all
  reject_min_eligible_votes: 1
# ...
---
```

#### Operational Flow
- AI_Tester syncs testing/checklist.md with discussion posts
- Parse result blocks: [RESULT] PASS/FAIL: description
- Mark corresponding checklist items pass/fail
- On test failure: auto-create bug report with full sub-cycle

#### Bug Sub-Cycle Creation

```text
bugs/BUG_YYYYMMDD_<slug>/
├─ report.md          # Steps, expected/actual, environment
├─ discussion.md      # Bug discussion (OPEN)
└─ fix/
   ├─ plan.md         # Fix implementation plan
   └─ tasks.md        # Fix tasks checklist
```

#### Bug Resolution Flow
- Bug follows mini Implementation→Testing cycle
- On bug closure, return to main testing discussion
- Bug results integrated into main test checklist

#### Promotion Actions
- Creates discussions/review.discussion.md (OPEN)
- Creates review/findings.md with verification summary

### Stage 6: Review Discussion
- File: discussions/review.discussion.md

#### Header

```yaml
---
type: discussion
stage: review
status: OPEN  # OPEN | READY_FOR_RELEASE | CHANGES_REQUESTED
promotion_rule:
  allow_agent_votes: true
  ready_min_eligible_votes: 1_human  # HUMAN GATE
  reject_min_eligible_votes: 1
# ...
---
```

#### Operational Flow
- AI_Reviewer summarizes into review/findings.md
- Review covers: changes, risks, test evidence, deployment considerations
- Can spawn follow-up feature requests or bugs from findings
- When human READY present and no blockers: status → READY_FOR_RELEASE

#### Follow-up Artifact Creation
- New FR: ../../FR_YYYY-MM-DD_followup/request.md
- New Bug: bugs/BUG_YYYYMMDD_review/report.md

### Stage 7: Release

#### Entry Criteria
- Review discussion status is READY_FOR_RELEASE

#### Automated Actions
- Generate release notes from feature changes
- Semver bump based on change type
- Create git tag
- Update changelog
- Document rollback procedure

#### Post-Release
- Queue post-release validation tasks
- Update documentation as needed
- Archive feature folder if complete

## Voting, Quorum & Etiquette
### Voting System
Vote Values: READY | CHANGES | REJECT

Format Requirements:

Each comment must end with: VOTE: READY|CHANGES|REJECT

Last line of comment, exact format

Multiple votes by same participant: latest wins

Vote Parsing Examples:

```text
Rob: I agree with this approach. VOTE: READY
→ Rob: READY

AI_Claude: Here's my analysis... VOTE: CHANGES
→ AI_Claude: CHANGES (if allow_agent_votes=true)

User: I have concerns... VOTE: CHANGES
Later: User: Actually, addressed now. VOTE: READY
→ User: READY (latest vote wins)
```
### Eligibility & Quorum
Default Policy (machine-readable in process/policies.yml):

```yaml
version: 1
voting:
  values: [READY, CHANGES, REJECT]
  allow_agent_votes: true
  quorum:
    discussion:     { ready: all,      reject: 1 }
    implementation: { ready: 1_human,  reject: 1 }
    release:        { ready: 1_human,  reject: 1 }
eligibility:
  agents_allowed: true
  require_human_for: [implementation, release]
etiquette:
  name_prefix_agents: "AI_"
  vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\b"
timeouts:
  discussion_stale_days: 3
  nudge_interval_hours: 24
```
Human Safety Gates:

Implementation promotion: ≥1 human READY required

Release promotion: ≥1 human READY required

Agent votes count toward discussion but cannot satisfy human requirements

### Participation Etiquette
Conciseness: Keep comments action-oriented and focused

References: Link to files/sections when possible (design.md#architecture)

Naming: Agents must prefix with AI_ (e.g., AI_Architect)

Ownership: Suggest explicit owners for next steps (@AI_Architect: please draft...)

Timeliness: Respond to direct questions within 24 hours

## Cascading Rules System
### Global Rules (Root .ai-rules.yml)
```yaml
version: 1

# Map file extensions to rule names
file_associations:
  "*.js":   "js-file"
  "*.ts":   "js-file"
  "*.puml": "puml-file"
  "*.md":   "md-file"

rules:
  js-file:
    description: "Generate PlantUML + review for JS/TS files"
    outputs:
      diagram:
        enabled: true
        path: "Docs/diagrams/file_diagrams/{basename}.puml"
        output_type: "puml-file"
        instruction: |
          Update the PlantUML diagram to reflect staged code changes.
          Focus on: key functions, control flow, data transformations, dependencies.
          Keep architectural elements clear and focused.          
      review:
        enabled: true
        path: "Docs/discussions/reviews/{date}_{basename}.md"
        output_type: "md-file"
        instruction: |
          Create technical review of code changes.
          Include: summary of changes, potential risks, edge cases,
          testing considerations, performance implications.
          Use concise bullet points.          

  puml-file:
    description: "Rules for PlantUML diagram files"
    instruction: |
      Maintain readable, consistent diagrams.
      Use descriptive element names, consistent arrow styles.
      Include brief legend for complex diagrams.      

  md-file:
    description: "Rules for Markdown documentation"
    instruction: |
      Use proper Markdown syntax with concise paragraphs.
      Use code fences for examples, lists for multiple points.
      Maintain technical, clear tone.      

settings:
  max_tokens: 4000
  temperature: 0.1
  model: "claude-sonnet-4-5-20250929"
```
### Feature-Scoped Rules (Docs/features/.ai-rules.yml)
```yaml
version: 1

file_associations:
  "request.md":                  "feature_request"
  "feature.discussion.md":       "feature_discussion"
  "design.discussion.md":        "design_discussion"
  "implementation.discussion.md":"impl_discussion"
  "testing.discussion.md":       "test_discussion"
  "review.discussion.md":        "review_discussion"

rules:
  feature_request:
    outputs:
      feature_discussion:
        path: "{dir}/discussions/feature.discussion.md"
        output_type: "feature_discussion_writer"
        instruction: |
          If discussion file missing: create with standard header (stage: feature, status: OPEN),
          add Summary and Participation sections, then append initial AI comment with vote.
          If exists: no operation.          

  feature_discussion:
    outputs:
      self_append:
        path: "{dir}/discussions/feature.discussion.md"
        output_type: "feature_discussion_writer"
        instruction: |
          Append concise comment signed with AI name, ending with single vote line.
          Evaluate votes against header thresholds. If READY threshold met:
          - Flip status to READY_FOR_DESIGN
          - Clearly state promotion decision in comment
          Append-only with minimal diff.          

      design_discussion:
        path: "{dir}/discussions/design.discussion.md"
        output_type: "design_discussion_writer"
        instruction: |
          Create ONLY if feature discussion status is READY_FOR_DESIGN.
          Seed with standard header (stage: design, status: OPEN).          

      design_doc:
        path: "{dir}/design/design.md"
        output_type: "design_doc_writer"
        instruction: |
          Create ONLY if feature discussion status is READY_FOR_DESIGN.
          Seed design document from request content and feature discussion.
          Include: Context, Options, Decision, Risks, Acceptance Criteria.          

  design_discussion:
    outputs:
      design_update:
        path: "{dir}/design/design.md"
        output_type: "design_doc_writer"
        instruction: |
          Update design document to reflect latest design discussion.
          Ensure acceptance criteria are measurable and complete.
          Maintain all standard sections. Minimal diffs.          

      impl_discussion:
        path: "{dir}/discussions/implementation.discussion.md"
        output_type: "impl_discussion_writer"
        instruction: |
          Create ONLY if design discussion status is READY_FOR_IMPLEMENTATION.          

      impl_plan:
        path: "{dir}/implementation/plan.md"
        output_type: "impl_plan_writer"
        instruction: |
          Create ONLY if design status is READY_FOR_IMPLEMENTATION.
          Draft implementation milestones and scope.          

      impl_tasks:
        path: "{dir}/implementation/tasks.md"
        output_type: "impl_tasks_writer"
        instruction: |
          Create ONLY if design status is READY_FOR_IMPLEMENTATION.
          Generate task checklist aligned to acceptance criteria.          

  impl_discussion:
    outputs:
      tasks_sync:
        path: "{dir}/implementation/tasks.md"
        output_type: "impl_tasks_maintainer"
        instruction: |
          Parse checkboxes and PR mentions from implementation discussion.
          Synchronize tasks.md accordingly.
          When all required tasks complete, mark implementation discussion READY_FOR_TESTING.          

      test_discussion:
        path: "{dir}/discussions/testing.discussion.md"
        output_type: "test_discussion_writer"
        instruction: |
          Create ONLY if implementation status is READY_FOR_TESTING.          

      test_plan:
        path: "{dir}/testing/testplan.md"
        output_type: "testplan_writer"
        instruction: |
          Create ONLY if implementation status is READY_FOR_TESTING.
          Derive test strategy from acceptance criteria.          

      test_checklist:
        path: "{dir}/testing/checklist.md"
        output_type: "testchecklist_writer"
        instruction: |
          Create ONLY if implementation status is READY_FOR_TESTING.
          Generate test checklist covering acceptance criteria and edge cases.          

  test_discussion:
    outputs:
      checklist_update:
        path: "{dir}/testing/checklist.md"
        output_type: "testchecklist_maintainer"
        instruction: |
          Parse result blocks from test discussion ([RESULT] PASS/FAIL: description).
          Update checklist accordingly with evidence links.
          On test failure, create appropriate bug report.          

      bug_report:
        path: "{dir}/bugs/BUG_{date}_auto/report.md"
        output_type: "bug_report_writer"
        instruction: |
          Create bug report ONLY when test failure with clear reproduction steps.
          Initialize bug discussion and fix plan in same folder.          

      review_discussion:
        path: "{dir}/discussions/review.discussion.md"
        output_type: "review_discussion_writer"
        instruction: |
          Create ONLY if all test checklist items pass.
          Set testing discussion status to READY_FOR_REVIEW.          

      review_findings:
        path: "{dir}/review/findings.md"
        output_type: "review_findings_writer"
        instruction: |
          Create summary of verified functionality, risks, and noteworthy changes.          

  review_discussion:
    outputs:
      followup_feature:
        path: "../../FR_{date}_followup/request.md"
        output_type: "feature_request_writer"
        instruction: |
          Create follow-up feature request ONLY when review identifies enhancement opportunity.          

      followup_bug:
        path: "{dir}/bugs/BUG_{date}_review/report.md"
        output_type: "bug_report_writer"
        instruction: |
          Create bug report ONLY when review identifies defect.
          Seed discussion and fix plan.          
```
5.3 Rule Resolution Precedence
Nearest Directory: Check source file directory and parents upward

Feature Scope: Docs/features/.ai-rules.yml for feature artifacts

Global Fallback: Root .ai-rules.yml for code files

Conflict Resolution: Nearest rule wins, with logging of override decisions

## Orchestration Architecture
### Bash Pre-commit Hook (Current Implementation)
Core Responsibilities:

Collect staged files (Added/Modified only)

Resolve rules via cascading lookup

Build context prompts from staged content

Call AI model via CLI for patch generation

Apply patches with robust error handling

Enhanced Template Support:

```bash
# Add to resolve_template() function
local dirpath
dirpath=$(dirname "$rel_path")
# ...
-e "s|{dir}|$dirpath|g"
```
Patch Application Strategy:

Preserve Index Lines: Enable 3-way merge capability

Try 3-way First: git apply --index --3way --recount --whitespace=nowarn

Fallback to Strict: git apply --index if 3-way fails

Debug Artifacts: Save raw/clean/sanitized/final patches to .git/ai-rules-debug/

Discussion File Optimization:

Prefer append-only edits with optional header flips

For large files: generate full new content and compute diff locally

Minimize hunk drift through careful patch construction

### Python Orchestrator (automation/workflow.py)
Phase 1 (Non-blocking Status):

```python
#!/usr/bin/env python3
import json, os, sys, subprocess, re
from pathlib import Path

def main():
    changed_files = read_changed_files()
    status_report = analyze_discussion_status(changed_files)
    if status_report:
        print("AI-Workflow Status Report")
        print(json.dumps(status_report, indent=2))
    sys.exit(0)  # Always non-blocking in v1
```
Core Functions:

Vote Parsing: Parse discussion files, track latest votes per participant

Threshold Evaluation: Compute eligibility and quorum status

Status Reporting: JSON output of current discussion state

Decision Hints: Suggest promotion based on policy rules

Future Enhancements:

Policy enforcement based on process/policies.yml

Gitea API integration for issue/PR management

Advanced agent coordination and task routing

### Gitea Integration (Future)
Label System:

stage/*: stage/discussion, stage/design, stage/implementation, etc.

blocked/*: blocked/needs-votes, blocked/needs-human

needs/*: needs/design, needs/review, needs/tests

Automated Actions:

Open/label PRs for implementation transitions

Post status summaries to PR threads

Create tracking issues for feature implementation

Report status checks to PRs

## Moderator Protocol
### AI_Moderator Responsibilities
Conversation Tracking:

Monitor unanswered questions (>24 hours)

Track missing votes from active participants

Identify stale threads needing attention

Flag direct mentions that need responses

Progress Reporting:

Compute current vote tallies and thresholds

List participants who haven't voted recently

Summarize promotion status and remaining requirements

Highlight blocking issues or concerns

Task Allocation:

Suggest explicit owners for pending tasks

Example: "AI_Architect: please draft the acceptance criteria section"

Example: "Rob: could you clarify the deployment timeline?"

### Moderator Implementation
Rule Definition (in Docs/features/.ai-rules.yml):

```yaml
discussion_moderator_nudge:
  outputs:
    self_append:
      path: "{dir}/discussions/{basename}.discussion.md"
      output_type: "feature_discussion_writer"
      instruction: |
        Act as AI_Moderator. Analyze the entire discussion and:
        
        UNANSWERED QUESTIONS:
        - List any direct questions unanswered for >24 hours (mention @names)
        - Flag questions that need clarification or follow-up
        
        VOTE STATUS:
        - Current tally: READY: X, CHANGES: Y, REJECT: Z
        - Missing votes from: [list of participants without recent votes]
        - Promotion status: [based on header thresholds]
        
        ACTION ITEMS:
        - Suggest specific next owners for pending tasks
        - Propose concrete next steps with deadlines
        
        Keep comment under 10 lines. End with "VOTE: CHANGES".
        Append-only; minimal diff; update nothing else.        
```
Nudge Frequency: Controlled by nudge_interval_hours in policies

## Error Handling & Resilience
### Common Failure Modes
Patch Application Issues:

Symptom: Hunk drift on large files, merge conflicts

Mitigation: 3-way apply with index preservation, append-only strategies

Fallback: Local diff computation from full new content

Model Output Problems:

Symptom: Malformed diff, missing markers, invalid patch format

Mitigation: Extract between markers, validate with git apply --check

Fallback: Clear diagnostics with patch validation output

Tooling Dependencies:

Symptom: Missing yq, claude, or other required tools

Mitigation: Pre-flight checks with clear error messages

Fallback: Graceful degradation with feature-specific disabling

Rule Conflicts:

Symptom: Multiple rules matching same file with conflicting instructions

Mitigation: Nearest-directory precedence with conflict logging

Fallback: Global rule application with warning

### Recovery Procedures
Manual Override:

```bash
# Bypass hook for emergency edits
git commit --no-verify -m "Emergency fix: manually overriding discussion status"

# Manually update discussion header
# type: discussion -> status: READY_FOR_IMPLEMENTATION
```
Debug Artifacts:

All patch variants saved to .git/ai-rules-debug/

Timestamped files: raw, clean, sanitized, final patches

Commit-specific directories for correlation

Rollback Strategy:

All generated artifacts are staged separately

Easy partial staging: git reset HEAD <file> for specific artifacts

Full reset: git reset HEAD~1 to undo entire commit with generations

### Audit Trail
Execution Logging:

All rule invocations logged with source→output mapping

Patch application attempts and outcomes recorded

Vote calculations and promotion decisions documented

Debug Bundle:

```bash
.git/ai-rules-debug/
├─ 20251021-143022-12345-feature.discussion.md/
│  ├─ raw.out          # Raw model output
│  ├─ clean.diff       # Extracted patch
│  ├─ sanitized.diff   # After sanitization
│  └─ final.diff       # Final applied patch
└─ execution.log       # Chronological action log
```
## Security & Secrets Management
### Secret Protection
Never Commit:

API keys, authentication tokens

Personal identifying information

Internal system credentials

Private configuration data

Environment Variables:

```bash
# Current approach
export CLAUDE_API_KEY="your_key"
# Future .env approach (git-ignored)
# .env file loaded via python-dotenv in Python components
```
Configuration Management:

Keep sensitive endpoints in automation/config.yml

Use environment variable substitution in configuration

Validate no secrets in discussions, rules, or generated artifacts

### Access Control
Repository Security:

Assume all repository contents are potentially exposed

No sensitive business logic in prompt instructions

Regular security reviews of rule definitions

Agent Permissions:

Limit file system access to repository scope

Validate output paths stay within repository

Sanitize all file operations for path traversal

## Performance & Scale Considerations
### Optimization Strategies
Prompt Efficiency:

Pass staged diffs instead of full file contents when possible

Use concise, structured instructions with clear formatting

Limit context to relevant sections for large files

Discussion Management:

Append-only edits with periodic summarization

Compact status reporting in moderator comments

Archive completed discussions if they become too large

Batch Operations:

Process multiple related files in single model calls when beneficial

Cache rule resolutions for multiple files in same directory

Parallelize independent output generations

### Scaling Limits
File Size Considerations:

Small (<100KB): Full content in prompts

Medium (100KB-1MB): Diff-only with strategic context

Large (>1MB): Chunked processing or summary-only approaches

Repository Size:

Current approach suitable for medium-sized repositories

For very large codebases: scope rules to specific directories

Consider rule disabling for generated/binary assets

Rate Limiting:

Model API calls: implement throttling and retry logic

Gitea API: respect rate limits with exponential backoff

File operations: batch where possible to reduce I/O

## Testing Strategy
### Testing Tiers
Unit Tests (Python):

Vote parsing and eligibility calculation

Policy evaluation and quorum determination

Rules resolution and conflict handling

Template variable substitution

Integration Tests (Bash + Python):

End-to-end rule → prompt → patch → apply cycle

Discussion status transitions and promotion logic

Error handling and recovery procedures

Multi-file rule processing

Artifact Validation:

PlantUML syntax checking: plantuml -checkonly

Markdown structure validation

Template completeness checks

YAML syntax validation

### Test Architecture
```text
tests/
├─ unit/
│  ├─ test_votes.py
│  ├─ test_policies.py
│  ├─ test_rules_resolution.py
│  └─ test_template_variables.py
├─ integration/
│  ├─ run.sh                    # Main test runner
│  ├─ lib.sh                    # Test utilities
│  ├─ fixtures/
│  │  └─ repo_skeleton/         # Minimal test repository
│  │     ├─ .ai-rules.yml
│  │     ├─ Docs/features/.ai-rules.yml
│  │     └─ Docs/features/FR_test/
│  │        ├─ request.md
│  │        └─ discussions/
│  └─ test_cases/
│     ├─ test_feature_promotion.sh
│     ├─ test_design_generation.sh
│     └─ test_bug_creation.sh
├─ bin/
│  └─ claude                    # Fake deterministic model
└─ README.md
```
### Fake Model Implementation
Purpose: Deterministic testing without external API dependencies

Implementation (tests/bin/claude):

```bash
#!/bin/bash
# Fake Claude CLI for testing
# Reads prompt from stdin, outputs predetermined patch based on content

if grep -q "OUTPUT FILE:.*discussion.md" ; then
    # Output discussion update patch
    cat << 'EOF'
<<<AI_DIFF_START>>>
diff --git a/Docs/features/FR_test/discussions/feature.discussion.md b/Docs/features/FR_test/discussions/feature.discussion.md
index 1234567..890abcd 100644
--- a/Docs/features/FR_test/discussions/feature.discussion.md
+++ b/Docs/features/FR_test/discussions/feature.discussion.md
@@ -15,3 +15,6 @@ voting:
 
 ## Summary
 Test feature for validation
+
+## Participation
+AI_Test: This is a test comment. VOTE: READY
<<<AI_DIFF_END>>>
EOF
else
    # Default patch for other file types
    echo "No specific patch for this file type"
fi
```
### Integration Test Runner
#### Key Test Scenarios
- Feature Promotion: request.md → feature.discussion.md → READY_FOR_DESIGN
- Design Generation: design.discussion.md → design.md updates
- Bug Creation: test failure → auto bug report generation
- Error Recovery: Malformed patch → graceful failure with diagnostics
- Rule Conflicts: Multiple rule matches → nearest-directory resolution

#### Test Execution
```bash
# Run full test suite
cd tests/integration
./run.sh

# Run specific test case
./test_cases/test_feature_promotion.sh
```
### Continuous Validation
Pre-commit Checks:

PlantUML syntax validation for generated diagrams

Markdown link validation

YAML syntax checking for rule files

Template variable validation

Performance Benchmarks:

Rule resolution time for typical commit

Patch generation and application duration

Memory usage during large file processing

## Source Intelligence Automation (Auto-Review + Auto-Diagram)

### Purpose
To keep technical documentation and diagrams in sync with evolving source code. On every staged change to src/**/*.js|ts|py, the automation layer:
- Analyzes the diff and AST to produce a concise review summary
- Extracts structure and updates a PlantUML diagram in Docs/diagrams/file_diagrams/

### A) Folder Layout
```text
src/
├─ automation/
│  ├─ __init__.py
│  ├─ analyzer.py            # parses diffs, extracts structure & metrics
│  ├─ reviewer.py            # writes review summaries (md)
│  ├─ diagrammer.py          # emits PUML diagrams
│  └─ utils/
│     ├─ git_tools.py        # staged diff, blob lookup
│     ├─ code_parser.py      # AST helpers (JS/TS/Python)
│     └─ plantuml_gen.py     # renders PlantUML text
```

### B) Operational Flow (Triggered by Hook)
```text
┌────────────────────────────────────────────────────────┐
│  pre-commit hook (bash)                                │
│   └──> detect src/**/*.js|ts|py changes                │
│         ├─> call automation/analyzer.py --file <path>  │
│         │     ├─ parse diff + AST                      │
│         │     ├─ collect functions, classes, calls     │
│         │     └─ emit JSON summary                     │
│         ├─> reviewer.py  → Docs/discussions/reviews/   │
│         └─> diagrammer.py → Docs/diagrams/file_diagrams/│
└────────────────────────────────────────────────────────┘
```
Each stage emits a unified diff so the same patch-application rules (3-way apply, append-only) still apply.

### C) Sample Rule (Root .ai-rules.yml)
```yaml
js-file:
  description: "Generate PlantUML + review for JS/TS files"
  outputs:
    diagram:
      path: "Docs/diagrams/file_diagrams/{basename}.puml"
      output_type: "puml-file"
      instruction: |
        Parse code structure and update a PlantUML diagram:
        - Modules, classes, functions
        - Control-flow edges between major functions        
    review:
      path: "Docs/discussions/reviews/{date}_{basename}.md"
      output_type: "md-file"
      instruction: |
        Summarize this commit’s code changes:
        - What changed and why
        - Possible risks / performance / security notes
        - Suggested tests or TODOs        
```
Similar rules exist for py-file, ts-file, etc.

### D) Core Algorithms (pseudocode)
```python
# 1 analyzer.py

def analyze_source(path):
    diff = git_diff(path)
    tree = parse_ast(path)
    funcs, classes = extract_symbols(tree)
    flows = extract_calls(tree)
    metrics = compute_metrics(tree)
    return {
        "file": path,
        "functions": funcs,
        "classes": classes,
        "flows": flows,
        "metrics": metrics,
        "diff_summary": summarize_diff(diff),
    }

# 2 diagrammer.py

def generate_puml(analysis):
    nodes = [*analysis["classes"], *analysis["functions"]]
    edges = analysis["flows"]
    puml = "@startuml\n"
    for n in nodes:
        puml += f"class {n}\n"
    for a, b in edges:
        puml += f"{a} --> {b}\n"
    puml += "@enduml\n"
    return puml

# 3 reviewer.py

def generate_review(analysis):
    return f"""# Auto Review — {analysis['file']}

## Summary
{analysis['diff_summary']}

## Key Functions
{', '.join(analysis['functions'][:10])}

## Potential Risks
- TODO: evaluate complexity or security implications

## Suggested Tests
- Unit tests for new/modified functions
"""
```

### E) Outputs
- .puml → Docs/diagrams/file_diagrams/{basename}.puml (keeps architecture maps current)
- .md   → Docs/discussions/reviews/{date}_{basename}.md (rolling code review history)
Each output follows 3-way apply / append-only rules; every commit leaves a diff trail in .git/ai-rules-debug/.

### F) Integration with Orchestrator
```python
# automation/workflow.py (aggregation example)
if src_changed():
    from automation import analyzer, reviewer, diagrammer
    for f in changed_src_files:
        data = analyzer.analyze_source(f)
        diagrammer.update_puml(data)
        reviewer.update_review(data)
```
Future versions can post summaries to the feature’s implementation discussion and link diagrams into design/design.md.

### G) Testing the Source Automation Layer
- Unit: tests/unit/test_code_parser.py, tests/unit/test_puml_gen.py
- Integration: tests/integration/test_cases/test_auto_review.sh, test_auto_diagram.sh
- Fixtures: tests/integration/fixtures/repo_skeleton/src/ with fake commits to verify generation

### H) Security & Performance Notes
- Sandbox analysis only — no execution of user code
- AST parsing limited to static structure
- Large files (>5k lines): partial summarization
- Output capped to ≤ 200 KB per artifact

### I) Deliverables Added to Milestones
- M0 → create src/automation/ skeleton
- M1 → functional auto-review + auto-diagram for JS/TS files
- M2 → extend to Python + PlantUML cross-linking in design docs

## Discussion Summaries (Companion Artifacts per Stage)

### What it is
For every {stage}.discussion.md, maintain a sibling {stage}.summary.md. It is append-minimal with bounded section rewrites only (between stable markers). Contents: decisions, vote tallies, open questions, awaiting replies, action items, compact timeline.

### Where it lives
```text
Docs/features/FR_.../
└─ discussions/
   ├─ feature.discussion.md
   ├─ feature.summary.md
   ├─ design.discussion.md
   ├─ design.summary.md
   ├─ implementation.discussion.md
   ├─ implementation.summary.md
   ├─ testing.discussion.md
   ├─ testing.summary.md
   ├─ review.discussion.md
   └─ review.summary.md
```

### Header (machine-readable)
```yaml
---
type: discussion-summary
stage: feature               # feature|design|implementation|testing|review
status: ACTIVE               # ACTIVE|SNAPSHOT|ARCHIVED
source_discussion: feature.discussion.md
feature_id: FR_YYYY-MM-DD_<slug>
updated: YYYY-MM-DDTHH:MM:SSZ
policy:
  allow_agent_votes: true
  require_human_for: [implementation, review]
---
```

### Stable section markers (for tiny diffs)
```markdown
# Summary — <Stage Title>

<!-- SUMMARY:DECISIONS START -->
## Decisions (ADR-style)
- (none yet)
<!-- SUMMARY:DECISIONS END -->

<!-- SUMMARY:OPEN_QUESTIONS START -->
## Open Questions
- (none yet)
<!-- SUMMARY:OPEN_QUESTIONS END -->

<!-- SUMMARY:AWAITING START -->
## Awaiting Replies
- (none yet)
<!-- SUMMARY:AWAITING END -->

<!-- SUMMARY:ACTION_ITEMS START -->
## Action Items
- (none yet)
<!-- SUMMARY:ACTION_ITEMS END -->

<!-- SUMMARY:VOTES START -->
## Votes (latest per participant)
READY: 0 • CHANGES: 0 • REJECT: 0
- (no votes yet)
<!-- SUMMARY:VOTES END -->

<!-- SUMMARY:TIMELINE START -->
## Timeline (most recent first)
- <YYYY-MM-DD HH:MM> <name>: <one-liner>
<!-- SUMMARY:TIMELINE END -->

<!-- SUMMARY:LINKS START -->
## Links
- Related PRs: –
- Commits: –
- Design/Plan: ../design/design.md
<!-- SUMMARY:LINKS END -->
```

### How it updates
Trigger: whenever {stage}.discussion.md is staged, the hook also updates/creates {stage}.summary.md.

Deterministic logic:
- Votes: parse latest vote per participant (eligibility per policy)
- Decisions: if header status flips (e.g., READY_FOR_IMPLEMENTATION), append an ADR entry
- Open Questions: lines ending with ? or flagged Q: with @owner if present
- Awaiting Replies: mentions with no response from that participant within response_timeout_hours
- Action Items: unchecked tasks (- [ ]) with @owner remain tracked until checked
- Timeline: last N (default 15) comment one-liners with timestamp and name
- Links: auto-add PRs (#123), SHAs, and cross-file links

Rotation / snapshots (optional): when discussion grows large or on schedule, write discussions/summaries/<YYYY-MM-DD>.md (status: SNAPSHOT) and keep {stage}.summary.md trimmed while retaining Decisions/Open Q/Actions/Votes.

### Rules (additions in Docs/features/.ai-rules.yml)
```yaml
file_associations:
  "feature.discussion.md":        "feature_discussion"
  "design.discussion.md":         "design_discussion"
  "implementation.discussion.md": "impl_discussion"
  "testing.discussion.md":        "test_discussion"
  "review.discussion.md":         "review_discussion"

rules:
  feature_discussion:
    outputs:
      summary_companion:
        path: "{dir}/discussions/feature.summary.md"
        output_type: "discussion_summary_writer"
        instruction: |
          Create or update the summary file. Replace ONLY content between
          these markers: DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS,
          VOTES, TIMELINE, LINKS. Do not touch other lines.
          Inputs: the entire feature.discussion.md.          
  design_discussion:
    outputs:
      summary_companion:
        path: "{dir}/discussions/design.summary.md"
        output_type: "discussion_summary_writer"
        instruction: |
          Same summary policy as feature.summary.md; also add link to ../design/design.md.          
  impl_discussion:
    outputs:
      summary_companion:
        path: "{dir}/discussions/implementation.summary.md"
        output_type: "discussion_summary_writer"
        instruction: |
          Same summary policy; include unchecked items from ../implementation/tasks.md.          
  test_discussion:
    outputs:
      summary_companion:
        path: "{dir}/discussions/testing.summary.md"
        output_type: "discussion_summary_writer"
        instruction: |
          Same summary policy; include failing test artifacts and ensure FAILs surface in Open Questions or Awaiting.          
  review_discussion:
    outputs:
      summary_companion:
        path: "{dir}/discussions/review.summary.md"
        output_type: "discussion_summary_writer"
        instruction: |
          Same summary policy; Decisions should note READY_FOR_RELEASE with date and follow-ups.          
```

### Orchestrator support (nice-to-have)
Provide workflow.py --summarize <discussion-path> to output regenerated sections for tests/CI. Track awaiting replies via timestamps per author; if absent, mark as awaiting.

### Testing additions
- Unit: parsing of votes, questions, mentions, action items
- Integration: commit a discussion with constructs → verify summary sections updated and only marker-bounded hunks changed
- Failure: malformed discussion / huge file → generator still writes sections; timeline truncates; no crash

### Why this helps
Newcomers can open {stage}.summary.md and immediately see the state. Humans keep talking in the discussion; the system curates the signal in the summary. Promotions are transparent via Decisions. Open loops are visible and assigned.

## Implementation Plan
### Milestone M0: Process Foundation
Deliverables:

process/design.md (this document)

process/policies.md + process/policies.yml

process/templates/ (all four core templates)

automation/agents.yml (role mappings)

src/automation/ skeleton (analyzer.py, reviewer.py, diagrammer.py, utils/*)

Success Criteria:

All process documentation in place

Policy definitions machine-readable

Templates provide clear starting points

### Milestone M1: Orchestrator MVP + Hook Enhancements
Deliverables:

automation/workflow.py (non-blocking status reporter)

Bash hook: {dir} template variable support

Bash hook: Index preservation for 3-way apply

Bash hook: Append-only optimization for discussions

Auto-review + auto-diagram operational for JS/TS via root rules (js-file)

Success Criteria:

Python orchestrator reports discussion status

Template variables work for feature folder paths

3-way apply handles merge conflicts gracefully

### Milestone M2: Stage Automation & Moderator
Deliverables:

Enhanced Docs/features/.ai-rules.yml with stage rules

AI_Moderator implementation via discussion rules

Python orchestrator: policy-based decision hints

Test suite for feature promotion flow

Discussion summaries: rules (discussion_summary_writer) + tests

Success Criteria:

Feature requests auto-create discussions

Discussions promote through stages based on votes

Moderator provides useful conversation guidance

### Milestone M3: Gitea Integration
Deliverables:

automation/adapters/gitea_adapter.py

Automated PR creation and labeling

Status reporting to PR threads

Issue tracking integration

Success Criteria:

Implementation stage auto-creates PRs

Review status visible in PR discussions

Labels reflect current stage and blockers

### Milestone M4: Bash to Python Migration
Deliverables:

Core rule resolution logic in Python

Patch generation and application in Python

Bash hook as thin wrapper calling Python

Enhanced error handling and diagnostics

Success Criteria:

Maintains current functionality with better maintainability

Improved error messages and recovery options

Consistent behavior across all operations

## Risks & Mitigations
### Technical Risks
Over-Automation Bypassing Humans:

Risk: Critical decisions made without human oversight

Mitigation: Human READY gates for Implementation and Release stages

Control: Manual override capability for all automated promotions

Patch Instability on Large Files:

Risk: Hunk drift and merge conflicts in long discussions

Mitigation: 3-way apply with index preservation, append-only strategies

Fallback: Local diff computation from full content regeneration

Tooling Dependency Management:

Risk: Version conflicts or missing dependencies break system

Mitigation: Pre-flight validation with clear error messages

Recovery: Graceful degradation with feature flags

Context Limit Exceeded:

Risk: AI models cannot process very large discussions

Mitigation: Structured summarization, chunked processing

Alternative: Focus on recent changes with reference to history

13.2 Process Risks
Vote Manipulation or Gaming:

Risk: Participants exploit voting system for unwanted outcomes

Mitigation: Clear etiquette policies, human override capability

Oversight: Moderator monitoring for voting patterns

Discussion Fragmentation:

Risk: Conversations become scattered across multiple files

Mitigation: Clear stage boundaries, cross-references between discussions

Tooling: Search and navigation aids for related artifacts

Agent Coordination Conflicts:

Risk: Multiple agents making conflicting changes

Mitigation: Clear role definitions, sequential processing

Resolution: Human maintainer as final arbiter

13.3 Adoption Risks
Learning Curve:

Risk: New contributors struggle with system complexity

Mitigation: Comprehensive documentation, template guidance

Support: AI_Moderator provides onboarding assistance

Process Overhead:

Risk: System creates too much ceremony for small changes

Mitigation: Configurable rule enabling/disabling

Flexibility: Bypass options for trivial changes

14 Template Evolution
14.1 Versioning Strategy
Template Location as Version:

Current templates always in process/templates/

Breaking changes require new feature request and migration plan

Existing features use templates current at their creation

Migration Guidance:

Document template changes in release notes

Provide automated migration scripts for simple changes

Flag features using deprecated templates

14.2 Core Templates
Feature Request Template (process/templates/feature_request.md):

markdown
# Feature Request: <title>

**Feature ID**: <FR_YYYY-MM-DD_slug>
**Intent**: <one paragraph describing purpose>
**Motivation / Problem**: <why this is needed now>
**Constraints / Non-Goals**: <bulleted list of limitations>
**Rough Proposal**: <short implementation outline>
**Open Questions**: <bulleted list of uncertainties>
**Meta**: Created: <date> • Author: <name>
Discussion Template (process/templates/discussion.md):

markdown
---
type: discussion
stage: <feature|design|implementation|testing|review>
status: OPEN
feature_id: <FR_...>
created: <YYYY-MM-DD>

promotion_rule:
  allow_agent_votes: true
  ready_min_eligible_votes: all
  reject_min_eligible_votes: 1

participation:
  instructions: |
    - Append your input at the end as: "YourName: your comment…"
    - Every comment must end with a vote line: "VOTE: READY|CHANGES|REJECT"
    - Agents/bots must prefix names with "AI_"

voting:
  values: [READY, CHANGES, REJECT]
---

## Summary
2-4 sentence summary of current state

## Participation
comments appended below
Design Document Template (process/templates/design_doc.md):

```markdown
# Design — <FR id / Title>

## Context & Goals
## Non-Goals & Constraints
## Options Considered
## Decision & Rationale
## Architecture Diagram(s)
## Risks & Mitigations
## Acceptance Criteria (measurable)
```
Implementation Plan Template (process/templates/implementation_plan.md):

```markdown
# Implementation Plan — <FR id / Title>

## Scope
## Milestones
- [ ] M0: Initial setup and scaffolding
- [ ] M1: Core functionality
- [ ] M2: Testing and refinement
## Tasks
- [ ] specific actionable task
## Test Strategy
## Done When
- <clear, verifiable completion criteria>
```

Discussion Summary Template (process/templates/summary.md):

```markdown
# Summary — <Stage Title>
(Automatically maintained. Edit the discussion; this file will follow.)

<!-- SUMMARY:DECISIONS START -->
## Decisions (ADR-style)
- (none yet)
<!-- SUMMARY:DECISIONS END -->

<!-- SUMMARY:OPEN_QUESTIONS START -->
## Open Questions
- (none yet)
<!-- SUMMARY:OPEN_QUESTIONS END -->

<!-- SUMMARY:AWAITING START -->
## Awaiting Replies
- (none yet)
<!-- SUMMARY:AWAITING END -->

<!-- SUMMARY:ACTION_ITEMS START -->
## Action Items
- (none yet)
<!-- SUMMARY:ACTION_ITEMS END -->

<!-- SUMMARY:VOTES START -->
## Votes (latest per participant)
READY: 0 • CHANGES: 0 • REJECT: 0
- (no votes yet)
<!-- SUMMARY:VOTES END -->

<!-- SUMMARY:TIMELINE START -->
## Timeline (most recent first)
- <timestamp> <name>: <one-liner>
<!-- SUMMARY:TIMELINE END -->

<!-- SUMMARY:LINKS START -->
## Links
- Related PRs: –
- Commits: –
- Design/Plan: ../design/design.md
<!-- SUMMARY:LINKS END -->
```

## Roles & Agent Personas
### Human Roles
- Maintainer:
  - Final approval authority for critical stages
  - System configuration and rule definition
  - Conflict resolution and manual overrides
- Contributor:
  - Feature authorship and implementation
  - Participation in discussions and voting
  - Review and testing responsibilities

### AI Agent Roles
Defined in automation/agents.yml:
```yaml
agents:
  AI_Researcher:
    role: research_specialist
    stages: [request, discussion, design]
    capabilities: [web_search, documentation_review, best_practices]
    voting_weight: 0.5

  AI_Architect:
    role: software_architect
    stages: [design, implementation]
    capabilities: [system_design, tradeoff_analysis, diagram_generation]
    voting_weight: 0.8

  AI_Implementer:
    role: senior_developer
    stages: [implementation, review]
    capabilities: [code_generation, refactoring, testing_strategy]
    voting_weight: 0.7

  AI_Reviewer:
    role: quality_engineer
    stages: [review, test]
    capabilities: [code_review, risk_assessment, security_analysis]
    voting_weight: 0.9

  AI_Moderator:
    role: discussion_moderator
    stages: [discussion, design, review]
    capabilities: [progress_tracking, question_routing, vote_monitoring]
    voting_weight: 0.3
```

#### Role-Specific Responsibilities
- AI_Researcher:
  - Find prior art, RFCs, and reference implementations
  - Research technical constraints and dependencies
  - Identify potential risks and mitigation strategies
- AI_Architect:
  - Translate requirements into technical design plan
  - Create and maintain architecture diagrams
  - Evaluate trade-offs and make design recommendations
- AI_Implementer:
  - Propose code structure and implementation approaches
  - Generate code snippets and refactoring suggestions
  - Develop testing strategies and fixture plans
- AI_Reviewer:
  - Conduct adversarial code and design review
  - Identify edge cases and failure modes
  - Assess security and performance implications
- AI_Moderator:
  - Track discussion progress and participation
  - Identify unanswered questions and missing votes
  - Suggest next steps and task ownership

## Glossary
- FR: Feature Request — the initial document proposing new functionality
- Gate: Promotion decision point between stages based on policy thresholds
- Append-Only: Edit strategy that only adds new content to end of file, with optional header updates
- 3-way Apply: Patch application technique using blob IDs to reconcile content drift
- Cascading Rules: Rule resolution system where nearest directory's rules override parent directories
- Stage-Per-Discussion: Organizational pattern with separate conversation files for each development phase
- Human Gate: Promotion requirement that cannot be satisfied by AI votes alone
- Bug Sub-Cycle: Mini feature lifecycle automatically created for test failures
- Template Variables: Placeholders ({basename}, {date}, {dir}, {rel}) resolved in rule paths
- Vote Threshold: Minimum number or type of votes required for promotion
- Status Machine: Defined state transitions for discussion files (OPEN → READY_FOR_* → etc.)
- Orchestrator: Central coordination component managing rule execution and status tracking

## Appendices
### Appendix A: Complete Policy Configuration
```yaml
# process/policies.yml
version: 1
voting:
  values: [READY, CHANGES, REJECT]
  allow_agent_votes: true
  quorum:
    discussion:     { ready: all,      reject: 1 }
    design:         { ready: all,      reject: 1 }
    implementation: { ready: 1_human,  reject: 1 }
    testing:        { ready: all,      reject: 1 }
    review:         { ready: 1_human,  reject: 1 }
eligibility:
  agents_allowed: true
  require_human_for: [implementation, review]
etiquette:
  name_prefix_agents: "AI_"
  vote_line_regex: "^VOTE:\s*(READY|CHANGES|REJECT)\b"
  response_timeout_hours: 24
timeouts:
  discussion_stale_days: 3
  nudge_interval_hours: 24
  promotion_timeout_days: 14
```

### Appendix B: Diff Application Rules (Normative)
- Patch Sanitization Rules:
  - Preserve index lines for 3-way merge capability
  - Remove only fragile metadata (similarity, rename info)
  - Keep file mode lines (new file mode, deleted file mode)
  - Ensure proper header formatting for new files
- Application Order:
  - Attempt 3-way apply with recount and whitespace ignore
  - Fall back to strict apply if 3-way fails
  - For new files: use -p0 patch level with header rewriting
  - Validate patch with --check before application
- Error Handling:
  - Save all patch variants for debugging
  - Provide clear diagnostics on failure
  - Suggest manual resolution steps when automated recovery fails

### Appendix C: Complete Agent Definitions
```yaml
# automation/agents.yml
version: 1
agent_defaults:
  voting_weight: 0.5
  require_human_approval: false

agents:
  AI_Researcher:
    role: research_specialist
    description: "Finds prior art, documentation, and best practices"
    stages: [request, discussion, design]
    capabilities: 
      - web_search
      - documentation_review  
      - best_practices_research
      - risk_identification
    voting_weight: 0.5

  AI_Architect:
    role: software_architect
    description: "Designs system architecture and evaluates trade-offs"
    stages: [design, implementation]
    capabilities:
      - system_design
      - tradeoff_analysis
      - diagram_generation
      - technology_selection
    voting_weight: 0.8

  AI_Implementer:
    role: senior_developer  
    description: "Implements features and creates testing strategies"
    stages: [implementation, review]
    capabilities:
      - code_generation
      - refactoring
      - testing_strategy
      - performance_optimization
    voting_weight: 0.7

  AI_Reviewer:
    role: quality_engineer
    description: "Conducts security, risk, and quality analysis"
    stages: [review, test]
    capabilities:
      - code_review
      - risk_assessment
      - security_analysis
      - quality_validation
    voting_weight: 0.9

  AI_Moderator:
    role: discussion_moderator
    description: "Tracks progress and ensures participation"
    stages: [discussion, design, review]
    capabilities:
      - progress_tracking
      - question_routing
      - vote_monitoring
      - task_allocation
    voting_weight: 0.3
```

### Final Implementation Note
This v2.0 design document incorporates all insights from our collaborative discussion, providing a comprehensive framework for AI-human development collaboration. The system balances automation with appropriate human oversight, maintains the lightweight Git-native philosophy, and provides clear escalation paths from feature conception through release.

The stage-per-discussion model with automated artifact generation creates a self-documenting development process that scales from small features to large, complex implementations. The integrated bug sub-cycle ensures that quality issues are handled systematically without disrupting the main development flow.

Implementation Priority: Begin with Milestone M0 (process foundation) and proceed sequentially through the implementation plan, validating each milestone before proceeding to the next.

Document Version: 2.1
Last Updated: 2025-10-22
Status: READY_FOR_IMPLEMENTATION