Template cleanup

.cspell.yaml

@@ -9,14 +9,14 @@
 # - NEVER add a misspelled word to the 'words' list
 # - PROPOSE only genuine technical terms/names as needed
 
-version: "0.2"
+version: '0.2'
+
 language: en
 
 # Project-specific technical terms and tool names
 words:
-  - behaviour
-  - behaviours
   - buildmark
+  - CIFS
   - Dema
   - fileassert
   - fileshare
@@ -25,38 +25,36 @@ words:
   - nendobj
   - nstartxref
   - pandoc
-  - parallelisation
+  - pdfsharp
   - Pdfs
   - planfile
+  - postconditions
   - Qube
-  - recognised
   - reportfile
   - reqstream
+  - rethrowing
   - reviewmark
   - Sarif
   - sarifmark
   - selftest
   - sonarmark
-  - summarising
-  - unrecognised
   - unreviewed
   - versionmark
   - weasy
   - weasyprint
   - xunit
   - yamlfix
+  - yamldotnet
 
-# Exclude common build artifacts, dependencies, and vendored third-party code
 ignorePaths:
-  - "**/.git/**"
-  - "**/node_modules/**"
-  - "**/.venv/**"
-  - "**/thirdparty/**"
-  - "**/third-party/**"
-  - "**/3rd-party/**"
-  - "**/generated/**"
-  - "**/AGENT_REPORT_*.md"
-  - "**/.agent-logs/**"
-  - "**/bin/**"
-  - "**/obj/**"
+  - '**/.git/**'
+  - '**/node_modules/**'
+  - '**/.venv/**'
+  - '**/thirdparty/**'
+  - '**/third-party/**'
+  - '**/3rd-party/**'
+  - '**/.agent-logs/**'
+  - '**/bin/**'
+  - '**/obj/**'
+  - '**/generated/**'
   - package-lock.json

.fileassert.yaml

@@ -36,7 +36,7 @@ tests:
             - field: "Author"
               contains: "DEMA Consulting"
             - field: "Subject"
-              contains: "Build notes"
+              contains: "Build Notes"
           pages:
             min: 1
           text:
@@ -201,7 +201,7 @@ tests:
             - field: "Author"
               contains: "DEMA Consulting"
             - field: "Subject"
-              contains: "Verification design document"
+              contains: "Verification Design Document"
           pages:
             min: 3
           text:
@@ -234,7 +234,7 @@ tests:
             - field: "Author"
               contains: "DEMA Consulting"
             - field: "Subject"
-              contains: "File-Review Evidence Management"
+              contains: "User Guide"
           pages:
             min: 3
           text:
@@ -302,7 +302,7 @@ tests:
             - field: "Author"
               contains: "DEMA Consulting"
             - field: "Subject"
-              contains: "Traceability"
+              contains: "Trace Matrix"
           pages:
             min: 1
           text:

.github/agents/developer.agent.md

@@ -14,6 +14,10 @@ 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)
    - Include companion artifact updates in the work plan

.github/agents/quality.agent.md

@@ -54,77 +54,64 @@ Priority-ordered list of issues that MUST be resolved for the next retry:
 
 ## Requirements Compliance: (PASS|FAIL|N/A)
 
-- Were requirements updated to reflect functional changes?
-- Were new requirements created for new features?
-- Do requirement IDs follow semantic naming standards?
-- Do requirement files follow kebab-case naming convention?
-- Are requirement files organized under `docs/reqstream/` with proper folder structure?
-- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder?
-- Were source filters applied appropriately for platform-specific requirements?
+- Were requirements created/updated for all functional changes?
+- Were source filters applied for platform-specific requirements?
 - Is requirements traceability maintained to tests?
 
 ## Design Documentation Compliance: (PASS|FAIL|N/A)
 
-- Were design documents updated for architectural changes?
-- Were new design artifacts created for new components?
-- Do design folder names use kebab-case convention matching source structure?
-- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)?
+- Were design artifacts created/updated for all new or changed components?
 - Is `docs/design/introduction.md` present with required Software Structure section?
 - Are design decisions documented with rationale?
 - Is system/subsystem/unit categorization maintained?
 - Is design-to-implementation traceability preserved?
 
 ## Code Quality Compliance: (PASS|FAIL|N/A)
 
-- Are language-specific standards followed (from applicable standards files)?
-- Are quality checks from standards files satisfied?
-- Is code properly categorized (system/subsystem/unit/OTS)?
-- Is appropriate separation of concerns maintained?
-- Was language-specific build tooling executed and passing?
+- Do language-specific quality checks from loaded standards pass?
+- Is code properly categorized (system/subsystem/unit/OTS/Shared Package)?
+- Does the build pass?
 
 ## Testing Compliance: (PASS|FAIL|N/A)
 
 - Were tests created/updated for all functional changes?
 - Is test coverage maintained for all requirements?
-- Are testing standards followed (AAA pattern, etc.)?
-- Do tests respect software item hierarchy boundaries (System/Subsystem/Unit scope)?
+- Do tests respect software item hierarchy boundaries?
 - Are cross-hierarchy test dependencies documented in design docs?
-- Does test categorization align with code structure?
-- Do all tests pass without failures?
+- Do all tests pass?
 
 ## Review Management Compliance: (PASS|FAIL|N/A)
 
-- Were review-sets updated for structural changes (new/deleted systems, subsystems, or units)?
-- Do file patterns follow include-then-exclude approach?
+- Were review-sets updated for structural changes?
 - Is review scope appropriate for change magnitude?
-- Was ReviewMark tooling executed and passing?
-- Were review artifacts generated correctly?
+- Does ReviewMark pass?
 
 ## Documentation Compliance: (PASS|FAIL|N/A)
 
-- Was README.md updated for user-facing changes?
-- Were user guides updated for feature changes?
+- Were README.md and user guides updated for user-facing changes?
 - Does API documentation reflect code changes?
 - Was compliance documentation generated?
-- Does documentation follow standards formatting?
-- Is documentation organized under `docs/` following standard folder structure?
-- Do Pandoc collections include proper `introduction.md` with Purpose and Scope sections?
 - Are auto-generated markdown files left unmodified?
-- Do README.md files use absolute URLs and include concrete examples?
-- Is documentation integrated into ReviewMark review-sets for formal review?
+- Is documentation integrated into ReviewMark review-sets?
 
 ## Software Item Completeness: (PASS|FAIL|N/A)
 
+- Load `software-items.md` before evaluating this section.
+
 - Does every identified software unit have its own requirements file?
 - Does every identified software unit have its own design document?
 - Does every identified subsystem have its own requirements file?
 - Does every identified subsystem have its own design document?
 
+## Repository Structure Compliance: (PASS|FAIL|N/A)
+
+- Load `repository-map.md` from the template URL in the `# Reference Template`
+  section of `AGENTS.md` before evaluating this section.
+
+- Are parallel artifact trees in sync (reqstream/design/verification/src/test)?
+- Does the repository conform to the template `repository-map.md`?
+
 ## Process Compliance: (PASS|FAIL|N/A)
 
-- Was Continuous Compliance workflow followed?
-- Did all quality gates execute successfully?
-- Were appropriate tools used for validation?
-- Were standards consistently applied across work?
-- Was compliance evidence generated and preserved?
+- Was compliance evidence (test results, review artifacts, generated docs) generated and preserved?
 ```

.github/agents/software-architect.agent.md

@@ -13,7 +13,7 @@ Interview the user and produce evolving architecture documentation with prioriti
 # Standards
 
 Read `.github/standards/software-items.md` before starting. Use its definitions
-(Software Package, System, Subsystem, Unit, OTS) as vocabulary throughout.
+(Software Package, System, Subsystem, Unit, OTS, Shared Package) as vocabulary throughout.
 
 # Approach
 

.github/agents/template-sync.agent.md

@@ -0,0 +1,109 @@
+---
+name: template-sync
+description: Audits or synchronizes repository files against the canonical template.
+  Supports four modes - Audit, Sync, Scaffold, and Recreate.
+user-invocable: true
+---
+
+# Template Sync Agent
+
+This agent is an orchestrator supporting four modes:
+
+- **Audit** - report structural deviations; no changes
+- **Sync** - patch missing sections into existing files
+- **Scaffold** - create files that do not yet exist; skip existing files
+- **Recreate** - rebuild existing files from the template, migrating old content
+
+Read the template URL and `repository-map.md` from the `# Reference Template`
+section in `AGENTS.md`, then map the requested scope onto the work groups below.
+Delegate each group to a sub-agent.
+
+# Work Groups
+
+- **Root config files** - all non-collection files at the repository root
+- **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/`
+- **One group per system subtree** in `docs/design/`, `docs/verification/`, `docs/reqstream/` -
+  each subtree and all its descendants is one group
+
+# Orchestration
+
+For each group intersecting the requested scope, call a sub-agent with:
+
+- **context**:
+  - Group scope and template URL from the `# Reference Template` section in `AGENTS.md`
+  - Applicable standards from the `# Standards Application` matrix in `AGENTS.md`
+    for the file types in the group scope
+  - Project-specific names substitute for placeholders at matching path depth
+    (e.g. `SystemName` → `{SystemName}`, `system-name` → `{system-name}`)
+  - For files within `{system-name}/` subtrees in `docs/design/`, `docs/verification/`,
+    and `docs/reqstream/`: consult `docs/design/introduction.md` to determine whether
+    each item is a subsystem or unit, then select the appropriate template
+    (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth —
+    do not infer item type from path depth alone
+  - If a template counterpart cannot be fetched, skip the file and report it
+- **goal**:
+  - Based on the given mode:
+    - **Audit** - fetch each template counterpart; compare headings; report missing
+      sections and depth mismatches; no changes
+    - **Sync** - as Audit, then insert each missing section; run `pwsh ./fix.ps1`
+    - **Scaffold** - fetch `repository-map.md` from the template URL in `AGENTS.md`
+      to identify files that should exist but don't; for each, fetch the template,
+      populate all sections, write the file; run `pwsh ./fix.ps1`
+    - **Recreate** - fetch the template and use it as the blueprint for a
+      freshly authored document:
+      - Work through the template section by section; for each section, find
+        any `TEMPLATE-DIRECTIVE` blocks (both `<!-- TEMPLATE-DIRECTIVE: ... -->`
+        in markdown and `# <!-- TEMPLATE-DIRECTIVE: ... -->` in YAML) — execute
+        each directive (read specified standards, apply structural guidance,
+        substitute content), then **remove the directive block entirely** from
+        the output; gather the relevant technical details from all available
+        sources — the old file, README, related docs, sibling files, and any
+        other repo context — to populate that section correctly; the old file's
+        structure and headings are irrelevant; only its factual content is mined
+        as a source
+      - **Gap-check**: after all template sections are filled, scan the old
+        file once more for any technical information not yet captured; if
+        found, preserve it by appending new relevant sections at the end
+      - **Before writing**: do a mandatory self-check — for every section that
+        has a `TEMPLATE-DIRECTIVE` block in the template, explicitly state what
+        format the directive requires, then verify the drafted content matches
+        that format exactly (e.g. if the directive says "no sub-headings",
+        confirm there are no `###` headings inside that section; if it says
+        "bold-name paragraph blocks", confirm each entry is `**Name**: prose`
+        with no sub-heading); fix any mismatches before writing the file
+      - Write the rebuilt file; run `pwsh ./fix.ps1`
+  - When writing any section: `TEMPLATE-DIRECTIVE` blocks are directives —
+    execute them (read specified standards, apply structural guidance, substitute
+    content) and **remove the block entirely** from the written file; inline
+    `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`)
+    are content placeholders — always resolve them to real content; infer from
+    README, related files, sibling docs, and path; if confident write directly;
+    if ambiguous offer 2–3 concrete options and ask the user; keep asking until
+    they answer - never leave a TODO or TEMPLATE-DIRECTIVE in the output unless
+    the user explicitly requests it
+
+Collect sub-agent results and assemble the final report.
+
+# Report Template
+
+```markdown
+# Template Sync Report
+
+**Result**: (SUCCEEDED|FAILED)
+**Mode**: (Audit|Sync|Scaffold|Recreate)
+
+## Files
+
+### {file-path}
+
+- **Template**: {template path}
+- **Missing sections**: {list or "none"}
+- **Heading depth issues**: {list or "none"}
+- **Content format issues**: {list of sections where intra-section content did not
+  match the template comment's prescribed format, or "none"} *(Recreate only)*
+- **Action**: (Reported | Sections added | Created | Rebuilt | No template found)
+
+## Summary
+
+- **Conformant**: {count} | **Deviations**: {count} | **Updated**: {count}
+```