Introduce IFileContainer for enhanced zip content assertions

.cspell.yaml

@@ -26,6 +26,7 @@ words:
   - deserialize
   - deserializes
   - dogfooding
+  - enation
   - fileassert
   - fontconfig
   - initialise

.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}
+```

.github/agents/quality.agent.md

@@ -13,14 +13,23 @@ Grade and validate software development work by ensuring compliance with project
 1. **Analyze the task request AND completed work** to determine scope: identify
    which artifact categories were changed, and which *should have been changed*
    given the task - new user-visible features always require requirements,
-   design, and review-set coverage regardless of whether those files were touched;
-   test-only additions (corner-case tests, defensive boundary tests, regression
-   tests) do not require a corresponding requirement
+   design, verification docs, and README/user guide updates regardless of
+   whether those files were touched; Review Sets are always in scope when
+   the software item hierarchy changes (units or subsystems added, removed, or
+   reorganized); test-only additions (corner-case tests, defensive boundary
+   tests, regression tests) do not require a corresponding requirement; if a
+   planning companion artifact table is provided in context, cross-reference it
+   — any artifact listed as create/update must be covered in the evaluation and
+   FAIL if the artifact was not produced
 2. **Read relevant standards** using the selection matrix in AGENTS.md
 3. **Evaluate all in-scope categories** - N/A only when the task genuinely
    cannot affect a category; if the task introduces new user-visible features or
-   structural changes then Requirements, Design Documentation, and Review
-   Management are always in scope and FAIL if the artifacts were not updated
+   structural changes then Requirements, Design Documentation, and Verification
+   Documentation are always in scope and FAIL if the artifacts were not updated;
+   Documentation (README/user guide) is always in scope for user-facing changes
+   and FAIL if not updated; Review Sets are always in scope when the
+   software item hierarchy changes (units or subsystems added, removed, or
+   reorganized) and FAIL if review-sets were not updated
 4. **Validate tool compliance** using ReqStream, ReviewMark, and build tools
 5. **Generate focused quality report** per the AGENTS.md reporting requirements - save to
    `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller
@@ -36,6 +45,7 @@ For each checklist item in the template below, record as `(PASS|FAIL|N/A) - {one
 # Quality Assessment Report
 
 **Result**: (SUCCEEDED|FAILED)
+**Report**: `.agent-logs/quality-{subject}-{unique-id}.md`
 **Overall Grade**: (PASS|FAIL)
 
 ## Required Fixes (only when Result is FAILED)
@@ -50,13 +60,13 @@ Priority-ordered list of issues that MUST be resolved for the next retry:
 
 - **Evaluated**: {List sections assessed and why}
 - **Skipped**: {One-line per skipped section with reason, e.g., "Design
-  Documentation: N/A - no design files modified"}
+  Documentation: N/A - no component behavior, structure, or interface changed"}
 
 ## Requirements Compliance: (PASS|FAIL|N/A)
 
 - Were requirements created/updated for all functional changes?
 - Were source filters applied for platform-specific requirements?
-- Is requirements traceability maintained to tests?
+- Is forward traceability from requirements to verification artifacts preserved?
 
 ## Design Documentation Compliance: (PASS|FAIL|N/A)
 
@@ -80,7 +90,14 @@ Priority-ordered list of issues that MUST be resolved for the next retry:
 - Are cross-hierarchy test dependencies documented in design docs?
 - Do all tests pass?
 
-## Review Management Compliance: (PASS|FAIL|N/A)
+## Verification Documentation Compliance: (PASS|FAIL|N/A)
+
+- Were verification documents created/updated for all new or changed components?
+- Do verification documents include all mandatory sections (Verification Approach, Test Environment,
+  Acceptance Criteria, Test Scenarios)?
+- Is requirements-to-test coverage tracked via the ReqStream trace matrix (not embedded in verification docs)?
+
+## Review Sets Compliance: (PASS|FAIL|N/A)
 
 - Were review-sets updated for structural changes?
 - Is review scope appropriate for change magnitude?