From 18d84c2b157cecdee85a8cee7f073c05a553c649 Mon Sep 17 00:00:00 2001 From: rob Date: Fri, 24 Oct 2025 20:55:11 -0300 Subject: [PATCH] 1st commit --- Docs/DESIGN.md | 314 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 260 insertions(+), 54 deletions(-) diff --git a/Docs/DESIGN.md b/Docs/DESIGN.md index 3b7920d..fb35663 100644 --- a/Docs/DESIGN.md +++ b/Docs/DESIGN.md @@ -27,7 +27,12 @@ ## 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. +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 @@ -36,16 +41,25 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co - Deterministic & Reversible: All automated actions are diffed, logged, and easily revertible - Composable Rules: Nearest-folder precedence via cascading .ai-rules.yml configurations -### Key Innovations +### 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 (Option A: Per-Feature Folders) +### Canonical Structure (Per-Feature Folders) ```text / (repository root) ├─ .ai-rules.yml # Global defaults + file associations @@ -80,7 +94,7 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co │ │ │ │ ├─ 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.md # Final review │ │ │ │ └─ review.discussion.sum.md # Summary of the review discussion │ │ │ ├─ design/ # Design artifacts │ │ │ │ ├─ design.md # Evolving design document @@ -92,7 +106,7 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co │ │ │ │ ├─ testplan.md # Test strategy │ │ │ │ └─ checklist.md # Test checklist │ │ │ ├─ review/ # Review artifacts -│ │ │ │ └─ findings.md # Review findings +│ │ │ │ └─ findings.md # Feature-specific review findings │ │ │ └─ bugs/ # Auto-generated bug reports │ │ │ └─ BUG_YYYYMMDD_/ │ │ │ ├─ report.md @@ -122,11 +136,14 @@ Note: Each stage discussion has a companion summary maintained automatically nex ### Template Variables Supported in path resolution: - -- {basename}: Filename without extension -- {date}: Current date in YYYY-MM-DD format -- {rel}: Repository-relative path to source file -- {dir}: Directory containing the source file (NEW) +- {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 (.discussion.md), e.g., feature|design|implementation|testing|review ## Stage Model & Operational Procedure @@ -134,6 +151,18 @@ Supported in path resolution: ```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 @@ -162,6 +191,7 @@ type: discussion stage: feature status: OPEN # OPEN | READY_FOR_DESIGN | REJECTED feature_id: FR_YYYY-MM-DD_ +stage_id: FR_YYYY-MM-DD__feature created: YYYY-MM-DD promotion_rule: @@ -185,12 +215,15 @@ voting: - 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) @@ -206,6 +239,8 @@ voting: type: discussion stage: design status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO +feature_id: FR_YYYY-MM-DD_ +stage_id: FR_YYYY-MM-DD__design # ... same promotion_rule, participation, voting as feature --- ``` @@ -216,6 +251,8 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO - 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 @@ -249,6 +286,8 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO type: discussion stage: implementation status: OPEN # OPEN | READY_FOR_TESTING +feature_id: FR_YYYY-MM-DD_ +stage_id: FR_YYYY-MM-DD__implementation promotion_rule: allow_agent_votes: true ready_min_eligible_votes: 1_human # HUMAN GATE @@ -263,6 +302,8 @@ promotion_rule: - 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 @@ -287,17 +328,18 @@ promotion_rule: #### Header ```yaml ---- type: discussion stage: testing status: OPEN # OPEN | READY_FOR_REVIEW +feature_id: FR_YYYY-MM-DD_ +stage_id: FR_YYYY-MM-DD__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 @@ -305,6 +347,8 @@ promotion_rule: - 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 @@ -320,9 +364,11 @@ promotion_rule: bugs/BUG_YYYYMMDD_/ ├─ 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 @@ -330,9 +376,19 @@ bugs/BUG_YYYYMMDD_/ - 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 discussions/review.discussion.md (OPEN) -- Creates review/findings.md with verification summary +- Creates or report to discussions/review.discussion.md (OPEN) +- Creates review/findings_BUG_YYYYMMDD_.md with verification summary ### Stage 6: Review Discussion - File: discussions/review.discussion.md @@ -344,6 +400,8 @@ bugs/BUG_YYYYMMDD_/ type: discussion stage: review status: OPEN # OPEN | READY_FOR_RELEASE | CHANGES_REQUESTED +feature_id: FR_YYYY-MM-DD_ +stage_id: FR_YYYY-MM-DD__review promotion_rule: allow_agent_votes: true ready_min_eligible_votes: 1_human # HUMAN GATE @@ -358,6 +416,8 @@ promotion_rule: - 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 @@ -379,17 +439,18 @@ promotion_rule: - 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 +- 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: @@ -404,6 +465,11 @@ 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): @@ -421,7 +487,7 @@ eligibility: require_human_for: [implementation, release] etiquette: name_prefix_agents: "AI_" - vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\b" + vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\s*$" timeouts: discussion_stale_days: 3 nudge_interval_hours: 24 @@ -431,14 +497,49 @@ Human Safety Gates: - 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** | `/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 @@ -491,17 +592,36 @@ settings: 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" - "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" + "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: @@ -510,22 +630,42 @@ rules: path: "{dir}/discussions/feature.discussion.md" output_type: "feature_discussion_writer" instruction: | - If discussion file missing: create with standard header (stage: feature, status: OPEN), + 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 operation. + 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 single vote line. + 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 - - Clearly state promotion decision in comment - Append-only with minimal diff. + - 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" @@ -538,9 +678,17 @@ rules: output_type: "design_doc_writer" instruction: | Create ONLY if feature discussion status is READY_FOR_DESIGN. - Seed design document from request content and feature discussion. + 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: @@ -551,6 +699,13 @@ rules: 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" @@ -571,6 +726,13 @@ rules: 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: @@ -581,6 +743,13 @@ rules: 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" @@ -592,7 +761,7 @@ rules: output_type: "testplan_writer" instruction: | Create ONLY if implementation status is READY_FOR_TESTING. - Derive test strategy from acceptance criteria. + Derive strategy from acceptance criteria. test_checklist: path: "{dir}/testing/checklist.md" @@ -601,22 +770,35 @@ rules: 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 blocks from test discussion ([RESULT] PASS/FAIL: description). + 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 with clear reproduction steps. - Initialize bug discussion and fix plan in same folder. + 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" @@ -631,20 +813,44 @@ rules: 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 enhancement opportunity. + 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 defect. + 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 @@ -1145,22 +1351,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}.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. +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.sum.md + ├─ feature.discussion.sum.md ├─ design.discussion.md - ├─ design.sum.md + ├─ design.discussion.sum.md ├─ implementation.discussion.md - ├─ implementation.sum.md + ├─ implementation.discussion.sum.md ├─ testing.discussion.md - ├─ testing.sum.md + ├─ testing.discussion.sum.md ├─ review.discussion.md - └─ review.sum.md + └─ review.discussion.sum.md ``` ### Header (machine-readable) @@ -1248,7 +1454,7 @@ rules: feature_discussion: outputs: summary_companion: - path: "{dir}/discussions/feature.sum.md" + path: "{dir}/discussions/feature.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Create or update the summary file. Replace ONLY content between @@ -1258,28 +1464,28 @@ rules: design_discussion: outputs: summary_companion: - path: "{dir}/discussions/design.sum.md" + 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.sum.md" + 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.sum.md" + 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.sum.md" + 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. @@ -1621,7 +1827,7 @@ agents: - Stage-Per-Discussion: Organizational pattern with separate conversation files for each development phase - Human Gate: Promotion requirement that cannot be satisfied by AI votes alone - Bug Sub-Cycle: Mini feature lifecycle automatically created for test failures -- Template Variables: Placeholders ({basename}, {date}, {dir}, {rel}) resolved in rule paths +- 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 @@ -1645,7 +1851,7 @@ eligibility: 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)\\s*$" response_timeout_hours: 24 timeouts: discussion_stale_days: 3