2416 lines
92 KiB
Markdown
2416 lines
92 KiB
Markdown
# Cascading Development - 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.
|
||
|
||
> *Git-Native Philosophy: Every conversation, decision, and generated artifact lives in the same version-controlled environment as the source code. There are no external databases, dashboards, or SaaS dependencies required for the core workflow.
|
||
|
||
### Objective:
|
||
Establish a reproducible, self-documenting workflow where 90% of documentation, status artifacts and code changes are generated automatically from development discussions, while maintaining human oversight for all promotion gates and releases.
|
||
|
||
### 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
|
||
|
||
### Innovative Features
|
||
- 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
|
||
|
||
### System Overview:
|
||
The architecture consists of a lightweight Bash pre-commit hook for artifact generation, a Python orchestrator for state evaluation and policy enforcement, and optional adapters for model and API integrations (Claude, Gitea, etc.). Together they form a layered, rule-driven automation stack.
|
||
|
||
```text
|
||
Human → Git Commit → Pre-commit Hook → AI Generator → Markdown Artifact
|
||
↑ ↓
|
||
Orchestrator ← Discussion Summaries ← AI Moderator
|
||
```
|
||
|
||
## Repository Layout
|
||
|
||
### Canonical Structure (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
|
||
│ │ │ │ ├─ feature.discussion.sum.md # Summary of the request discussion
|
||
│ │ │ │ ├─ design.discussion.md # Discuss the design
|
||
│ │ │ │ ├─ design.discussion.sum.md # Summary of the design discussion
|
||
│ │ │ │ ├─ implementation.discussion.md # Track implementation
|
||
│ │ │ │ ├─ implementation.discussion.sum.md # Summary of the implementation discussion
|
||
│ │ │ │ ├─ testing.discussion.md # Plan/track testing
|
||
│ │ │ │ ├─ testing.discussion.sum.md # Summary of the testing discussion
|
||
│ │ │ │ ├─ review.discussion.md # Final review
|
||
│ │ │ │ └─ review.discussion.sum.md # Summary of the review discussion
|
||
│ │ │ ├─ 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 # Feature-specific 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 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
|
||
- Discussion summary: {stage}.discussion.sum.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 with extension (e.g., design.discussion.md)
|
||
- {name} — filename without extension (e.g., design.discussion)
|
||
- {ext} — file extension without dot (e.g., md)
|
||
- {date} — current date in YYYY-MM-DD
|
||
- {rel} — repository-relative path to the source file
|
||
- {dir} — directory containing the source file
|
||
- {feature_id} — nearest FR_* folder name (e.g., FR_2025-10-21_initial-feature-request)
|
||
- {stage} — stage inferred from discussion filename (<stage>.discussion.md), e.g., feature|design|implementation|testing|review
|
||
|
||
## Stage Model & Operational Procedure
|
||
|
||
### Complete Stage Lifecycle
|
||
```text
|
||
Request → Feature Discussion → Design Discussion → Implementation Discussion → Testing Discussion → Review Discussion → Release
|
||
```
|
||
### Stage Overview
|
||
|
||
| Stage | Primary File | Promotion Trigger | Human Gate | Key Artifacts Created |
|
||
|:------|:-------------|:------------------|:-----------|:----------------------|
|
||
| 1 Request | request.md | Created from template | – | feature.discussion.md, feature.discussion.sum.md |
|
||
| 2 Feature Discussion | discussions/feature.discussion.md | Votes → READY_FOR_DESIGN | – | design.discussion.md, design/design.md |
|
||
| 3 Design Discussion | discussions/design.discussion.md | Votes → READY_FOR_IMPLEMENTATION | – | implementation.discussion.md, implementation/plan.md, implementation/tasks.md |
|
||
| 4 Implementation Discussion | discussions/implementation.discussion.md | All required tasks complete → READY_FOR_TESTING | ✅ ≥1 human READY | testing.discussion.md, testing/testplan.md, testing/checklist.md |
|
||
| 5 Testing Discussion | discussions/testing.discussion.md | All tests pass → READY_FOR_REVIEW | – | review.discussion.md, review/findings.md |
|
||
| 6 Review Discussion | discussions/review.discussion.md | Human READY → READY_FOR_RELEASE | ✅ ≥1 human READY | Release notes, follow-up FRs/Bugs |
|
||
| 7 Release | – | Tag & changelog generated | ✅ maintainer | Changelog, version bump, rollback notes |
|
||
|
||
### 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>
|
||
stage_id: FR_YYYY-MM-DD_<slug>_feature
|
||
created: YYYY-MM-DD
|
||
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: all
|
||
reject_min_eligible_votes: all
|
||
|
||
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 decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- Establishes objectives with consensus
|
||
- Delegates in-conversation tasks
|
||
- Creates/maintains discussions/feature.discussion.sum.md
|
||
> **Automation boundary:** All actions occur within the same Git commit and are never auto-committed by the orchestrator.
|
||
|
||
#### Promotion Actions
|
||
- Creates discussions/design.discussion.md (OPEN)
|
||
- Creates design/design.md seeded from request + feature discussion
|
||
|
||
### Stage 3: Design Discussion
|
||
- File: discussions/design.discussion.md
|
||
|
||
#### Header
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: design
|
||
status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
stage_id: FR_YYYY-MM-DD_<slug>_design
|
||
# ... 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
|
||
|
||
_Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes objective
|
||
- delegates in-conversation tasks
|
||
- Creates/maintains discussions/design.discussion.sum.md
|
||
- Creates/maintains design/design.md
|
||
- Creates/maintains design/diagrams/*.puml files if any are produced during the discussion.
|
||
|
||
#### 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
|
||
- Creates 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
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
stage_id: FR_YYYY-MM-DD_<slug>_implementation
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||
reject_min_eligible_votes: all
|
||
# ...
|
||
---
|
||
```
|
||
|
||
#### 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
|
||
|
||
_Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes implementation objectives from Plan.md
|
||
- delegates implementation tasks from Tasks.md
|
||
- Creates/maintains discussions/implementation.discussion.sum.md
|
||
- Creates/maintains src/* files if any are produced during the discussion.
|
||
|
||
#### 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
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
stage_id: FR_YYYY-MM-DD_<slug>_testing
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: all
|
||
reject_min_eligible_votes: all
|
||
```
|
||
---
|
||
|
||
|
||
#### 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
|
||
|
||
_Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes testing objectives from testing/testplan.md and testing/checklist.md
|
||
- delegates testing tasks from testing/checklist.md
|
||
- Creates/maintains discussions/testing.discussion.sum.md
|
||
- Creates/maintains test/* files if any are produced during the discussion.
|
||
|
||
|
||
#### Bug Sub-Cycle Creation
|
||
|
||
```text
|
||
bugs/BUG_YYYYMMDD_<slug>/
|
||
├─ report.md # Steps, expected/actual, environment
|
||
├─ discussion.md # Bug discussion (OPEN)
|
||
├─ discussion.sum.md # Summary of Bug discussion
|
||
└─ fix/
|
||
├─ plan.md # Fix implementation plan
|
||
└─ tasks.md # Fix tasks checklist
|
||
└─ src/
|
||
```
|
||
|
||
#### Bug Resolution Flow
|
||
- Bug follows mini Implementation→Testing cycle
|
||
- On bug closure, return to main testing discussion
|
||
- Bug results integrated into main test checklist
|
||
|
||
_The bug sub-cycle mirrors Stages 4–6 (Implementation → Testing → Review) and inherits the same promotion and voting policies._
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote to discussion.md
|
||
- Moderates discussion
|
||
- establishes fix objectives from plan.md
|
||
- delegates fix tasks from tasks.md
|
||
- Maintains discussions/discussion.sum.md
|
||
- Creates/maintains fix/src/* files if any are produced during the discussion.
|
||
|
||
#### Promotion Actions
|
||
- Creates or report to discussions/review.discussion.md (OPEN)
|
||
- Creates review/findings_BUG_YYYYMMDD_<slug>.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
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
stage_id: FR_YYYY-MM-DD_<slug>_review
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||
reject_min_eligible_votes: all
|
||
# ...
|
||
---
|
||
```
|
||
|
||
#### 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
|
||
|
||
_Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._
|
||
|
||
#### 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
|
||
|
||
_State machine summary:_ All stage transitions are governed by the orchestrator and thresholds defined in `process/policies.yml`. Human gates remain mandatory for Implementation and Release.
|
||
|
||
|
||
## 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
|
||
- Trailing spaces are ignored; the vote must be the final non-empty line
|
||
|
||
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)
|
||
```
|
||
**Update Rules**
|
||
- Latest vote per participant supersedes all prior votes in the same stage.
|
||
- If a comment has multiple “VOTE:” lines, only the **last** valid line counts.
|
||
- Empty or malformed vote lines are ignored (no implicit abstain).
|
||
|
||
### 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: all }
|
||
implementation: { ready: 1_human, reject: all }
|
||
release: { ready: 1_human, reject: all }
|
||
eligibility:
|
||
agents_allowed: true
|
||
require_human_for: [implementation, release]
|
||
etiquette:
|
||
name_prefix_agents: "AI_"
|
||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\s*$"
|
||
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
|
||
|
||
### Promotion Evaluation Algorithm
|
||
1. Parse latest vote per participant (apply `vote_line_regex` to final non-empty line).
|
||
2. Filter by eligibility (humans/agents per stage policy).
|
||
3. Check human-gate requirement (if configured for the stage).
|
||
4. Evaluate quorum thresholds from `voting.quorum[stage]`:
|
||
- `ready: all` → all eligible voters are `READY` (or no `CHANGES/REJECT`)
|
||
- `ready: 1_human` → at least one human `READY`
|
||
- `reject: all` → if any `REJECT`, fail promotion
|
||
5. If thresholds met → flip `status` to the target (e.g., `READY_FOR_DESIGN`) **within the same commit** and generate next artifacts.
|
||
6. If not met → append moderator summary and keep status unchanged.
|
||
|
||
Eligibility Definition
|
||
- Eligible voter: any participant (human or agent) who posted in the current stage discussion and conforms to eligibility.* policy.
|
||
- Human gate: stages listed in eligibility.require_human_for require ≥ 1 human READY regardless of agent votes.
|
||
|
||
### 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
|
||
- Staleness & Nudges: If a stage has no new comments within `discussion_stale_days`, the AI_Moderator posts a nudge every `nudge_interval_hours` with missing votes and open questions.
|
||
|
||
### Tie-breaks & Deadlocks
|
||
- If votes include both `READY` and `CHANGES/REJECT` beyond the promotion timeout (`promotion_timeout_days`), the AI_Moderator escalates:
|
||
1) Summarize blocking points and owners,
|
||
2) Request explicit human decision,
|
||
3) If still unresolved after one more nudge window, maintain status and open a follow-up item in the summary’s **ACTION_ITEMS**.
|
||
|
||
## Cascading Rules System
|
||
The Cascading Rules System defines how automation instructions are discovered and applied
|
||
for any file committed in the repository. The nearest `.ai-rules.yml` file to a changed
|
||
file determines how it will be processed. Rules can exist at three scopes:
|
||
|
||
| Scope | Typical Path | Purpose |
|
||
|:------|:-------------|:---------|
|
||
| **Global** | `/.ai-rules.yml` | Default behavior for all files (e.g., code, diagrams) |
|
||
| **Feature-Scoped** | `Docs/features/.ai-rules.yml` | Rules specific to feature discussions and artifacts |
|
||
| **Local / Experimental** | `<feature>/local/.ai-rules.yml` (optional) | Overrides for prototypes or nested modules |
|
||
|
||
Rule lookup always starts in the source file’s directory and walks upward until it finds
|
||
a `.ai-rules.yml`, then merges settings from outer scopes, where **nearest directory wins**.
|
||
|
||
### 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"
|
||
```
|
||
### Validation & Schema
|
||
Each `.ai-rules.yml` must pass a lightweight YAML schema check before execution:
|
||
- `version` key is required (integer or semver)
|
||
- `file_associations` maps glob patterns → rule names
|
||
- Each rule under `rules:` must include at least one of:
|
||
- `description`, `outputs:` with `path`, `output_type`, and `instruction`
|
||
- Unknown keys are ignored but logged as warnings.
|
||
|
||
Schema validation prevents mis-typed keys from silently breaking automation.
|
||
|
||
### Feature-Scoped Rules (Docs/features/.ai-rules.yml)
|
||
```yaml
|
||
version: 1
|
||
|
||
file_associations:
|
||
"request.md": "feature_request"
|
||
|
||
# discussions
|
||
"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"
|
||
|
||
# summaries (companions)
|
||
"feature.discussion.sum.md": "discussion_summary"
|
||
"design.discussion.sum.md": "discussion_summary"
|
||
"implementation.discussion.sum.md": "discussion_summary"
|
||
"testing.discussion.sum.md": "discussion_summary"
|
||
"review.discussion.sum.md": "discussion_summary"
|
||
|
||
rules:
|
||
feature_request:
|
||
outputs:
|
||
feature_discussion:
|
||
path: "{dir}/discussions/feature.discussion.md"
|
||
output_type: "feature_discussion_writer"
|
||
instruction: |
|
||
If missing: create with standard header (stage: feature, status: OPEN),
|
||
add Summary and Participation sections, then append initial AI comment with vote.
|
||
If exists: no op.
|
||
|
||
# Also create the companion summary file if missing (blank sections with markers)
|
||
feature_summary_init:
|
||
path: "{dir}/discussions/feature.discussion.sum.md"
|
||
output_type: "discussion_summary_init"
|
||
instruction: |
|
||
If missing, create companion summary with stable markers:
|
||
DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS, VOTES, TIMELINE, LINKS.
|
||
If exists, do not modify.
|
||
|
||
feature_discussion:
|
||
outputs:
|
||
# 1) Append the new AI comment to the discussion (append-only)
|
||
self_append:
|
||
path: "{dir}/discussions/feature.discussion.md"
|
||
output_type: "feature_discussion_writer"
|
||
instruction: |
|
||
Append concise comment signed with AI name, ending with a single vote line.
|
||
Evaluate votes against header thresholds. If READY threshold met:
|
||
- Flip status to READY_FOR_DESIGN (or FEATURE_REJECTED)
|
||
Clearly state promotion decision. Append-only with minimal diff.
|
||
|
||
# 2) Update the companion summary (marker-bounded sections only)
|
||
summary_companion:
|
||
path: "{dir}/discussions/feature.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Create or update the summary file. Replace ONLY content between markers:
|
||
DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS, VOTES, TIMELINE, LINKS.
|
||
Inputs: the entire feature.discussion.md and current header.
|
||
Keep diffs minimal.
|
||
|
||
# 3) Promotion artifacts when READY_FOR_DESIGN
|
||
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 from request.md and feature discussion.
|
||
Include: Context, Options, Decision, Risks, Acceptance Criteria.
|
||
|
||
# Ensure design summary exists once design discussion begins
|
||
design_summary_init:
|
||
path: "{dir}/discussions/design.discussion.sum.md"
|
||
output_type: "discussion_summary_init"
|
||
instruction: |
|
||
If missing, create companion summary with standard markers.
|
||
If exists, do not modify unless via discussion_summary_writer.
|
||
|
||
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.
|
||
|
||
# Always keep the design summary in sync (marker-bounded)
|
||
summary_companion:
|
||
path: "{dir}/discussions/design.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Update only the marker-bounded sections from the discussion content.
|
||
|
||
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.
|
||
|
||
# Ensure implementation summary exists at the moment implementation starts
|
||
impl_summary_init:
|
||
path: "{dir}/discussions/implementation.discussion.sum.md"
|
||
output_type: "discussion_summary_init"
|
||
instruction: |
|
||
If missing, create companion summary with standard markers.
|
||
|
||
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.
|
||
|
||
summary_companion:
|
||
path: "{dir}/discussions/implementation.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Update only the marker-bounded sections from the discussion content.
|
||
Include unchecked items from ../implementation/tasks.md in ACTION_ITEMS.
|
||
|
||
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 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_summary_init:
|
||
path: "{dir}/discussions/testing.discussion.sum.md"
|
||
output_type: "discussion_summary_init"
|
||
instruction: |
|
||
If missing, create companion summary with standard markers.
|
||
|
||
test_discussion:
|
||
outputs:
|
||
checklist_update:
|
||
path: "{dir}/testing/checklist.md"
|
||
output_type: "testchecklist_maintainer"
|
||
instruction: |
|
||
Parse [RESULT] PASS/FAIL blocks from test discussion.
|
||
Update checklist accordingly with evidence links.
|
||
On test failure, create appropriate bug report.
|
||
|
||
summary_companion:
|
||
path: "{dir}/discussions/testing.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Update marker-bounded sections from the discussion content.
|
||
Surface FAILs in OPEN_QUESTIONS or AWAITING with owners.
|
||
|
||
bug_report:
|
||
path: "{dir}/bugs/BUG_{date}_auto/report.md"
|
||
output_type: "bug_report_writer"
|
||
instruction: |
|
||
Create bug report ONLY when test failure has clear reproduction steps.
|
||
Initialize bug discussion and fix plan in the 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_summary_init:
|
||
path: "{dir}/discussions/review.discussion.sum.md"
|
||
output_type: "discussion_summary_init"
|
||
instruction: |
|
||
If missing, create companion summary with standard markers.
|
||
|
||
review_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/review.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Update marker-bounded sections from the discussion content.
|
||
Decisions should include READY_FOR_RELEASE with date and follow-ups.
|
||
|
||
followup_feature:
|
||
path: "../../FR_{date}_followup/request.md"
|
||
output_type: "feature_request_writer"
|
||
instruction: |
|
||
Create follow-up feature request ONLY when review identifies an enhancement.
|
||
|
||
followup_bug:
|
||
path: "{dir}/bugs/BUG_{date}_review/report.md"
|
||
output_type: "bug_report_writer"
|
||
instruction: |
|
||
Create bug report ONLY when review identifies a defect.
|
||
Seed discussion and fix plan.
|
||
|
||
# Generic writer invoked when a *.discussion.sum.md file itself is staged/edited
|
||
discussion_summary:
|
||
outputs:
|
||
normalize:
|
||
path: "{dir}/{basename}.sum.md"
|
||
output_type: "discussion_summary_normalizer"
|
||
instruction: |
|
||
Ensure standard header exists and marker blocks are present.
|
||
Do not rewrite content outside markers.
|
||
|
||
```
|
||
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
|
||
**Principles**
|
||
- **Single-commit boundary:** automation only stages changes within the *current* commit; it never creates new commits or loops.
|
||
- **Deterministic prompts:** identical inputs produce identical patches (prompt hashing + stable sorting of inputs).
|
||
- **Nearest-rule wins:** rule resolution favors the closest `.ai-rules.yml`.
|
||
- **Fail fast, explain:** on any failure, keep the index untouched and write actionable diagnostics to `.git/ai-rules-debug/`.
|
||
|
||
### Bash Pre-commit Hook
|
||
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
|
||
|
||
Prompt Envelope (deterministic)
|
||
```text
|
||
BEGIN ENVELOPE
|
||
VERSION: 1
|
||
SOURCE_FILE: <rel_path>
|
||
RULE: <rule_name>/<output_key>
|
||
FEATURE_ID: <feature_id>
|
||
STAGE: <stage>
|
||
POLICY_SHA256: <sha of process/policies.yml>
|
||
CONTEXT_FILES: <sorted list>
|
||
PROMPT_SHA256: <sha of everything above + inputs>
|
||
--- INPUT:FILE ---
|
||
<trimmed content or staged diff>
|
||
--- INPUT:POLICY ---
|
||
<process/policies.yml relevant subset>
|
||
--- INSTRUCTION ---
|
||
<rules.outputs[*].instruction>
|
||
END ENVELOPE
|
||
```
|
||
On output, the model must return only a unified diff between
|
||
`<<<AI_DIFF_START>>>` and `<<<AI_DIFF_END>>>`. The orchestrator records
|
||
`PROMPT_SHA256` alongside the patch for reproducibility.
|
||
|
||
Execution Order (per staged file)
|
||
1) **resolve_rules(rel_path)** → pick nearest `.ai-rules.yml`, match `file_associations`, assemble outputs.
|
||
2) **build_prompt(ctx)** → gather file content/diff, parsed headers, policy, `{feature_id}/{stage}` and neighboring artifacts.
|
||
3) **invoke_model(prompt)** → receive a **unified diff** envelope (no raw text rewrites).
|
||
4) **sanitize_diff()** → enforce patch constraints (no path traversal, within repo, size limits).
|
||
5) **apply_patch()** → try 3-way apply, then strict apply; stage only on success.
|
||
6) **log_diagnostics()** → write `resolution.log`, raw/clean/sanitized/final diffs.
|
||
|
||
Enhanced Template Support:
|
||
|
||
```bash
|
||
# Add/extend in resolve_template() function
|
||
resolve_template() {
|
||
local tmpl="$1" rel_path="$2"
|
||
local today dirpath basename name ext feature_id stage
|
||
today="$(date +%F)"
|
||
dirpath="$(dirname "$rel_path")"
|
||
basename="$(basename "$rel_path")"
|
||
name="${basename%.*}"
|
||
ext="${basename##*.}"
|
||
# nearest FR_* ancestor as feature_id
|
||
feature_id="$(echo "$rel_path" | sed -n 's|.*Docs/features/\(FR_[^/]*\).*|\1|p')"
|
||
# infer stage from <stage>.discussion.md when applicable
|
||
stage="$(echo "$basename" | sed -n 's/^\([A-Za-z0-9_-]\+\)\.discussion\.md$/\1/p')"
|
||
echo "$tmpl" \
|
||
| sed -e "s|{date}|$today|g" \
|
||
-e "s|{rel}|$rel_path|g" \
|
||
-e "s|{dir}|$dirpath|g" \
|
||
-e "s|{basename}|$basename|g" \
|
||
-e "s|{name}|$name|g" \
|
||
-e "s|{ext}|$ext|g" \
|
||
-e "s|{feature_id}|$feature_id|g" \
|
||
-e "s|{stage}|$stage|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/
|
||
|
||
Additional Safeguards:
|
||
- Reject patches that:
|
||
- create or edit files outside the repo root
|
||
- exceed 200 KB per artifact (configurable)
|
||
- modify binary or non-targeted files for the current output
|
||
- Normalize line endings; ensure new files include headers when required.
|
||
- Abort on conflicting hunks; do not partially apply a file’s patch.
|
||
|
||
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
|
||
- Enforce append-only: refuse hunks that modify prior lines except header keys explicitly allowed (`status`, timestamps, `feature_id`, `stage_id`).
|
||
|
||
### 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
|
||
|
||
#### Optimization Notes:
|
||
- Memoize `load_policy()` and `parse_front_matter()` with LRU caches.
|
||
- Reuse a single regex object for `vote_line_regex`.
|
||
- Avoid re-reading unchanged files by comparing `git hash-object` results.
|
||
|
||
#### CLI (v1):
|
||
- workflow.py --status # print stage/vote status for staged files
|
||
- workflow.py --summarize <path> # regenerate summary sections to stdout (no write)
|
||
- workflow.py --dry-run # run full pipeline but do not stage patches
|
||
- Outputs are written to stdout and .git/ai-rules-debug/orchestrator.log.
|
||
|
||
#### Future Enhancements:
|
||
- Policy enforcement based on process/policies.yml
|
||
- Gitea API integration for issue/PR management
|
||
- Advanced agent coordination and task routing
|
||
|
||
#### Model Invocation (env-configured)
|
||
- `AI_MODEL_CMD` (default: `claude`) and `AI_MODEL_OPTS` are read from env.
|
||
- `AI_RULES_SEED` allows deterministic sampling where supported.
|
||
- If the model returns non-diff output, the hook aborts with diagnostics.
|
||
|
||
#### Environment toggles:
|
||
- `AI_RULES_MAX_JOBS` caps parallel workers (default 4)
|
||
- `AI_RULES_CACHE_DIR` overrides `.git/ai-rules-cache`
|
||
- `AI_RULES_DISABLE_CACHE=1` forces re-generation
|
||
- `AI_RULES_CI=1` enables dry-run & cache-only in CI
|
||
### 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
|
||
|
||
#### Happy Path (single changed discussion file)
|
||
```text
|
||
git add Docs/features/FR_x/.../feature.discussion.md
|
||
└─ pre-commit
|
||
├─ resolve_rules → feature_discussion + summary_companion
|
||
├─ build_prompt (PROMPT_SHA256=…)
|
||
├─ invoke_model → <<<AI_DIFF_START>>>…<<<AI_DIFF_END>>>
|
||
├─ sanitize_diff + guards
|
||
├─ apply_patch (3-way → strict)
|
||
└─ write logs under .git/ai-rules-debug/
|
||
```
|
||
|
||
## 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
|
||
|
||
##### Signals & Triggers
|
||
- **Unanswered Qs:** any line ending with `?` or prefixed `Q:` with an `@owner` and no reply within `response_timeout_hours`.
|
||
- **Missing Votes:** participants who posted in the stage but whose last non-empty line does not match `vote_line_regex`.
|
||
- **Stale Discussion:** no new comments within `discussion_stale_days`.
|
||
- **Promotion Drift:** conflicting votes present beyond `promotion_timeout_days`.
|
||
|
||
#### 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
|
||
|
||
##### Comment Template & Constraints:
|
||
- Max 10 lines, each ≤ 120 chars.
|
||
- Sections in order: **UNANSWERED**, **VOTES**, **ACTION ITEMS**, **STATUS**.
|
||
- Always end with `VOTE: CHANGES` (so it never promotes by itself).
|
||
|
||
#### 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?"
|
||
|
||
##### Escalation Path:
|
||
- If blockers persist past `promotion_timeout_days`, ping owners + maintainer.
|
||
- If still unresolved after one more nudge interval, create a follow-up entry in the summary’s **ACTION_ITEMS** with owner + due date.
|
||
|
||
### Moderator Implementation
|
||
Rule Definition (in Docs/features/.ai-rules.yml):
|
||
|
||
```yaml
|
||
discussion_moderator_nudge:
|
||
outputs:
|
||
self_append:
|
||
path: "{dir}/discussions/{stage}.discussion.md"
|
||
output_type: "discussion_moderator_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.
|
||
UNANSWERED: list @owners for Qs > response_timeout_hours.
|
||
VOTES: READY=X, CHANGES=Y, REJECT=Z; Missing=[@a, @b]
|
||
ACTION: concrete next steps with @owner and a due date.
|
||
STATUS: promotion readiness per process/policies.yml (voting.quorum).
|
||
Constraints: ≤10 lines; ≤120 chars/line; append-only; end with:
|
||
VOTE: CHANGES
|
||
```
|
||
Nudge Frequency: Controlled by nudge_interval_hours in policies
|
||
> **Automation boundary:** Moderator comments are appended within the current commit; no auto-commits are created.
|
||
|
||
## Error Handling & Resilience
|
||
|
||
### Safety Invariants
|
||
- **No auto-commits:** automation only stages changes in the current commit.
|
||
- **Atomic per-file:** a patch for a file applies all-or-nothing; no partial hunks.
|
||
- **Append-first for discussions:** prior lines are immutable except allowed header keys.
|
||
- **Inside repo only:** patches cannot create/modify files outside the repository root.
|
||
- **Deterministic retry:** identical inputs → identical patches (same prompt hash).
|
||
|
||
### 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
|
||
- Exit code: 2 (apply failure); write `final.diff` and `apply.stderr`
|
||
|
||
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
|
||
- Exit code: 3 (invalid diff); write `raw.out`, `clean.diff`, `sanitize.log`
|
||
|
||
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
|
||
- Exit code: 4 (missing dependency); write `preflight.log`
|
||
|
||
Rule Conflicts:
|
||
- Symptom: Multiple rules matching same file with conflicting instructions
|
||
- Mitigation: Nearest-directory precedence with conflict logging
|
||
- Fallback: Global rule application with warning
|
||
- Exit code: 5 (rule resolution); write `resolution.log`
|
||
|
||
Guardrail Violations:
|
||
- Symptom: Patch touches forbidden paths, exceeds size, or edits outside markers
|
||
- Mitigation: Reject patch, print exact guard name and offending path/line count
|
||
- Exit code: 6 (guardrail); write `guards.json`
|
||
|
||
### Retry & Idempotency
|
||
- Re-run the same commit contents → identical `PROMPT_SHA256` and identical patch.
|
||
- To force a new generation, change *only* the source file content or the rule instruction.
|
||
- `--dry-run` prints the unified diff without staging; useful for CI and reproduction.
|
||
|
||
### Recovery Procedures
|
||
|
||
#### Quick Triage Map
|
||
| Failure | Where to Look | Fast Fix |
|
||
|---|---|---|
|
||
| Patch won’t apply | `.git/ai-rules-debug/*/apply.stderr` | Rebase or re-run after pulling; if discussion, ensure append-only |
|
||
| Invalid diff envelope | `raw.out`, `clean.diff`, `sanitize.log` | Check that model returned `<<<AI_DIFF_START/END>>>`; shorten file context |
|
||
| Rule not found | `resolution.log` | Verify `file_associations` and `{stage}`/`{feature_id}` resolution |
|
||
| Guardrail breach | `guards.json` | Reduce patch size, keep edits within markers, or adjust config limit |
|
||
| Missing dependency | `preflight.log` | Install tool or disable rule until available |
|
||
|
||
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
|
||
- Rule resolution decisions saved to `.git/ai-rules-debug/resolution.log` including matched rule, output keys, and template-expanded paths.
|
||
|
||
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
|
||
|
||
Regenerate Safely:
|
||
```bash
|
||
# See what would be generated without staging anything
|
||
automation/workflow.py --dry-run
|
||
# Apply only after inspection
|
||
git add -p
|
||
````
|
||
Bypass & Minimal Patch:
|
||
```bash
|
||
# Temporarily bypass the hook for urgent hand-edits
|
||
git commit --no-verify -m "Hotfix: manual edit, will reconcile with rules later"
|
||
```
|
||
|
||
### Audit Trail
|
||
|
||
#### Patch Sanitization & Guards (summary)
|
||
- Validate unified diff headers; reject non-diff content.
|
||
- Enforce append-only on discussions; allow header keys: status, feature_id, stage_id, timestamps.
|
||
- Enforce marker-bounded edits for *.discussion.sum.md.
|
||
- Limit per-artifact patch size (default 200 KB; configurable).
|
||
- Reject paths escaping repo root or targeting binaries.
|
||
- See Appendix B for the normative, full rule set.
|
||
|
||
#### 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
|
||
```
|
||
### Operator Checklist (1-minute)
|
||
1. git status → confirm only intended files are staged.
|
||
2. Open .git/ai-rules-debug/…/apply.stderr (if failed) or final.diff.
|
||
3. If discussion file: ensure your change is append-only.
|
||
4. Re-run automation/workflow.py --dry-run and compare diffs.
|
||
5. If still blocked, bypass with --no-verify, commit, and open a follow-up to reconcile.
|
||
|
||
## Security & Secrets Management
|
||
|
||
### Security Principles
|
||
- **No plaintext secrets in Git** — ever.
|
||
- **Scan before stage** — block secrets at pre-commit, not in CI.
|
||
- **Redact on write** — debug logs and prompts never store raw secrets.
|
||
- **Least scope** — env vars loaded only for the current process; not persisted.
|
||
|
||
### Secret Protection
|
||
#### Never Commit:
|
||
- API keys, authentication tokens
|
||
- Personal identifying information
|
||
- Internal system credentials
|
||
- Private configuration data
|
||
|
||
#### Secret Scanning & Blocking (pre-commit):
|
||
- Run lightweight detectors before rule execution; fail fast on matches.
|
||
- Suggested tools (any one is fine): `git-secrets`, `gitleaks`, or `trufflehog` (regex mode).
|
||
- Provide a repo-local config at `process/secrets.allowlist` to suppress false positives.
|
||
|
||
#### Redaction Policy:
|
||
- If a candidate secret is detected in an input file, the hook **aborts**.
|
||
- If a secret appears only in model output or logs, it is **replaced** with `***REDACTED***` before writing artifacts.
|
||
|
||
#### Inbound/Outbound Data Handling:
|
||
- **Inbound (source & discussions):** if a suspected secret is present, the hook blocks the commit and points to the line numbers.
|
||
- **Outbound (logs, envelopes, diffs):** redact values and include a `[REDACTED:<key>]` tag to aid debugging without leakage.
|
||
|
||
#### 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
|
||
```
|
||
.gitignore (additions):
|
||
```
|
||
.env
|
||
.env.*
|
||
# .env.local, .env.prod, etc.
|
||
*.key
|
||
*.pem
|
||
*.p12
|
||
secrets/*.json
|
||
secrets/*.yaml
|
||
```
|
||
Provide non-sensitive examples as *.sample:
|
||
- .env.sample with placeholder keys
|
||
- automation/config.sample.yml showing structure without values
|
||
|
||
Configuration Management:
|
||
- Keep sensitive endpoints in automation/config.yml
|
||
- Use environment variable substitution in configuration
|
||
- Validate no secrets in discussions, rules, or generated artifacts
|
||
- Substitution happens **in-memory** during prompt build; no expanded values are written back to disk.
|
||
- Maintain a denylist of key names that must never appear in artifacts: `API_KEY, ACCESS_TOKEN, SECRET, PASSWORD, PRIVATE_KEY`.
|
||
|
||
### Access Control
|
||
Repository Security:
|
||
- Assume all repository contents are potentially exposed
|
||
- No sensitive business logic in prompt instructions
|
||
- Regular security reviews of rule definitions
|
||
- Guardrails: outputs cannot target paths outside repo root; writes to `secrets/` are blocked.
|
||
|
||
Agent Permissions:
|
||
- Limit file system access to repository scope
|
||
- Validate output paths stay within repository
|
||
- Sanitize all file operations for path traversal
|
||
- Prompt Redaction: when building the model prompt, mask env-like values with `***REDACTED***` for any key matching the denylist or high-entropy detector.
|
||
- See **Appendix B: Diff Application Rules (Normative)** for the full list of path/size/marker guardrails enforced during patch application.
|
||
|
||
|
||
### Incident Response & Rotation
|
||
- If a secret is accidentally committed, immediately:
|
||
1) Rotate the key at the provider,
|
||
2) Purge it from Git history (e.g., `git filter-repo`),
|
||
3) Invalidate caches and re-run the secret scanner.
|
||
- Track rotations in a private runbook (outside the repo).
|
||
|
||
### Preflight Checks (hook)
|
||
- Verify required tools present: `git`, `python3`, `yq` (optional), chosen secret scanner.
|
||
- Run secret scanner against **staged** changes; on hit → exit 11.
|
||
- Validate `.ai-rules.yml` schema; on error → exit 12.
|
||
- Confirm patch guards (size/paths); violations → exit 13.
|
||
- Diagnostics: write to `.git/ai-rules-debug/preflight.log`.
|
||
|
||
## Performance & Scale Considerations
|
||
### Optimization Strategies
|
||
|
||
#### Deterministic Caching & Batching:
|
||
- **Prompt cache**: reuse model outputs when `PROMPT_SHA256` is identical.
|
||
- **Batch compatible files**: same rule/output pairs with small contexts can be grouped.
|
||
- **Stable ordering**: sort staged files + outputs before batching to keep results repeatable.
|
||
- **Cache location**: `.git/ai-rules-cache/` (keys by `PROMPT_SHA256` + rule/output).
|
||
|
||
#### 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
|
||
- Preload policy once per run; inject only relevant subsections into the prompt
|
||
- Memoize parsed front-matter (YAML) and ASTs across files in the same run
|
||
- Trim discussion context to the last N lines (configurable) + stable summary
|
||
|
||
#### Discussion Management:
|
||
- Append-only edits with periodic summarization
|
||
- Compact status reporting in moderator comments
|
||
- Archive completed discussions if they become too large
|
||
- Sliding-window summarization: regenerate `{stage}.discussion.sum.md` when diff > threshold lines
|
||
- Limit TIMELINE to the last 15 entries (configurable)
|
||
|
||
#### 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
|
||
- Cap parallelism with `AI_RULES_MAX_JOBS` (default 4) to avoid CPU thrash.
|
||
- Deduplicate prompts for identical contexts across multiple outputs.
|
||
|
||
### 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
|
||
- Very large (>5MB): refuse inline context; require pre-summarized artifacts
|
||
|
||
#### Context Window Strategy:
|
||
- Hard cap prompt body at 200 KB per output (configurable)
|
||
- If over cap: (1) include diff; (2) include header + last 200 lines; (3) link to file path
|
||
|
||
#### AST/Diagram Work:
|
||
- Cache ASTs in `.git/ai-rules-cache/ast/` keyed by `<rel_path>:<blob_sha>`
|
||
- Rate-limit diagram updates to once per file per commit (guard duplicate runs)
|
||
|
||
#### 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
|
||
|
||
#### Performance Telemetry (optional)
|
||
- Write `.git/ai-rules-debug/perf.json` with per-output timings:
|
||
`{ resolve_ms, prompt_ms, model_ms, sanitize_ms, apply_ms, bytes_in, bytes_out }`
|
||
- Summarize totals at end of run for quick regressions spotting.
|
||
|
||
## Testing Strategy
|
||
|
||
## Goals
|
||
- Prove determinism (same inputs → same patch).
|
||
- Prove guardrails (append-only, marker-bounded, path/size limits).
|
||
- Prove promotion math (votes, quorum, human gates).
|
||
- Keep runs fast and hermetic (temp repo, mock clock, seeded RNG).
|
||
|
||
## 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
|
||
|
||
### Golden & Snapshot Tests:
|
||
- **Prompt Envelope Golden**: compare against `tests/gold/envelopes/<case>.txt`
|
||
- **Diff Output Golden**: compare unified diffs in `tests/gold/diffs/<case>.diff`
|
||
- **Summary Snapshot**: write `{stage}.discussion.sum.md` and compare against `tests/snapshots/<case>/<stage>.discussion.sum.md` (markers only)
|
||
|
||
### Property-Based Tests:
|
||
- Using `hypothesis` to fuzz discussion comments; invariants:
|
||
- last non-empty line drives the vote
|
||
- regex `vote_line_regex` never matches malformed lines
|
||
- marker-bounded writer never edits outside markers
|
||
|
||
### Mutation Tests (optional):
|
||
- Run `mutmut` on `automation/workflow.py` vote math and ensure tests fail when logic is mutated.
|
||
|
||
### 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/
|
||
│ │ └─ data/
|
||
│ │ ├─ bigfile.md # >1MB to trigger chunking
|
||
│ │ ├─ bad.diff # malformed diff for sanitizer tests
|
||
│ │ ├─ secrets.txt # simulated secrets for scanner tests
|
||
│ │ └─ envelopes/ # golden prompt envelopes
|
||
│ ├─ gold/
|
||
│ │ ├─ envelopes/
|
||
│ │ └─ diffs/
|
||
│ └─ test_cases/
|
||
│ ├─ test_feature_promotion.sh
|
||
│ ├─ test_design_generation.sh
|
||
│ ├─ test_bug_creation.sh
|
||
│ ├─ test_append_only_guard.sh
|
||
│ ├─ test_summary_snapshot.sh
|
||
│ ├─ test_secret_scanner_block.sh
|
||
│ ├─ test_ci_cache_only_mode.sh
|
||
│ ├─ test_moderator_nudge.sh
|
||
│ └─ test_rule_precedence.sh
|
||
├─ bin/
|
||
│ └─ claude # Fake deterministic model
|
||
├─ snapshots/
|
||
│ └─ FR_test_case/
|
||
│ ├─ feature.discussion.sum.md
|
||
│ └─ design.discussion.sum.md
|
||
└─ README.md
|
||
```
|
||
|
||
### Hermetic Test Utilities
|
||
- Mock clock: set SOURCE_DATE_EPOCH to freeze {date} expansions.
|
||
- Temp repo: each test case creates a fresh TMP_REPO with isolated .git.
|
||
- Seeded RNG: set AI_RULES_SEED for deterministic model variants.
|
||
- Filesystem isolation: tests write only under TMPDIR and .git/ai-rules-*.
|
||
|
||
### Fake Model Implementation
|
||
Purpose: Deterministic testing without external API dependencies
|
||
|
||
Implementation (tests/bin/claude):
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# Fake Claude CLI for testing
|
||
# Reads prompt envelope from stdin, outputs a unified diff or injected error.
|
||
# Controls:
|
||
# AI_FAKE_ERR=diff|apply|malformed (force error modes)
|
||
# AI_FAKE_SEED=<int> (deterministic variant)
|
||
# AI_FAKE_MODE=discussion|design (which template to emit)
|
||
|
||
set -euo pipefail
|
||
prompt="$(cat)"
|
||
|
||
if [[ "${AI_FAKE_ERR:-}" == "malformed" ]]; then
|
||
echo "this is not a diff"
|
||
exit 0
|
||
fi
|
||
|
||
target_file=$(echo "$prompt" | awk '/^SOURCE_FILE:/ {print $2}')
|
||
if echo "$prompt" | grep -q "RULE: .*feature_discussion/self_append"; then
|
||
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
|
||
EOF
|
||
elif echo "$prompt" | grep -q "RULE: .*discussion_summary_writer"; then
|
||
cat << 'EOF'
|
||
<<<AI_DIFF_START>>>
|
||
diff --git a/Docs/features/FR_test/discussions/feature.discussion.sum.md b/Docs/features/FR_test/discussions/feature.discussion.sum.md
|
||
index 1111111..2222222 100644
|
||
--- a/Docs/features/FR_test/discussions/feature.discussion.sum.md
|
||
+++ b/Docs/features/FR_test/discussions/feature.discussion.sum.md
|
||
@@ -5,3 +5,4 @@
|
||
<!-- SUMMARY:VOTES START -->
|
||
## Votes (latest per participant)
|
||
READY: 1 • CHANGES: 0 • REJECT: 0
|
||
- Rob
|
||
<!-- SUMMARY:VOTES END -->
|
||
<<<AI_DIFF_END>>>
|
||
EOF
|
||
else
|
||
# Default patch for other file types
|
||
echo "<<<AI_DIFF_START>>>"
|
||
echo "diff --git a/README.md b/README.md"
|
||
echo "index 0000000..0000001 100644"
|
||
echo "--- a/README.md"
|
||
echo "+++ b/README.md"
|
||
echo "@@ -0,0 +1,1 @@"
|
||
echo "+Generated by fake model"
|
||
echo "<<<AI_DIFF_END>>>"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
|
||
- Append-Only Guard: attempt to edit earlier lines in discussion → reject
|
||
- Summary Snapshot: only markers mutate; outside text preserved
|
||
- Secret Scanner: staged secret blocks commit with exit 11
|
||
- CI Cache-only: with AI_RULES_CI=1 and cache miss → exit 20
|
||
- Moderator Nudge: comment ≤10 lines, ends with `VOTE: CHANGES`
|
||
- Rule Precedence: local overrides feature, feature overrides global
|
||
|
||
#### Test Execution
|
||
```bash
|
||
# Run full test suite
|
||
cd tests/integration
|
||
./run.sh
|
||
|
||
# Run specific test case
|
||
./test_cases/test_feature_promotion.sh
|
||
```
|
||
|
||
Makefile (optional)
|
||
```make
|
||
.PHONY: test unit integ lint
|
||
test: unit integ
|
||
unit:
|
||
- pytest -q tests/unit
|
||
integ:
|
||
- cd tests/integration && ./run.sh
|
||
lint:
|
||
- ruff check automation src || true
|
||
```
|
||
|
||
### 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
|
||
- **CI Mode (`AI_RULES_CI=1`)**:
|
||
- Default to `--dry-run` and **cache-only** model lookups.
|
||
- On cache miss, print the missing `PROMPT_SHA256`, skip invocation, and exit 20.
|
||
- Use to keep CI fast and reproducible.
|
||
|
||
#### Coverage Targets:
|
||
- ≥90% line coverage on `automation/workflow.py` vote/quorum logic
|
||
- ≥80% branch coverage on rule resolution and guards
|
||
|
||
#### Success Criteria:
|
||
- All golden prompts/diffs stable across runs (no drift)
|
||
- Guardrail tests fail if append-only/marker or path checks are removed
|
||
|
||
## 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/{name}.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}_{name}.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}.discussion.sum.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.discussion.sum.md
|
||
├─ design.discussion.md
|
||
├─ design.discussion.sum.md
|
||
├─ implementation.discussion.md
|
||
├─ implementation.discussion.sum.md
|
||
├─ testing.discussion.md
|
||
├─ testing.discussion.sum.md
|
||
├─ review.discussion.md
|
||
└─ review.discussion.sum.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}.sum.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}.sum.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.discussion.sum.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.discussion.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Same summary policy as feature.sum.md; also add link to ../design/design.md.
|
||
impl_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/implementation.discussion.sum.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.discussion.sum.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.discussion.sum.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}.sum.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:
|
||
- setup_project.py (Initialize Cascading Development repo)
|
||
- 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
|
||
|
||
## Initial Setup & Bootstrapping
|
||
To streamline project onboarding and ensure every repository begins with a structured, traceable starting point, this system includes a one-time setup script that initializes the folder structure and guides the maintainer through creating the first feature request using the interactive dialog.
|
||
|
||
### Steps Performed:
|
||
- Create the canonical folder structure under Docs/features/FR_<date>_initial-feature-request/, including the request.md template.
|
||
- Run the interactive dialog utility to guide the user (or team) through describing the project’s intent, motivation, and constraints in natural language.
|
||
- Initialize Git hooks, orchestration scripts, and default configuration files.
|
||
- Automatically generate the first Feature Request document from that conversation.
|
||
|
||
Example Implementation
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
setup_project.py — Initialize AI–Human Collaboration repo
|
||
"""
|
||
import os, subprocess, datetime
|
||
|
||
def run_ramble():
|
||
"""Launch Ramble dialog to collect initial feature request"""
|
||
subprocess.run(["python3", "ramble.py", "--prompt", "Describe your initial feature request"])
|
||
|
||
def main():
|
||
today = datetime.date.today().isoformat()
|
||
feature_dir = f"Docs/features/FR_{today}_initial-feature-request"
|
||
os.makedirs(f"{feature_dir}/discussions", exist_ok=True)
|
||
print(f"Creating {feature_dir}/ ...")
|
||
|
||
# Generate initial request file from template
|
||
request_md = os.path.join(feature_dir, "request.md")
|
||
if not os.path.exists(request_md):
|
||
with open(request_md, "w") as f:
|
||
f.write("# Feature Request: Initial Project Setup\n\n"
|
||
"**Intent:** Describe project goals and first milestone.\n"
|
||
"**Motivation / Problem:** Why this system is needed.\n"
|
||
"**Constraints / Non-Goals:** ...\n"
|
||
"**Open Questions:** ...\n")
|
||
|
||
# Run Ramble dialog to fill in details interactively
|
||
print("Launching Ramble interactive prompt...")
|
||
run_ramble()
|
||
print("Setup complete — initial feature request created.")
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
### Rationale
|
||
This setup process ensures that every repository starts with a consistent structure and a human-authored origin document, created in a conversational way. It also guarantees that the automation and templates are initialized before any feature work begins.
|
||
|
||
### 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: all
|
||
|
||
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}, {name}, {ext}, {date}, {rel}, {dir}, {feature_id}, {stage}) 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: all }
|
||
design: { ready: all, reject: all }
|
||
implementation: { ready: 1_human, reject: all }
|
||
testing: { ready: all, reject: all }
|
||
review: { ready: 1_human, reject: all }
|
||
eligibility:
|
||
agents_allowed: true
|
||
require_human_for: [implementation, review]
|
||
etiquette:
|
||
name_prefix_agents: "AI_"
|
||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\s*$"
|
||
response_timeout_hours: 24
|
||
timeouts:
|
||
discussion_stale_days: 3
|
||
nudge_interval_hours: 24
|
||
promotion_timeout_days: 14
|
||
moderation:
|
||
max_lines: 10
|
||
max_line_length: 120
|
||
security:
|
||
scanners:
|
||
enabled: true
|
||
tool: gitleaks # or git-secrets, trufflehog
|
||
allowlist_file: process/secrets.allowlist
|
||
redaction:
|
||
apply_to:
|
||
- logs
|
||
- prompts
|
||
- patches
|
||
denylist_keys:
|
||
- API_KEY
|
||
- ACCESS_TOKEN
|
||
- SECRET
|
||
- PASSWORD
|
||
- PRIVATE_KEY
|
||
guards:
|
||
block_paths:
|
||
- secrets/
|
||
max_patch_kb: 200
|
||
forbid_binary_edits: true
|
||
performance:
|
||
max_jobs: 4
|
||
prompt_kb_cap: 200
|
||
discussion_timeline_limit: 15
|
||
cache:
|
||
enabled: true
|
||
dir: .git/ai-rules-cache
|
||
batching:
|
||
enabled: true
|
||
max_batch: 4
|
||
ast_cache:
|
||
enabled: true
|
||
dir: .git/ai-rules-cache/ast
|
||
```
|
||
|
||
### 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
|