Sync DEMA agent definitions and update documentation standards

.fileassert.yaml

@@ -1,7 +1,7 @@
 ---
 # FileAssert document validation tests for TestResults.
 # Tests are tagged by document group to allow per-group execution during the build pipeline.
-# Tags: build-notes, code-quality, code-review, design, user-guide, requirements.
+# Tags: build-notes, code-quality, code-review, design, verification, user-guide, requirements.
 #
 # NOTE: build-notes through user-guide tests provide OTS evidence for Pandoc and WeasyPrint
 # and run before ReqStream. The requirements tests run after ReqStream and validate the
@@ -171,6 +171,10 @@ tests:
         html:
           - query: //head/title
             count: 1
+          - query: //nav[@id='TOC']
+            count: 1
+          - query: (//span[@class='header-section-number'])[1]
+            count: 1
         text:
           - contains: Design
 
@@ -193,6 +197,43 @@ tests:
           text:
             - contains: Design
 
+  # --- VERIFICATION DOCUMENT ---
+
+  - name: Pandoc_VerificationHtml
+    description: Verification HTML was generated by Pandoc
+    tags: [verification]
+    files:
+      - pattern: docs/verification/generated/verification.html
+        count: 1
+        html:
+          - query: //head/title
+            count: 1
+          - query: //nav[@id='TOC']
+            count: 1
+          - query: (//span[@class='header-section-number'])[1]
+            count: 1
+        text:
+          - contains: Verification
+
+  - name: WeasyPrint_VerificationPdf
+    description: Verification PDF was generated by WeasyPrint
+    tags: [verification]
+    files:
+      - pattern: "docs/generated/TestResults Software Verification Design.pdf"
+        count: 1
+        pdf:
+          metadata:
+            - field: Title
+              contains: Verification
+            - field: Author
+              contains: DEMA Consulting
+            - field: Subject
+              contains: Verification
+          pages:
+            min: 3
+          text:
+            - contains: Verification
+
   # --- USER GUIDE ---
 
   - name: Pandoc_UserGuideHtml

.github/agents/developer.agent.md

@@ -19,7 +19,7 @@ Perform software development tasks by determining and applying appropriate stand
      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
@@ -35,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

@@ -44,6 +44,7 @@ standards from the selection matrix in AGENTS.md.
 # 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}
+```