From 1141725d146fa16df4b47a9df94581b3aa2a7e0c Mon Sep 17 00:00:00 2001 From: rob Date: Fri, 24 Oct 2025 13:58:59 -0300 Subject: [PATCH] 1st commit --- Docs/DESIGN.md | 719 ++++++++++++++++++++----------------------------- 1 file changed, 286 insertions(+), 433 deletions(-) diff --git a/Docs/DESIGN.md b/Docs/DESIGN.md index 1c2728f..3b7920d 100644 --- a/Docs/DESIGN.md +++ b/Docs/DESIGN.md @@ -68,27 +68,32 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co │ └─ implementation_plan.md ├─ Docs/ │ ├─ features/ -│ │ ├─ .ai-rules.yml # Folder-scoped rules for all features -│ │ ├─ FR_YYYY-MM-DD_/ # Individual feature folders -│ │ │ ├─ request.md # Original feature request -│ │ │ ├─ discussions/ # Stage-specific conversations -│ │ │ │ ├─ feature.discussion.md # Discuss the request -│ │ │ │ ├─ design.discussion.md # Discuss the design -│ │ │ │ ├─ implementation.discussion.md # Track implementation -│ │ │ │ ├─ testing.discussion.md # Plan/track testing -│ │ │ │ └─ review.discussion.md # Final review -│ │ │ ├─ design/ # Design artifacts -│ │ │ │ ├─ design.md # Evolving design document -│ │ │ │ └─ diagrams/ # Architecture diagrams -│ │ │ ├─ implementation/ # Implementation artifacts -│ │ │ │ ├─ plan.md # Implementation plan -│ │ │ │ └─ tasks.md # Task checklist -│ │ │ ├─ testing/ # Testing artifacts -│ │ │ │ ├─ testplan.md # Test strategy -│ │ │ │ └─ checklist.md # Test checklist -│ │ │ ├─ review/ # Review artifacts -│ │ │ │ └─ findings.md # Review findings -│ │ │ └─ bugs/ # Auto-generated bug reports +│ │ ├─ .ai-rules.yml # Folder-scoped rules for all features +│ │ ├─ FR_YYYY-MM-DD_/ # 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 # Review findings +│ │ │ └─ bugs/ # Auto-generated bug reports │ │ │ └─ BUG_YYYYMMDD_/ │ │ │ ├─ report.md │ │ │ ├─ discussion.md @@ -106,11 +111,12 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co └─ bin/ ``` -Note: Each stage discussion has a companion summary maintained automatically next to it (e.g., feature.summary.md, design.summary.md, implementation.summary.md, testing.summary.md, review.summary.md) to provide a live, scannable state of the thread. +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_/ - Discussion Files: {stage}.discussion.md in discussions/ subfolder +- Discussion summary: {stage}.discussion.sum.md in discussions/ subfolder - Bug Reports: bugs/BUG_YYYYMMDD_/ with standardized contents - Source Files: Maintain existing patterns in src/ @@ -161,7 +167,7 @@ created: YYYY-MM-DD promotion_rule: allow_agent_votes: true ready_min_eligible_votes: all - reject_min_eligible_votes: 1 + reject_min_eligible_votes: all participation: instructions: | @@ -179,10 +185,16 @@ voting: - AI_Moderator tracks unanswered questions and missing votes - When READY threshold met: status → READY_FOR_DESIGN +#### 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 + #### Promotion Actions - Creates discussions/design.discussion.md (OPEN) - Creates design/design.md seeded from request + feature discussion -- Creates design/diagrams/ folder ### Stage 3: Design Discussion - File: discussions/design.discussion.md @@ -204,6 +216,15 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO - Participants vote on design completeness - When READY threshold met: status → READY_FOR_IMPLEMENTATION +#### 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 @@ -216,7 +237,7 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO #### Promotion Actions - Creates discussions/implementation.discussion.md (OPEN) - Creates implementation/plan.md and implementation/tasks.md -- Tasks are checkboxes aligned to acceptance criteria +- Creates implementation/tasks.md - Tasks are checkboxes aligned to acceptance criteria ### Stage 4: Implementation Discussion - File: discussions/implementation.discussion.md @@ -231,7 +252,7 @@ status: OPEN # OPEN | READY_FOR_TESTING promotion_rule: allow_agent_votes: true ready_min_eligible_votes: 1_human # HUMAN GATE - reject_min_eligible_votes: 1 + reject_min_eligible_votes: all # ... --- ``` @@ -242,6 +263,14 @@ promotion_rule: - Link commits/PRs to tasks when mentioned ([#123], commit shas) - When all required tasks complete: status → READY_FOR_TESTING +#### 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 @@ -265,7 +294,7 @@ status: OPEN # OPEN | READY_FOR_REVIEW promotion_rule: allow_agent_votes: true ready_min_eligible_votes: all - reject_min_eligible_votes: 1 + reject_min_eligible_votes: all # ... --- ``` @@ -276,6 +305,15 @@ promotion_rule: - Mark corresponding checklist items pass/fail - On test failure: auto-create bug report with full sub-cycle +#### 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 @@ -309,7 +347,7 @@ status: OPEN # OPEN | READY_FOR_RELEASE | CHANGES_REQUESTED promotion_rule: allow_agent_votes: true ready_min_eligible_votes: 1_human # HUMAN GATE - reject_min_eligible_votes: 1 + reject_min_eligible_votes: all # ... --- ``` @@ -375,9 +413,9 @@ voting: values: [READY, CHANGES, REJECT] allow_agent_votes: true quorum: - discussion: { ready: all, reject: 1 } - implementation: { ready: 1_human, reject: 1 } - release: { ready: 1_human, reject: 1 } + 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] @@ -389,23 +427,16 @@ timeouts: 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 +- Implementation promotion: ≥1 human READY required +- Release promotion: ≥1 human READY required +- Agent votes count toward discussion but cannot satisfy human requirements ### Participation Etiquette -Conciseness: Keep comments action-oriented and focused - -References: Link to files/sections when possible (design.md#architecture) - -Naming: Agents must prefix with AI_ (e.g., AI_Architect) - -Ownership: Suggest explicit owners for next steps (@AI_Architect: please draft...) - -Timeliness: Respond to direct questions within 24 hours +- Conciseness: Keep comments action-oriented and focused +- References: Link to files/sections when possible (design.md#architecture) +- Naming: Agents must prefix with AI_ (e.g., AI_Architect) +- Ownership: Suggest explicit owners for next steps (@AI_Architect: please draft...) +- Timeliness: Respond to direct questions within 24 hours ## Cascading Rules System ### Global Rules (Root .ai-rules.yml) @@ -616,27 +647,19 @@ rules: Seed discussion and fix plan. ``` 5.3 Rule Resolution Precedence -Nearest Directory: Check source file directory and parents upward - -Feature Scope: Docs/features/.ai-rules.yml for feature artifacts - -Global Fallback: Root .ai-rules.yml for code files - -Conflict Resolution: Nearest rule wins, with logging of override decisions +- Nearest Directory: Check source file directory and parents upward +- Feature Scope: Docs/features/.ai-rules.yml for feature artifacts +- Global Fallback: Root .ai-rules.yml for code files +- Conflict Resolution: Nearest rule wins, with logging of override decisions ## Orchestration Architecture ### Bash Pre-commit Hook (Current Implementation) Core Responsibilities: - -Collect staged files (Added/Modified only) - -Resolve rules via cascading lookup - -Build context prompts from staged content - -Call AI model via CLI for patch generation - -Apply patches with robust error handling +- Collect staged files (Added/Modified only) +- Resolve rules via cascading lookup +- Build context prompts from staged content +- Call AI model via CLI for patch generation +- Apply patches with robust error handling Enhanced Template Support: @@ -648,22 +671,15 @@ dirpath=$(dirname "$rel_path") -e "s|{dir}|$dirpath|g" ``` Patch Application Strategy: - -Preserve Index Lines: Enable 3-way merge capability - -Try 3-way First: git apply --index --3way --recount --whitespace=nowarn - -Fallback to Strict: git apply --index if 3-way fails - -Debug Artifacts: Save raw/clean/sanitized/final patches to .git/ai-rules-debug/ +- Preserve Index Lines: Enable 3-way merge capability +- Try 3-way First: git apply --index --3way --recount --whitespace=nowarn +- Fallback to Strict: git apply --index if 3-way fails +- Debug Artifacts: Save raw/clean/sanitized/final patches to .git/ai-rules-debug/ Discussion File Optimization: - -Prefer append-only edits with optional header flips - -For large files: generate full new content and compute diff locally - -Minimize hunk drift through careful patch construction +- Prefer append-only edits with optional header flips +- For large files: generate full new content and compute diff locally +- Minimize hunk drift through careful patch construction ### Python Orchestrator (automation/workflow.py) Phase 1 (Non-blocking Status): @@ -682,71 +698,46 @@ def main(): 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 +- Vote Parsing: Parse discussion files, track latest votes per participant +- Threshold Evaluation: Compute eligibility and quorum status +- Status Reporting: JSON output of current discussion state +- Decision Hints: Suggest promotion based on policy rules Future Enhancements: - -Policy enforcement based on process/policies.yml - -Gitea API integration for issue/PR management - -Advanced agent coordination and task routing +- Policy enforcement based on process/policies.yml +- Gitea API integration for issue/PR management +- Advanced agent coordination and task routing ### Gitea Integration (Future) Label System: - -stage/*: stage/discussion, stage/design, stage/implementation, etc. - -blocked/*: blocked/needs-votes, blocked/needs-human - -needs/*: needs/design, needs/review, needs/tests +- 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 +- Open/label PRs for implementation transitions +- Post status summaries to PR threads +- Create tracking issues for feature implementation +- Report status checks to PRs ## Moderator Protocol ### AI_Moderator Responsibilities Conversation Tracking: - -Monitor unanswered questions (>24 hours) - -Track missing votes from active participants - -Identify stale threads needing attention - -Flag direct mentions that need responses +- Monitor unanswered questions (>24 hours) +- Track missing votes from active participants +- Identify stale threads needing attention +- Flag direct mentions that need responses Progress Reporting: - -Compute current vote tallies and thresholds - -List participants who haven't voted recently - -Summarize promotion status and remaining requirements - -Highlight blocking issues or concerns +- Compute current vote tallies and thresholds +- List participants who haven't voted recently +- Summarize promotion status and remaining requirements +- Highlight blocking issues or concerns Task Allocation: - -Suggest explicit owners for pending tasks - -Example: "AI_Architect: please draft the acceptance criteria section" - -Example: "Rob: could you clarify the deployment timeline?" +- Suggest explicit owners for pending tasks +- Example: "AI_Architect: please draft the acceptance criteria section" +- Example: "Rob: could you clarify the deployment timeline?" ### Moderator Implementation Rule Definition (in Docs/features/.ai-rules.yml): @@ -781,36 +772,24 @@ Nudge Frequency: Controlled by nudge_interval_hours in policies ## Error Handling & Resilience ### Common Failure Modes Patch Application Issues: - -Symptom: Hunk drift on large files, merge conflicts - -Mitigation: 3-way apply with index preservation, append-only strategies - -Fallback: Local diff computation from full new content +- Symptom: Hunk drift on large files, merge conflicts +- Mitigation: 3-way apply with index preservation, append-only strategies +- Fallback: Local diff computation from full new content Model Output Problems: - -Symptom: Malformed diff, missing markers, invalid patch format - -Mitigation: Extract between markers, validate with git apply --check - -Fallback: Clear diagnostics with patch validation output +- Symptom: Malformed diff, missing markers, invalid patch format +- Mitigation: Extract between markers, validate with git apply --check +- Fallback: Clear diagnostics with patch validation output Tooling Dependencies: - -Symptom: Missing yq, claude, or other required tools - -Mitigation: Pre-flight checks with clear error messages - -Fallback: Graceful degradation with feature-specific disabling +- Symptom: Missing yq, claude, or other required tools +- Mitigation: Pre-flight checks with clear error messages +- Fallback: Graceful degradation with feature-specific disabling Rule Conflicts: - -Symptom: Multiple rules matching same file with conflicting instructions - -Mitigation: Nearest-directory precedence with conflict logging - -Fallback: Global rule application with warning +- Symptom: Multiple rules matching same file with conflicting instructions +- Mitigation: Nearest-directory precedence with conflict logging +- Fallback: Global rule application with warning ### Recovery Procedures Manual Override: @@ -823,29 +802,20 @@ git commit --no-verify -m "Emergency fix: manually overriding discussion status" # 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 +- All patch variants saved to .git/ai-rules-debug/ +- Timestamped files: raw, clean, sanitized, final patches +- Commit-specific directories for correlation Rollback Strategy: - -All generated artifacts are staged separately - -Easy partial staging: git reset HEAD for specific artifacts - -Full reset: git reset HEAD~1 to undo entire commit with generations +- All generated artifacts are staged separately +- Easy partial staging: git reset HEAD for specific artifacts +- Full reset: git reset HEAD~1 to undo entire commit with generations ### Audit Trail Execution Logging: - -All rule invocations logged with source→output mapping - -Patch application attempts and outcomes recorded - -Vote calculations and promotion decisions documented +- All rule invocations logged with source→output mapping +- Patch application attempts and outcomes recorded +- Vote calculations and promotion decisions documented Debug Bundle: @@ -861,14 +831,10 @@ Debug Bundle: ## Security & Secrets Management ### Secret Protection Never Commit: - -API keys, authentication tokens - -Personal identifying information - -Internal system credentials - -Private configuration data +- API keys, authentication tokens +- Personal identifying information +- Internal system credentials +- Private configuration data Environment Variables: @@ -879,112 +845,72 @@ export CLAUDE_API_KEY="your_key" # .env file loaded via python-dotenv in Python components ``` Configuration Management: - -Keep sensitive endpoints in automation/config.yml - -Use environment variable substitution in configuration - -Validate no secrets in discussions, rules, or generated artifacts +- Keep sensitive endpoints in automation/config.yml +- Use environment variable substitution in configuration +- Validate no secrets in discussions, rules, or generated artifacts ### Access Control Repository Security: - -Assume all repository contents are potentially exposed - -No sensitive business logic in prompt instructions - -Regular security reviews of rule definitions +- Assume all repository contents are potentially exposed +- No sensitive business logic in prompt instructions +- Regular security reviews of rule definitions Agent Permissions: - -Limit file system access to repository scope - -Validate output paths stay within repository - -Sanitize all file operations for path traversal +- Limit file system access to repository scope +- Validate output paths stay within repository +- Sanitize all file operations for path traversal ## Performance & Scale Considerations ### Optimization Strategies Prompt Efficiency: - -Pass staged diffs instead of full file contents when possible - -Use concise, structured instructions with clear formatting - -Limit context to relevant sections for large files +- Pass staged diffs instead of full file contents when possible +- Use concise, structured instructions with clear formatting +- Limit context to relevant sections for large files Discussion Management: - -Append-only edits with periodic summarization - -Compact status reporting in moderator comments - -Archive completed discussions if they become too large +- Append-only edits with periodic summarization +- Compact status reporting in moderator comments +- Archive completed discussions if they become too large Batch Operations: - -Process multiple related files in single model calls when beneficial - -Cache rule resolutions for multiple files in same directory - -Parallelize independent output generations +- Process multiple related files in single model calls when beneficial +- Cache rule resolutions for multiple files in same directory +- Parallelize independent output generations ### Scaling Limits File Size Considerations: - -Small (<100KB): Full content in prompts - -Medium (100KB-1MB): Diff-only with strategic context - -Large (>1MB): Chunked processing or summary-only approaches +- Small (<100KB): Full content in prompts +- Medium (100KB-1MB): Diff-only with strategic context +- Large (>1MB): Chunked processing or summary-only approaches Repository Size: - -Current approach suitable for medium-sized repositories - -For very large codebases: scope rules to specific directories - -Consider rule disabling for generated/binary assets +- 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 +- Model API calls: implement throttling and retry logic +- Gitea API: respect rate limits with exponential backoff +- File operations: batch where possible to reduce I/O ## Testing Strategy ### Testing Tiers Unit Tests (Python): - -Vote parsing and eligibility calculation - -Policy evaluation and quorum determination - -Rules resolution and conflict handling - -Template variable substitution - -Integration Tests (Bash + Python): - -End-to-end rule → prompt → patch → apply cycle - -Discussion status transitions and promotion logic - -Error handling and recovery procedures - -Multi-file rule processing +- 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 +- PlantUML syntax checking: plantuml -checkonly +- Markdown structure validation +- Template completeness checks +- YAML syntax validation ### Test Architecture ```text @@ -1063,22 +989,15 @@ cd tests/integration ``` ### Continuous Validation Pre-commit Checks: - -PlantUML syntax validation for generated diagrams - -Markdown link validation - -YAML syntax checking for rule files - -Template variable validation +- 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 +- Rule resolution time for typical commit +- Patch generation and application duration +- Memory usage during large file processing ## Source Intelligence Automation (Auto-Review + Auto-Diagram) @@ -1226,22 +1145,22 @@ Future versions can post summaries to the feature’s implementation discussion ## Discussion Summaries (Companion Artifacts per Stage) ### What it is -For every {stage}.discussion.md, maintain a sibling {stage}.summary.md. It is append-minimal with bounded section rewrites only (between stable markers). Contents: decisions, vote tallies, open questions, awaiting replies, action items, compact timeline. +For every {stage}.discussion.md, maintain a sibling {stage}.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.summary.md + ├─ feature.sum.md ├─ design.discussion.md - ├─ design.summary.md + ├─ design.sum.md ├─ implementation.discussion.md - ├─ implementation.summary.md + ├─ implementation.sum.md ├─ testing.discussion.md - ├─ testing.summary.md + ├─ testing.sum.md ├─ review.discussion.md - └─ review.summary.md + └─ review.sum.md ``` ### Header (machine-readable) @@ -1303,7 +1222,7 @@ READY: 0 • CHANGES: 0 • REJECT: 0 ``` ### How it updates -Trigger: whenever {stage}.discussion.md is staged, the hook also updates/creates {stage}.summary.md. +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) @@ -1314,7 +1233,7 @@ Deterministic logic: - 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/.md (status: SNAPSHOT) and keep {stage}.summary.md trimmed while retaining Decisions/Open Q/Actions/Votes. +Rotation / snapshots (optional): when discussion grows large or on schedule, write discussions/summaries/.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 @@ -1329,7 +1248,7 @@ rules: feature_discussion: outputs: summary_companion: - path: "{dir}/discussions/feature.summary.md" + path: "{dir}/discussions/feature.sum.md" output_type: "discussion_summary_writer" instruction: | Create or update the summary file. Replace ONLY content between @@ -1339,28 +1258,28 @@ rules: design_discussion: outputs: summary_companion: - path: "{dir}/discussions/design.summary.md" + path: "{dir}/discussions/design.sum.md" output_type: "discussion_summary_writer" instruction: | - Same summary policy as feature.summary.md; also add link to ../design/design.md. + Same summary policy as feature.sum.md; also add link to ../design/design.md. impl_discussion: outputs: summary_companion: - path: "{dir}/discussions/implementation.summary.md" + path: "{dir}/discussions/implementation.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.summary.md" + path: "{dir}/discussions/testing.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.summary.md" + path: "{dir}/discussions/review.sum.md" output_type: "discussion_summary_writer" instruction: | Same summary policy; Decisions should note READY_FOR_RELEASE with date and follow-ups. @@ -1375,208 +1294,141 @@ Provide workflow.py --summarize to output regenerated sections - Failure: malformed discussion / huge file → generator still writes sections; timeline truncates; no crash ### Why this helps -Newcomers can open {stage}.summary.md and immediately see the state. Humans keep talking in the discussion; the system curates the signal in the summary. Promotions are transparent via Decisions. Open loops are visible and assigned. +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: - -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/*) +- 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 +- 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) +- 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 +- 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 +- 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 +- 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 +- 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 +- 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 +- 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 +- 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: +- 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 +- 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 +- 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 +- 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 +- 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 +- 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 +- 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 +- 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 -Risk: System creates too much ceremony for small changes - -Mitigation: Configurable rule enabling/disabling - -Flexibility: Bypass options for trivial changes - -14 Template Evolution -14.1 Versioning Strategy +### 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 +- 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 -Document template changes in release notes - -Provide automated migration scripts for simple changes - -Flag features using deprecated templates - -14.2 Core Templates +#### 14.2 Core Templates Feature Request Template (process/templates/feature_request.md): -markdown +```markdown # Feature Request: **Feature ID**: <FR_YYYY-MM-DD_slug> @@ -1587,8 +1439,9 @@ markdown **Open Questions**: <bulleted list of uncertainties> **Meta**: Created: <date> • Author: <name> Discussion Template (process/templates/discussion.md): +``` -markdown +```markdown --- type: discussion stage: <feature|design|implementation|testing|review> @@ -1599,7 +1452,7 @@ created: <YYYY-MM-DD> promotion_rule: allow_agent_votes: true ready_min_eligible_votes: all - reject_min_eligible_votes: 1 + reject_min_eligible_votes: all participation: instructions: | @@ -1610,13 +1463,13 @@ participation: 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> @@ -1782,17 +1635,17 @@ voting: values: [READY, CHANGES, REJECT] allow_agent_votes: true quorum: - discussion: { ready: all, reject: 1 } - design: { ready: all, reject: 1 } - implementation: { ready: 1_human, reject: 1 } - testing: { ready: all, reject: 1 } - review: { ready: 1_human, reject: 1 } + 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)\b" + vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\b" response_timeout_hours: 24 timeouts: discussion_stale_days: 3