Introduce IFileContainer for enhanced zip content assertions (#54)

* Add IFileContainer abstraction for zip content assertions

Introduce IFileContainer (with DirectoryFileContainer and ZipFileContainer
implementations) so that the full suite of content assertions (text, xml,
yaml, json, html, pdf, and nested zip) can be applied to entries inside a
zip archive, recursively.

Key changes:
- New IContext interface and ScopedContext wrapper for breadcrumb error messages
- New IFileContainer interface with Glob(), Size(), Open(), and DisplayName
- DirectoryFileContainer wraps a real filesystem directory
- ZipFileContainer wraps a ZipArchive (from path or stream, enabling zip-in-zip)
- All 7 content asserters updated to Run(IContext, IFileContainer, string entryPath)
- FileAssertFile.Run() unified to take IFileContainer (DirectoryInfoWrapper retired)
- FileAssertTest constructs DirectoryFileContainer for top-level filesystem runs
- FileAssertZipAssert rewritten: entries now use FileAssertFileData (full parity),
  opens ZipFileContainer per entry, scopes context with breadcrumb prefix
- FileAssertZipEntryData deleted; FileAssertZipData.Entries reuses FileAssertFileData
- 291 tests across net8/net9/net10 (19 new zip content tests, 2 new modeling tests,
  12 new container unit tests, 2 new scoped context tests, 5 new integration tests)
- Full companion artifact sweep: requirements, design, verification docs, review sets,
  README, and user guide all updated

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix formal review findings from IFileContainer feature branch

* Add OTS design docs to YamlDotNet, PdfPig, HtmlAgilityPack, FileSystemGlobbing review sets

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix second round of formal review findings

* Fix third round of formal review findings

- Add malformed-HTML lenient-parse test for HtmlAgilityPack OTS
- Add HTML and PDF zip-entry assertion tests
- Add multi-page PDF boundary test and PdfMetadataRule negative tests
- Add YamlAssert.Create() validation (empty queries, no-op, contradictory min/max)
- Split compound FileAssertFile Count/Size requirements into atomic requirements
- Fix compound OTS parent requirements (ReviewMark, VersionMark, PdfPig)
- Restructure OTS design docs to Purpose/Features Used/Integration Pattern (ReviewMark, VersionMark, xUnit)
- Fix OTS-ReviewMark design: document URL-based evidence source and network dependency
- Add Features Used and Integration Pattern to OTS-VersionMark design
- Fix xUnit 'or equivalent' ambiguity and PrivateAssets claim
- Fix AllRequirements traceability: FileTypeParsing, FileTypeParseError, QueryAssertions, JUnit
- Add system-level design and verification for --depth flag
- Complete HtmlAssert design doc tables
- Add JUnit configuration verification scenario
- Fix DirectoryFileContainer temp path description
- Fix introduction.md References section to use verbal references

Tests: 326/326 passing

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add 'enation' to cspell word list

Used in multi-page PDF boundary tests to verify the page separator
prevents cross-page token merging (concat + enation).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Remove flawed LockedFile test and FileTypeReadError requirement

File locking via FileShare.None is not reliably enforced on Linux.
The IO error path is already covered by per-asserter IOError tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix duplicated breadcrumb in ZipAssert error messages

ZipFileContainer.GetDisplayPath already builds the full breadcrumb
path (e.g. 'outer.zip > entry.txt'). The additional context.WithPrefix
call in FileAssertZipAssert.Run duplicated it, producing messages like
'outer.zip > File ''outer.zip > entry.txt'' ...'.

Remove WithPrefix from ZipAssert.Run and rely solely on GetDisplayPath.
Also tighten the breadcrumb test to assert the zip name appears exactly
once in the error message, so this cannot regress silently.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix PR review findings: silent-pass, backslash patterns, misc

- Remove entries: alias (never shipped, no backward compat needed)
- Validate zip: block requires at least one files: entry; null/empty
  now throws InvalidOperationException instead of silently passing
- Normalize backslash separators in glob patterns before matching
  so sub\*.txt works against forward-slash normalized entry paths
- Add tests: NullFiles/EmptyFiles throw, BackslashPattern matches,
  invalid YAML throws, selftest scenario name corrected

Tests: 329/329 passing

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix MultiRuntime reqstream filter prefix (net8.0 not dotnet8.x)

The build job produces TRX files named 'macos-latest_net8.0_*.trx'.
ReqStream derives the source filter from the TRX filename, so the
correct prefix is 'net8.0@', not 'dotnet8.x@'.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Developer Agent <agent@dema.local>

Author: 4 people

.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?