Refactor documentation and apply formal review findings

.cspell.yaml

@@ -15,6 +15,7 @@ language: en
 # Project-specific technical terms and tool names
 words:
   - Blockquotes
+  - Postconditions
   - buildmark
   - buildtransitive
   - contentfiles

.github/agents/developer.agent.md

@@ -14,8 +14,12 @@ Perform software development tasks by determining and applying appropriate stand
 2. **Read relevant standards** using the selection matrix in AGENTS.md
 3. **Pre-flight verification** before making any changes:
    - List files that will be created, modified, or deleted
+   - For each file to be **created**, check whether a counterpart exists in the
+     template (URL in the `# Reference Template` section of `AGENTS.md`).
+     If one exists, fetch it as the starting point; adjust placeholder names and heading
+     depth to match the target path before writing the file
    - For each modified file, identify which companion artifacts need updating
-     (requirements, design docs, tests, review-sets)
+     (requirements, design docs, verification docs, tests, review-sets, README.md, user guides)
    - Include companion artifact updates in the work plan
 4. **Execute work** following standards requirements and quality checks
 5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all
@@ -31,8 +35,7 @@ Perform software development tasks by determining and applying appropriate stand
 # Developer Agent Report
 
 **Result**: (SUCCEEDED|FAILED)
-
-## Work Summary
+**Report**: `.agent-logs/developer-{subject}-{unique-id}.md`
 
 - **Files Modified**: {List of files created/modified/deleted}
 - **Languages Detected**: {Languages identified}

.github/agents/formal-review.agent.md

@@ -31,19 +31,22 @@ standards from the selection matrix in AGENTS.md.
 1. Download the review checklist from
    <https://github.com/demaconsulting/ContinuousCompliance/raw/refs/heads/main/docs/review-template/review-template.md>.
    If the download fails, report the failure rather than proceeding without the template.
-2. Use `dotnet reviewmark --elaborate {review-set}` to get the files to review
-3. Review all files holistically, checking for cross-file consistency and
-   compliance with the review checklist
-4. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`.
+2. Run `dotnet reviewmark --elaborate {review-set}`. Read all files listed under
+   `## Context` first — these are reference material, not under review — then review
+   all files listed under `## Files` holistically, using the context to understand
+   the intended role and scope within the broader system, and checking for cross-file
+   consistency and compliance with the review checklist.
+3. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`.
    This directory holds formal review artifacts, not agent logs.
-5. Generate a completion report per the AGENTS.md reporting requirements.
+4. Generate a completion report per the AGENTS.md reporting requirements.
 
 # Report Template
 
 ```markdown
 # Formal Review Report
 
 **Result**: (SUCCEEDED|FAILED)
+**Report**: `.agent-logs/formal-review-{subject}-{unique-id}.md`
 
 ## Review Summary
 

.github/agents/implementation.agent.md

@@ -28,36 +28,18 @@ The state-transitions include retrying a limited number of times:
 
 ## PLANNING State (start)
 
-Call the **explore** agent as a sub-agent (built-in agent type) with:
+Call the **planning** agent as a sub-agent (custom agent from `.github/agents/`) with:
 
 - **context**: the user's request + any previous quality findings + retry context
-- **goal**: produce a verified implementation plan through these steps:
-
-  1. Investigate the codebase and develop a concrete implementation plan that
-     addresses the request
-  2. **Identify companion artifact deliverables**: for every code change in the
-     plan, list the requirements files, design documents, and review-set entries
-     that must be created or updated - traceability must flow requirements →
-     design → code, so these are mandatory deliverables, not optional extras
-  3. Review the plan for assumptions, weaknesses, and gaps - identify up to 5
-     key assumptions and rate each as:
-     - **VERIFIED**: confirmed by codebase evidence
-     - **LIKELY**: consistent with codebase patterns but not directly confirmed
-     - **UNVERIFIED**: not confirmed by any evidence
-  4. For any assumption rated UNVERIFIED or LIKELY, attempt to resolve it
-     through additional investigation and revise the plan to address identified
-     weaknesses - repeat the critique-and-strengthen cycle up to 2 additional
-     times if unresolved issues remain, but stop as soon as the plan is stable
-  5. List up to 5 risks to the implementation
-  6. Assess feasibility: can this be implemented in a single development pass?
-  7. State a **recommendation**: GO or INCOMPLETE - GO if the plan is sound, or
-     INCOMPLETE if critical unknowns remain that only the user can resolve
-
-Once the explore sub-agent finishes:
-
-- IF recommendation is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE,
+- **goal**: produce a verified implementation plan, or a targeted plan to address
+  the identified quality issues if this is a retry
+
+Once the planning sub-agent finishes:
+
+- IF Result is FAILED: Transition to REPORT with Result: FAILED
+- IF Result is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE,
   listing the unknowns and what CAN be implemented once they are resolved
-- OTHERWISE (GO): Transition to DEVELOPMENT
+- OTHERWISE (SUCCEEDED): Transition to DEVELOPMENT
 
 ## DEVELOPMENT State
 
@@ -76,7 +58,8 @@ Once the developer sub-agent finishes:
 
 Call the **quality** agent as a sub-agent (custom agent from `.github/agents/`) with:
 
-- **context**: the user's request + development summary + files changed + previous issues (if any)
+- **context**: the user's request + development summary + files changed + planning companion artifact table +
+  previous issues (if any)
 - **goal**: check the quality of the work performed for any issues
 
 Once the quality sub-agent finishes:
@@ -92,6 +75,9 @@ Once the quality sub-agent finishes:
 this agent may report INCOMPLETE when the request cannot be implemented without
 information only the user can provide.
 
+For full planning details (assumptions, risks, feasibility), read the planning
+report file referenced in the planning agent's response.
+
 Generate the completion report using the template below, then save it to
 `.agent-logs/{agent-name}-{subject}-{unique-id}.md` per the AGENTS.md reporting
 requirements, and return the summary to the caller.
@@ -102,19 +88,20 @@ requirements, and return the summary to the caller.
 # Implementation Orchestration Report
 
 **Result**: (SUCCEEDED|FAILED|INCOMPLETE)
-**Final State**: (PLANNING|DEVELOPMENT|QUALITY|REPORT)
+**Report**: `.agent-logs/implementation-{subject}-{unique-id}.md`
+**Last Active State**: (PLANNING|DEVELOPMENT|QUALITY)
 **Retry Count**: <Number of quality retry cycles>
 
 ## State Machine Execution
 
-- **Planning Results**: {Implementation plan, assumption ratings, risks, and recommendation}
+- **Planning Results**: {Planning report path; plan summary and SUCCEEDED/INCOMPLETE/FAILED result}
 - **Development Results**: {Summary of developer agent results}
 - **Quality Results**: {Summary of quality agent results}
 - **State Transitions**: {Log of state changes and decisions}
 
 ## Sub-Agent Coordination
 
-- **Explore Agent (Planning)**: {Plan, assumption verdicts, top risks, GO/INCOMPLETE recommendation}
+- **Planning Agent**: {Report file path, SUCCEEDED/INCOMPLETE/FAILED result, plan summary}
 - **Developer Agent**: {Development status and files modified}
 - **Quality Agent**: {Validation results and compliance status}
 
@@ -123,4 +110,9 @@ requirements, and return the summary to the caller.
 - **Implementation Success**: {Overall completion status}
 - **Quality Compliance**: {Final quality validation status}
 - **Issues Resolved**: {Problems encountered and resolution attempts}
+
+## Unknowns (only when Result is INCOMPLETE)
+
+- **Unresolved Questions**: {List each question the user must answer}
+- **What Can Proceed**: {Work that can be done without the missing information}
 ```

.github/agents/lint-fix.agent.md

@@ -68,8 +68,7 @@ submission, not during normal development.
 # Lint Fix Report
 
 **Result**: (SUCCEEDED|FAILED)
-
-## Summary
+**Report**: `.agent-logs/lint-fix-{subject}-{unique-id}.md`
 
 - **Iterations**: {Number of fix-loop iterations performed}
 - **Files Modified**: {List of all files changed}

.github/agents/planning.agent.md

@@ -0,0 +1,134 @@
+---
+name: planning
+description: Planning agent that investigates the codebase, develops a verified implementation plan, and identifies all companion artifact deliverables.
+user-invocable: true
+---
+
+# Planning Agent
+
+Investigate the codebase and produce a verified implementation plan with all
+companion artifact deliverables.
+
+## Step 1 — Load Standards
+
+Read the relevant standards from `.github/standards/` using the selection matrix
+in `AGENTS.md` based on the artifact types in scope for the request (requirements,
+design, verification, documentation, code).
+
+## Step 2 — Investigate and Plan
+
+Read `docs/design/introduction.md` first (if present), then investigate the
+codebase to develop a concrete implementation plan:
+
+- Identify all files to create, modify, or delete
+- Describe the change required for each file
+
+## Step 3 — Identify Companion Artifact Deliverables
+
+For each planned change, assess the mandatory companion artifacts below (create/update/N/A
+with justification):
+
+- **Requirements** — functional changes require a requirement entry
+- **Design Documentation** — new or changed components require design docs
+- **Verification Documentation** — new or changed components require verification docs
+- **Tests** — functional changes require test coverage
+- **Review Sets** — changes to the software item hierarchy (units or subsystems
+  added, removed, or reorganized) require review-set updates
+- **README.md** — user-facing changes require README updates
+- **User Guide** — user-facing features require user guide updates
+
+## Step 4 — Critique and Strengthen
+
+Identify up to 5 key assumptions and rate each:
+
+- **VERIFIED**: confirmed by codebase evidence
+- **LIKELY**: consistent with codebase patterns but not directly confirmed
+- **UNVERIFIED**: not confirmed by any evidence
+
+For UNVERIFIED or LIKELY assumptions, investigate further and revise the plan.
+Repeat up to 2 more times, stopping when the plan is stable.
+
+## Step 5 — Risk Assessment
+
+List up to 5 risks with a brief mitigation for each.
+
+## Step 6 — Feasibility Assessment
+
+State whether this can be implemented in a single development pass and any
+preconditions that affect feasibility.
+
+## Step 7 — Recommendation
+
+- **SUCCEEDED** — the plan is sound and the developer agent can proceed
+- **INCOMPLETE** — critical unknowns remain that only the user can resolve;
+  list each unknown explicitly
+- **FAILED** — investigation could not produce a viable plan
+
+# REPORT Phase
+
+Save the full analysis to `.agent-logs/planning-{subject}-{unique-id}.md` per
+the AGENTS.md reporting requirements.
+
+Then respond to the caller with ONLY the lean structured summary below.
+
+# Report Template
+
+```markdown
+# Planning Report
+
+**Result**: (SUCCEEDED|INCOMPLETE|FAILED)
+**Request Summary**: {Brief restatement of the task as understood}
+**Report**: `.agent-logs/planning-{subject}-{unique-id}.md`
+
+## Implementation Plan
+
+| File | Action | Description |
+|------|--------|-------------|
+| {path} | create/modify/delete | {what changes and why} |
+
+## Companion Artifact Deliverables
+
+| Category | File | Action |
+|----------|------|--------|
+| Requirements | {path} | create/update/N/A — {justification} |
+| Design Documentation | {path} | create/update/N/A — {justification} |
+| Verification Documentation | {path} | create/update/N/A — {justification} |
+| Tests | {path} | create/update/N/A — {justification} |
+| Review Sets | {path} | create/update/N/A — {justification} |
+| README.md | {path} | create/update/N/A — {justification} |
+| User Guide | {path} | create/update/N/A — {justification} |
+
+## Assumption Analysis
+
+| # | Assumption | Rating | Resolution |
+|---|-----------|--------|------------|
+| 1 | {assumption} | VERIFIED/LIKELY/UNVERIFIED | {resolution or N/A} |
+
+## Risk Assessment
+
+1. **[severity]** {risk} — {mitigation}
+
+## Feasibility Assessment
+
+{Single-pass or not, and why. Any preconditions.}
+
+## Unknowns
+
+{Only present when Result is INCOMPLETE. List each question the user must
+resolve before implementation can proceed.}
+```
+
+# Lean Structured Response (returned to caller)
+
+```markdown
+**Result**: (SUCCEEDED|INCOMPLETE|FAILED)
+**Report**: `.agent-logs/planning-{subject}-{unique-id}.md`
+
+**Plan**:
+{Repeat the Implementation Plan table}
+
+**Companion Artifacts**:
+{Repeat the Companion Artifact Deliverables table}
+
+**Unknowns**: {Only if INCOMPLETE — list questions for the user}
+```