1st commit

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_<slug>/
 │  │  │        ├─ 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 with extension (e.g., design.discussion.md)
-- {basename}: Filename without extension
+- {name} — filename without extension (e.g., design.discussion)
-- {date}: Current date in YYYY-MM-DD format
+- {ext} — file extension without dot (e.g., md)
-- {rel}: Repository-relative path to source file
+- {date} — current date in YYYY-MM-DD
-- {dir}: Directory containing the source file (NEW)
+- {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
 
@@ -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_<slug>
+stage_id: FR_YYYY-MM-DD_<slug>_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_<slug>
+stage_id: FR_YYYY-MM-DD_<slug>_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_<slug>
+stage_id: FR_YYYY-MM-DD_<slug>_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_<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
@@ -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_<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
@@ -330,9 +376,19 @@ bugs/BUG_YYYYMMDD_<slug>/
 - 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 or report to discussions/review.discussion.md (OPEN)
-- Creates review/findings.md with verification summary
+- Creates review/findings_BUG_YYYYMMDD_<slug>.md with verification summary
 
 ### Stage 6: Review Discussion
 - File: discussions/review.discussion.md
@@ -344,6 +400,8 @@ bugs/BUG_YYYYMMDD_<slug>/
 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
@@ -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
-Each comment must end with: VOTE: READY|CHANGES|REJECT
+- Last line of comment, exact format
-
+- Multiple votes by same participant: latest wins
-Last line of comment, exact format
+- Trailing spaces are ignored; the vote must be the final non-empty line
-
-Multiple votes by same participant: latest wins
 
 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** | `<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
@@ -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"
+  "request.md":                          "feature_request"
-  "feature.discussion.md":       "feature_discussion"
+
-  "design.discussion.md":        "design_discussion"
+  # discussions
-  "implementation.discussion.md":"impl_discussion"
+  "feature.discussion.md":               "feature_discussion"
-  "testing.discussion.md":       "test_discussion"
+  "design.discussion.md":                "design_discussion"
-  "review.discussion.md":        "review_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
+          - Flip status to READY_FOR_DESIGN (or FEATURE_REJECTED)
-          - Clearly state promotion decision in comment
+          Clearly state promotion decision. Append-only with minimal diff.
-          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.
+          Create bug report ONLY when test failure has clear reproduction steps.
-          Initialize bug discussion and fix plan in same folder.
+          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