diff --git a/.github/workflows/verify-2026-08-hardening-guidance.yml b/.github/workflows/verify-2026-08-hardening-guidance.yml
index a4d7dcb..10879e9 100644
--- a/.github/workflows/verify-2026-08-hardening-guidance.yml
+++ b/.github/workflows/verify-2026-08-hardening-guidance.yml
@@ -6,19 +6,22 @@ name: verify 2026-08 hardening guidance analysis
#
# It runs in two passes, and the split is the point:
#
-# 1. offline exactly what a contributor can run on a laptop with no
-# network. If this fails, the failure is reproducible locally.
-# 2. strict the same harness with --strict, which turns every skipped
-# check into a failure. The runner has network and can install
-# an OSCAL validator and a headless browser, so the four checks
-# that skip locally have to pass here.
+# 1. offline the harness uses --offline: after dependencies and sources
+# are acquired, verification does not access the network.
+# 2. strict --all --strict counts every skipped check as a failure,
+# including schema, external-link and browser checks.
+#
+# Both passes run corpus-independent regression checks before preparing the
+# repository-defined sources in tools/source-lock.json. Explicit preparation
+# fetches only the pinned public AWS archive; --check verifies its cache and
+# the committed IBM/Easy Dynamics examples without network access. Missing or
+# corrupt inputs fail the job; source checks never skip or count empty inputs.
#
# Without the second pass a skipped check stays skipped forever, and the harness
# quietly stops covering the thing it was written to cover.
#
-# The repository is checked out under site/ so the corpora can sit beside it
-# rather than inside it: the byte-identical check below runs `git diff`, and a
-# 231-file corpus inside the working tree would be untracked noise in it.
+# The repository stays under site/. The public source cache is ignored by Git;
+# no second checkout or source-repository Actions variables are required.
on:
push:
@@ -41,7 +44,6 @@ permissions:
env:
SITE: site/docs/analysis/2026-08-automating-technical-hardening-guidance
- TFG_CORPORA: ${{ github.workspace }}/tfg-automated-assessments
jobs:
offline:
@@ -52,14 +54,6 @@ jobs:
with:
path: site
- - name: Check out the source corpora
- uses: actions/checkout@v4
- with:
- repository: OSCAL-Foundation/tfg-automated-assessments
- path: tfg-automated-assessments
- continue-on-error: true
- id: corpora
-
- uses: actions/setup-python@v5
with:
python-version: "3.12"
@@ -71,51 +65,73 @@ jobs:
# Pillow is not optional: verify.py imports svgrender, which imports PIL
# at module scope, so the harness will not start without it.
- name: Install the harness dependencies
- run: pip install pyyaml pillow
+ run: pip install pyyaml pillow 'jsonschema[format]' regex
# svgrender loads DejaVu by absolute path rather than through fontconfig.
- name: Install the fonts the rasteriser names
run: sudo apt-get install -y --no-install-recommends fonts-dejavu-core
- - name: Report whether the corpora are present
+ - name: Run banner regression checks
+ working-directory: ${{ env.SITE }}
+ run: node tools/bannercheck.js
+
+ - name: Run verifier, source-resolver and workflow unit tests
+ working-directory: ${{ env.SITE }}
run: |
- if [ -d "$TFG_CORPORA" ]; then
- echo "corpora present, every check can run"
- else
- echo "::warning::the corpora are not available to this runner, so"\
- "--snippets, --stats and --conformance cannot read them"
- fi
+ for suite in tools/test_verify.py tools/test_source_inputs.py tools/test_workflow.py; do
+ [[ -f "$suite" ]] || { echo "::error::Missing $suite regression tests"; exit 1; }
+ done
+ python -m unittest discover -s tools -p 'test_*.py' -v
- - name: Re-extract every snippet and diff
+ - name: Run corpus-independent structural checks without network
working-directory: ${{ env.SITE }}
- run: python tools/verify.py --snippets
+ # --example invokes the corpus-backed artifact generator. Keep it in
+ # the full --all pass below, not in this independent subset.
+ run: python tools/verify.py --data --css --quotes --bundle --source --pages --offline
- - name: Run every offline check
+ - name: Prepare the locked sources (explicit public download)
+ working-directory: ${{ env.SITE }}
+ run: python tools/source_inputs.py --fetch
+
+ - name: Check the locked sources without network
working-directory: ${{ env.SITE }}
- run: python tools/verify.py --all
+ run: python tools/source_inputs.py --check
- - name: Render each page and inspect the result
+ - name: Re-extract every snippet and diff
+ working-directory: ${{ env.SITE }}
+ run: python tools/verify.py --snippets --offline
+
+ - name: Run every offline check
working-directory: ${{ env.SITE }}
- run: node tools/pagecheck.js
+ run: python tools/verify.py --all --offline
- name: Confirm the generated files are byte-identical to their generators
working-directory: ${{ env.SITE }}
+ shell: bash
run: |
+ set -euo pipefail
# A generated file that has been hand-edited is the one failure this
# repository cannot detect by reading. Regenerate and diff.
+ python tools/source_inputs.py --check
python tools/extract.py
python tools/pattern_examples.py
+ python tools/copy_examples.py
python tools/oscal_artifacts.py
python tools/sources_files.py
python tools/diagrams.py
python tools/approach_pages.py
python tools/scenario_page.py
python tools/bundle.py
- git diff --exit-code -- data assets/diagrams \
- assessment-first.html catalog-first.html component-first.html \
- scenario.html \
- || { echo "::error::a generated file differs from its generator."\
- "Run the generators and commit the result."; exit 1; }
+ outputs=(data assets/diagrams assets/bundle.js
+ assessment-first.html catalog-first.html component-first.html scenario.html)
+ # git diff alone misses newly generated, untracked files.
+ changes=$(git status --porcelain --untracked-files=all -- "${outputs[@]}")
+ if [[ -n "$changes" ]]; then
+ printf '%s\n' "$changes"
+ git diff --stat -- "${outputs[@]}"
+ echo "::error::Generated files differ. Run the generators and commit the results, including additions and deletions."
+ exit 1
+ fi
strict:
name: strict, the checks that need network
@@ -125,12 +141,6 @@ jobs:
with:
path: site
- - uses: actions/checkout@v4
- with:
- repository: OSCAL-Foundation/tfg-automated-assessments
- path: tfg-automated-assessments
- continue-on-error: true
-
- uses: actions/setup-python@v5
with:
python-version: "3.12"
@@ -140,29 +150,49 @@ jobs:
node-version: "20"
- name: Install the harness dependencies
- run: pip install pyyaml pillow
+ # regex supports the Unicode patterns used by the NIST schemas.
+ run: pip install pyyaml pillow 'jsonschema[format]' regex
- name: Install the fonts the rasteriser names
run: sudo apt-get install -y --no-install-recommends fonts-dejavu-core
- - name: Install an OSCAL validator
- # compliance-trestle carries its own copy of the OSCAL schemas and
- # validates a file against the model its root element names, which is
- # what --conformance needs.
- run: pip install compliance-trestle
+ - name: Run banner regression checks
+ working-directory: ${{ env.SITE }}
+ run: node tools/bannercheck.js
+
+ - name: Run verifier, source-resolver and workflow unit tests
+ working-directory: ${{ env.SITE }}
+ run: |
+ for suite in tools/test_verify.py tools/test_source_inputs.py tools/test_workflow.py; do
+ [[ -f "$suite" ]] || { echo "::error::Missing $suite regression tests"; exit 1; }
+ done
+ python -m unittest discover -s tools -p 'test_*.py' -v
+
+ - name: Run corpus-independent structural checks without network
+ working-directory: ${{ env.SITE }}
+ run: python tools/verify.py --data --css --quotes --bundle --source --pages --offline
+
+ - name: Prepare the locked sources (explicit public download)
+ working-directory: ${{ env.SITE }}
+ run: python tools/source_inputs.py --fetch
+
+ - name: Check the locked sources without network
+ working-directory: ${{ env.SITE }}
+ run: python tools/source_inputs.py --check
- name: Install axe-core and a headless browser
+ id: browser_deps
working-directory: ${{ env.SITE }}
- run: npm install --no-save axe-core puppeteer
+ run: npm install --no-save --package-lock=false axe-core puppeteer
- name: Every check, with a skip counted as a failure
working-directory: ${{ env.SITE }}
run: python tools/verify.py --all --strict
- - name: Publish the accessibility report
- if: always()
+ - name: Run accessibility audit even after other check failures
+ if: ${{ !cancelled() && steps.browser_deps.outcome == 'success' }}
working-directory: ${{ env.SITE }}
- run: node tools/axe_run.mjs || true
+ run: python tools/verify.py --a11y --strict
pages-build:
name: the site serves and opens from a folder
diff --git a/.vscode/launch.json b/.vscode/launch.json
index 57ad9c3..69551ba 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -30,10 +30,9 @@
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance/tools/verify.py",
- "args": ["--all"],
+ "args": ["--all", "--offline"],
"cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance",
"console": "integratedTerminal",
- "env": { "TFG_CORPORA": "${env:HOME}/pagesource/tfg-automated-assessments" },
"justMyCode": false
}
]
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index 398fc77..52f89ab 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -35,14 +35,23 @@
"presentation": { "reveal": "never", "panel": "dedicated" },
"problemMatcher": []
},
+ {
+ "label": "analysis 2026-08: prepare sources",
+ "detail": "Explicitly fetch or repair the pinned public AWS cache and check committed examples. Run once before offline verification or regeneration.",
+ "type": "shell",
+ "command": "python3 tools/source_inputs.py --fetch",
+ "options": {
+ "cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance"
+ },
+ "problemMatcher": []
+ },
{
"label": "analysis 2026-08: verify",
- "detail": "Recompute every figure and extract from its published source.",
+ "detail": "Check locked inputs and recompute every figure and extract offline. Run prepare sources explicitly first; this task never fetches inputs.",
"type": "shell",
- "command": "python3 tools/verify.py --all",
+ "command": "python3 tools/source_inputs.py --check && python3 tools/verify.py --all --offline",
"options": {
- "cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance",
- "env": { "TFG_CORPORA": "${input:corporaPath}" }
+ "cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance"
},
"problemMatcher": {
"owner": "verify",
@@ -52,23 +61,16 @@
},
{
"label": "analysis 2026-08: regenerate",
- "detail": "Run every generator. A generated file that differs afterwards was hand-edited.",
+ "detail": "Check locked inputs and run every generator. Run prepare sources explicitly first; this task never fetches inputs.",
"type": "shell",
- "command": "for g in extract pattern_examples oscal_artifacts sources_files diagrams approach_pages scenario_page bundle; do echo \"-- $g\"; python3 tools/$g.py || exit 1; done",
+ "command": "python3 tools/source_inputs.py --check && for g in extract pattern_examples copy_examples oscal_artifacts sources_files diagrams approach_pages scenario_page bundle; do echo \"-- $g\"; python3 tools/$g.py || exit 1; done",
"options": {
- "cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance",
- "env": { "TFG_CORPORA": "${input:corporaPath}" }
+ "cwd": "${workspaceFolder}/docs/analysis/2026-08-automating-technical-hardening-guidance"
},
"problemMatcher": []
}
],
"inputs": [
- {
- "id": "corporaPath",
- "type": "promptString",
- "description": "Path to the tfg-automated-assessments corpora checkout",
- "default": "${env:HOME}/pagesource/tfg-automated-assessments"
- },
{
"id": "terminateServe",
"type": "command",
diff --git a/README.md b/README.md
index 453919b..1be645d 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,28 @@
# OSCAL Foundation — Pattern Library
-A curated collection of high-quality, realistic [OSCAL](https://pages.nist.gov/OSCAL/) example artifacts published by the **OSCAL Foundation** to serve as patterns and practices for the community.
+A collection of [OSCAL](https://pages.nist.gov/OSCAL/) example artifacts published by the **OSCAL Foundation** as community patterns and practices.
## About OSCAL Foundation
-The Open Security Controls Assessment Language (OSCAL) is a machine-readable language that simplifies and standardizes information system security assessments through the exchange of information via automation.
+The Open Security Controls Assessment Language (OSCAL) is a machine-readable language for simplifying and standardizing information system security assessments through automated information exchange.
-Originally developed by the National Institute of Standards and Technology (NIST) in collaboration with FedRAMP and industry, OSCAL aims to improve the efficiency, timeliness, accuracy, and consistency of system security assessments.
+Developed by the National Institute of Standards and Technology (NIST) with FedRAMP and industry, OSCAL aims to improve the efficiency, timeliness, accuracy, and consistency of system security assessments.
-The **OSCAL Foundation** is dedicated to furthering the development and adoption of the OSCAL standards. The Foundation is a nonprofit organization seeking 501(c)(3) tax-exempt status recognition.
+The **OSCAL Foundation** supports the development and adoption of OSCAL standards. The Foundation is a nonprofit organization seeking recognition of 501(c)(3) tax-exempt status.
## Purpose
-There are few high-quality, representative examples of what an actual compliance package in OSCAL looks like, and few places where the arguments about how to build one are written down and kept. This repository holds both.
+The repository collects OSCAL compliance-package examples and design analyses.
-It is published as a website: ** **
+The repository is published as a website: ** **
-Three areas, each with its own lifecycle.
+Three areas have separate lifecycles.
-| Area | What it holds |
+| Area | Contents |
|---|---|
-| [**Patterns**](docs/patterns/summit/) | Model office examples covering the seven OSCAL models, published as files a tool can read |
-| [**Analyses**](docs/analysis/) | Efforts that debate a question about OSCAL, one area per effort, retained after the effort ends |
-| [**Recommendations**](docs/recommendations/) | What the Foundation recommends, each one citing the analysis it came from |
+| [**Patterns**](docs/patterns/summit/) | Model office examples covering the seven OSCAL models, published as machine-readable files |
+| [**Analyses**](docs/analysis/) | Comparisons of OSCAL approaches, retained in separate areas after conclusion |
+| [**Recommendations**](docs/recommendations/) | Foundation recommendations citing the supporting analyses |
## Examples
@@ -32,17 +32,17 @@ Three areas, each with its own lifecycle.
## Analyses
-Each effort gets its own dated area and keeps it. An area is never renamed, never moved and never deleted, and a concluded one is not edited into agreement with a later view: when an effort is superseded the new one gets its own area and the old one is marked, so the record shows the change rather than replacing it.
+Each analysis has a dated area, never renamed, moved, or deleted. Concluded analyses are not rewritten to match later views. A replacement analysis receives a new area; the earlier analysis is marked as superseded to preserve the record.
| Opened | Analysis | Status |
|---|---|---|
| 2026-08 | [Automating Technical Hardening Guidance with OSCAL](docs/analysis/2026-08-automating-technical-hardening-guidance/) | active |
-An analysis carries an `analysis.json` beside its `index.html`, and an entry in [docs/analysis/analyses.json](docs/analysis/analyses.json) that the index page renders from. Adding an effort means adding an area and appending to that file; no page is edited.
+Each analysis has an `analysis.json` beside `index.html` and an entry in [docs/analysis/analyses.json](docs/analysis/analyses.json), the registry rendered by the analysis index. Adding an analysis requires a new area and registry entry, not an index-page edit.
## OSCAL Models Covered
-Each example in this library aims to include artifacts for all seven OSCAL models:
+Each library example aims to include artifacts for all seven OSCAL models:
1. **Catalog** — Security control definitions
2. **Profile** — Baseline selection and tailoring
@@ -54,7 +54,7 @@ Each example in this library aims to include artifacts for all seven OSCAL model
## Repository Structure
-`docs/` is the site, verbatim. There is no build step and nothing is generated at deploy time: what is in the folder is what is published.
+`docs/` is published unchanged, with no build or generation step at deployment.
```
Pattern-Library/
@@ -85,34 +85,45 @@ Pattern-Library/
└── recommendations.json
```
-The artifacts sit inside `patterns/` rather than at the repository root so that the pages linking them resolve the same way locally and published. Nothing has to be copied or rewritten between the two.
+Artifacts reside in `patterns/` rather than the repository root so links resolve identically in local and published pages. No copying or rewriting is required.
## Running the site
-Press **F5**. The `Pattern Library` configuration starts a static server on 4173 and opens the landing page with the debugger attached, so breakpoints in `docs/assets/site.js` bind to the served file. Edge is the default because Chrome is not installed everywhere; the Chrome configuration is there if you have it.
+Press **F5**. The `Pattern Library` configuration starts a static server on port 4173 and opens the landing page with the debugger attached. Breakpoints in `docs/assets/site.js` bind to the served file. Edge is the default; a Chrome configuration is available for installations with Chrome.
-Nothing is installed and nothing in this repository serves the site — the task is a stock `python3 -m http.server` over `docs/`. Any equivalent works:
+The task serves `docs/` with `python3 -m http.server`, without installing dependencies or using repository server code. An equivalent static server also works:
```
python3 -m http.server --directory docs 4173
npx serve docs
```
-If you install the recommended [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) extension you can skip all of that: click the preview button on any page under `docs/`, or run **Live Preview: Show Debug Preview** for breakpoints. `.vscode/settings.json` already points its server root at `docs/`.
+Alternatively, install the recommended [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) extension and click the preview button on a page under `docs/`, or run **Live Preview: Show Debug Preview** for breakpoints. `.vscode/settings.json` sets the server root to `docs/`.
-**Run Task** carries the rest:
+**Run Task** provides these tasks:
-| Task | What it does |
+| Task | Action |
|---|---|
-| `site: serve` / `site: stop` | The server F5 uses, on its own |
-| `analysis 2026-08: verify` | Recompute every figure and extract from its published source |
-| `analysis 2026-08: regenerate` | Run every generator; a file that differs afterwards was hand-edited |
+| `site: serve` / `site: stop` | Start or stop the F5 server without the debugger |
+| `analysis 2026-08: prepare sources` | Explicitly fetch or repair the pinned public AWS cache and check committed examples |
+| `analysis 2026-08: verify` | Check locked inputs, then recompute every figure and extract offline; never fetch inputs |
+| `analysis 2026-08: regenerate` | Check locked inputs, then run every generator in dependency order; never fetch inputs |
-Opening a page from the filesystem does not work: every index renders its list from a JSON registry, and a browser blocks `fetch` on a `file://` origin. The pages say so when it happens rather than appearing empty.
+For the August analysis, run **prepare sources** once before **verify** or **regenerate**, and again if the public cache is missing, corrupt, or its pin changes. Preparation is not an automatic task dependency, so verification cannot silently access the network. No personal corpus folder or source-repository Actions variables are needed.
+
+The [source lock](docs/analysis/2026-08-automating-technical-hardening-guidance/tools/source-lock.json) defines 6 committed IBM and 18 committed Easy Dynamics JSON inputs plus 231 public AWS JSON files pinned to revision `4a1779ffb556c4ab8fb3dad94a19d4d198116803`. Committed examples are authoritative, checked against the size and SHA-256 fingerprints in [data/examples.json](docs/analysis/2026-08-automating-technical-hardening-guidance/data/examples.json). Explicit preparation authenticates the AWS archive against the lock before caching it; subsequent source checks use that verified cache offline. Missing or corrupt inputs fail rather than becoming empty counts or skipped checks. Changing an input pin is an explicit tracked change requiring updates to affected provenance, link indexes and generated outputs. See the [analysis verification instructions](docs/analysis/2026-08-automating-technical-hardening-guidance/README.md#verifying-it) for the exact fetch/check commands and cache location. These are build-time inputs, not new browser downloads; Pages publication is unchanged.
+
+The library index pages require a server to load lists from JSON registries: browsers block `fetch` on a `file://` origin. Affected pages display a message rather than an empty list.
+
+The “Work in progress” bar appears only within active analyses without a recorded decision. Each analysis's `analysis.json` controls visibility: `status` must be `active`, with no `concluded`, `recommendation`, `decision`, `decided`, or `supersededBy` value. A missing decision does not imply that an analysis will issue a recommendation. Library landing pages and indexes carry no banner.
+
+Closing the bar hides the notice across pages of that analysis for the browser tab's session, without affecting other analyses. With JavaScript disabled or status unavailable, the notice stays hidden. Folder-based copies read analysis status from the generated bundle.
+
+Banner regression checks: `node docs/analysis/2026-08-automating-technical-hardening-guidance/tools/bannercheck.js`.
## Contributing
-Contributions of high-quality OSCAL examples are welcome. Please ensure examples are realistic, well-structured, and follow OSCAL best practices.
+Contribute OSCAL examples grounded in implementation practice, organized by model, and following OSCAL best practices.
## License
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/.gitignore b/docs/analysis/2026-08-automating-technical-hardening-guidance/.gitignore
index 0083927..692f23f 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/.gitignore
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/.gitignore
@@ -1,6 +1,8 @@
__pycache__/
*.pyc
build/
+node_modules/
+/.cache/oscal-sources/
# The OSCAL corpora and the CIS Benchmarks used to be excluded here. Both are
# committed now, on the call recorded in BUILD-LOG.md: the artifacts page names
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/BUILD-LOG.md b/docs/analysis/2026-08-automating-technical-hardening-guidance/BUILD-LOG.md
index 441884d..6d3bd91 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/BUILD-LOG.md
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/BUILD-LOG.md
@@ -1,9 +1,22 @@
# Build log
-Append-only. Each session records what it did and every decision it had to make.
+Dated record. Each session records what it did and every decision it had to make.
Gate decisions from Pirooz go in their own headed section and are binding on
subsequent sessions.
+**Maintenance note, 2026-09-09:** Historical entries have been edited to remove
+unsupported traceability claims; Git history is unchanged. The 15 criteria and
+open questions are maintained as analysis content and verified structurally.
+The snippet manifest now contains 32 JSON-only extracts from published OSCAL
+examples resolved through the repository's source lock. Historical check totals below
+describe earlier versions of the harness, not current strict verification.
+The four assessment-plan schema defects recorded here until 2026-09-10 (missing
+associated-activity `subjects` in Maester and ScubaGear, activity-title line
+breaks in Windows Server 2019 and 2022) were repaired in the committed examples
+on that date; see the final entry. CI uses the committed example files and a
+hash-verified public AWS archive pinned in `tools/source-lock.json`; no personal
+corpus folder or source-repository variables are required.
+
---
## Phase 1: the data layer
@@ -21,7 +34,7 @@ tools/extract.py RFC 6901 resolution, trim, max_prose, provenance
tools/verify.py 4 phases implemented, 8 registered for later
data/snippets/ 27 files
data/schema-evidence/ 5 files
-data/{six questions,criteria,views,glossary,quotes,corpus-stats,provenance}.json
+data/{six questions,criteria,views,glossary,corpus-stats,provenance}.json
```
### Extraction summary
@@ -77,11 +90,8 @@ Every figure quoted in the plan recomputed exactly. Nothing had to be corrected.
definitions were small enough to embed whole, so no `fragment_note` was
needed and no reader has to trust an elision.
-7. **`corpus-stats.json` separates computed figures from cited ones.** The
- 304 / 563 / 867 numbers are NOT computed from the corpora. They come from an
- Easy Dynamics position paper and are held in a separate
- `cited_from_position_paper` block with an explicit attribution requirement,
- so a later phase cannot accidentally render them as measurements.
+7. **Figures require a reproducible derivation.** Scale claims that cannot be
+ recomputed from the published OSCAL examples are not evidence for this analysis.
8. **`views.json` records the claim the site does not make.** Alongside the
automation argument it carries a `claim_not_made` field stating that the site
@@ -105,7 +115,7 @@ Every figure quoted in the plan recomputed exactly. Nothing had to be corrected.
### Open for Gate 1
-Nothing blocking. Four items worth your eye, in the order they matter:
+Three items for review, in the order they matter:
1. **`data/six-questions.json` fill matrix.** Twenty-four cells, and they are the
site's central claim set. The empty cells carry the most weight: check that
@@ -113,13 +123,9 @@ Nothing blocking. Four items worth your eye, in the order they matter:
states, especially catalog-first slot 2 (`empty-not-asserted`, on Fritz's
stated reason) and assessment-first slot 6a (`empty-by-design`, on the
proponents' own claim).
-2. **`data/quotes.json`.** 37 quotations. Every attribution is from the
- pre-read, which itself notes that transcriber speaker labels were normalized
- and may contain errors. You know these people; correct anything wrong now
- rather than after it is on nine pages.
-3. **`data/criteria.json`.** Fifteen rows against Section 6 of the pre-read.
- Verbatim question text, correct attributions, no sixteenth.
-4. **Three snippets at random** against their source files, to confirm no trim
+2. **`data/criteria.json`.** Fifteen criteria maintained as analysis content;
+ review wording and mappings as well as structural checks.
+3. **Three snippets at random** against their source files, to confirm no trim
changed a meaning.
---
@@ -146,8 +152,8 @@ counts become visible to a reader.
```
assets/site.css 8 sections, tokens through reduced-motion
-assets/highlight.js JSON and Markdown highlighter, ~130 lines
-assets/site.js theme, data cache, snippets, quotes, strips,
+assets/highlight.js syntax highlighter, ~130 lines
+assets/site.js theme, data cache, snippets, strips,
glossary cards, tabs, matrix toggles
assets/shell.html documented page template
assets/kitchen-sink.html every component, both themes, not published
@@ -203,8 +209,8 @@ The spec called for vendoring Prism locally. Prism could not be retrieved as
text through the tooling available in this session, and fetching it by other
means is out of scope. Adding a CDN reference is forbidden by the same spec.
-`assets/highlight.js` replaces it: about 130 lines covering the only two
-languages the site shows, JSON and Markdown. Everything is HTML-escaped on the
+`assets/highlight.js` replaces it: about 130 lines for syntax highlighting.
+The extract manifest now contains JSON only. Everything is HTML-escaped on the
way out. For this site the trade is favourable, since there is no supply chain
to keep patched and the whole file can be audited in one sitting. It also does
one thing Prism would not have: it renders the extractor's ` [truncated]`
@@ -538,8 +544,6 @@ assertion that the three are equally light.
thesis. The words are on the figure already; do not drop them from the page.
- 7.8's three destination labels are fixed by the plan and must be used verbatim
in the buttons. `79-scale.js` documents the exact markup.
-- The 304 / 563 / 867 figures are cited, not computed. They carry their
- attribution on the figure; any page that repeats them must repeat it too.
- Nothing in `assets/diagrams/` may be hand-edited. Change `tools/diagrams.py`
and re-run.
@@ -592,7 +596,7 @@ page checks.
### What was built
```
-six-questions.html nine parts, 17 quotations, 67 snippets, 9 schema
+six-questions.html nine parts, 67 snippets, 9 schema
fragments, 8 tables, 3 figures
glossary.html 33 terms, filterable, one anchor each
assets/site.js twelve data components, plus a schema-evidence renderer
@@ -600,7 +604,7 @@ assets/site.css .state-swatch, .slot-fill, .worked, .filter-bar,
.glossary, .toc
tools/pagecheck.js a DOM harness that runs a page and inspects the result
tools/verify.py --quotes and --pages implemented
-data/glossary.json one term added, one quotation wired
+data/glossary.json one term added
```
### The pages are markup plus data, not generated HTML
@@ -615,7 +619,7 @@ is the only way to keep its literals honest. A page is a document: if the fill
matrix were baked into HTML, correcting one cell in `six-questions.json` would leave
the page stale until someone remembered to rebuild it. So the repeating,
data-bearing parts of a page render at load time from `data/`, exactly as
-snippets and quotations already did.
+snippets already did.
Twelve components were added for this: the three views, the automation evidence,
the working definition, the binding times, the cost of an empty tie, one slot's
@@ -673,22 +677,17 @@ are recorded below because a harness that lies is worse than no harness.
was to add it rather than to drop the references: `actor` is the site's own
name for slot 5, and the reason it is the site's own name rather than an
OSCAL one is exactly the thing evidence register item 8 records as
- unestablished. Added with status not-established, the four constructs in use
- as its other usages, and the same quotation the other three carry.
+ unestablished. Added with status not-established and the four constructs in
+ use as its other usages.
4. **Heading levels skipped.** The three views rendered as `h4` directly under
an `h2`, and the slot 6 fills rendered as `h4` under the `h4` that introduces
6a. Both are invisible in a visual review and both break heading navigation.
Fixed, and `pagecheck.js` now asserts that heading levels never skip.
-5. **`validation component` carried both senses but quoted neither.** The IBM
- sense has a normative statement in `quotes.json`; the AWS sense does not, and
- inventing one would have meant hand-typing a quotation, which the standing
- rules forbid. Wired the entry to the IBM quotation, and left the AWS sense
- carried by its `other_usages` entry, whose `who` field already names
- `docs/COMPONENTS.md` and records that it is listed under Future
- Considerations and not shipped. If an AWS quotation on this point is wanted,
- it has to go through `quotes.json` first.
+5. **`validation component` needs its senses kept distinct.** A proposed
+ construct and a shipped assembly are not interchangeable. The glossary must
+ identify which meaning the published OSCAL examples actually demonstrate.
### Two fidelity fixes to the harness itself
@@ -705,9 +704,8 @@ every diagram appeared to fail to load. Added.
1. **The section 2 diagnosis is one paragraph of 109 words**, and it is written
as an observation with its evidence in front of it rather than as a claim
- being defended. The two facts are quoted first, from the pre-read and from
- `views.json`; the paragraph only states what follows from them; and the
- testable consequence is put as a question for the Open questions page rather
+ being defended. The paragraph distinguishes the views recorded in
+ `views.json`; the testable consequence is put as an editorial open question rather
than as a conclusion. This is the most opinion-adjacent content on the site
and it is the thing to read twice at the gate.
2. **The automation claim is the weaker one everywhere.** The page states
@@ -723,8 +721,7 @@ every diagram appeared to fail to load. Added.
`pagecheck.js` asserts both sentences are present.
4. **The worked side-by-side in slot 6 has an empty left column**, because no
system security plan exists in any of the three corpora. That is the finding
- rather than an accident of extraction, and the column says so and quotes the
- pre-read reaching the same conclusion from the meeting record. The right
+ rather than an accident of extraction, and the column says so. The right
column is the one assessment result that does exist, with its publisher's own
proposed-schema status stated.
5. **Slots 2 and 6 appear twice, and the second time adds only new material.**
@@ -743,20 +740,15 @@ every diagram appeared to fail to load. Added.
### Verification added
-`--quotes`, 53 checks: quotes.json integrity, including that no quotation
-appears twice under two ids; every blockquote on every page carries a
-`data-quote` id that resolves and carries no hand-written text; every quotation
-reference in every data file resolves; and the two page-hygiene rules above. It
-also prints the quotations not yet used by any page, which is the number that
-tells you whether one was dropped. Twenty-one are unused, all belonging to pages
-not yet built.
+The page-hygiene checks cover hand-typed code blocks and long dashes. The
+current `--quotes` policy prohibits quotation and attribution hooks on pages.
`--pages` shells out to `tools/pagecheck.js` and reports its result.
```
[snippets] 12 [schema] 15 [stats] 20 [data] 18
[css] 62 [a11y] 46 [diagrams] 312
-[quotes] 53 [pages] 1 (384 page checks behind it)
+[pages] 1 (384 page checks behind it)
539/539 checks passed
```
@@ -774,16 +766,16 @@ not yet built.
`pagecheck.js` fails on a hook that `boot()` does not wire.
- Corpus figures go in with ``, never typed. Schema
fragments go in with `data-schema`, never `data-snippet`.
-- The approach pages must state which of the three views their proponents hold,
- in their words. `views.json` carries the quotation id for each.
+- The approach pages must state which reading of a rule each structure uses,
+ distinguishing analysis from the evidence in published OSCAL examples.
- Every first use of a contested term should be a
``, which pulls the card from the same
`glossary.json` the glossary page renders.
### Open for Gate 4
-1. **The section 2 diagnosis, read cold.** One paragraph, 109 words, after the
- two quotations that support it. Does it read as an observation or as an
+1. **The section 2 diagnosis, read cold.** One paragraph, 109 words.
+ Does it read as an observation or as an
argument? If the latter, the fallback in the plan is to state the three views
without the diagnosis and let readers draw it.
2. **The mapping-collection section.** It now says three things and explicitly
@@ -825,7 +817,7 @@ them 465 page checks, up from 384.
### What was built
```
-primer.html eight sections, 1 quotation, 3 snippets, 2 tables,
+primer.html eight sections, 3 snippets, 2 tables,
3 figures, 1,911 words of prose
assets/site.js renderModels, renderReaders, renderCitedFigures,
renderSc28; term cards rebuilt on delegation
@@ -850,8 +842,7 @@ so that the human review can spend itself on the part it cannot delegate.
sentence runs past 40.
The prose measurement excludes navigation, the table of contents, tables, inline
-SVG, snippet bodies and quotations. Tables hold labels rather than sentences, and
-a quotation is someone else's sentence which the site may not shorten. Measured
+SVG and snippet bodies. Tables hold labels rather than sentences. Measured
that way the primer is 1,911 words, average sentence 17.7, reading grade 9.3.
The six-questions page is 15.6 and 10.2, the glossary 16.3 and 11.3.
@@ -859,9 +850,9 @@ Two of those checks failed on the first run and both were right to. The gist had
a 35-word sentence and the slot 2 cross-reference had a 57-word one. Both were
split.
-### Four things render from data rather than being written
+### Content renders from data rather than being written
-Same principle as phase 4, applied to the four places on this page where the
+Same principle as phase 4, applied to places on this page where the
primer would otherwise restate something that already exists.
1. **The seven models.** Each one line of purpose is the glossary's own text,
@@ -871,12 +862,7 @@ primer would otherwise restate something that already exists.
glossary cannot drift apart, in either direction.
2. **The three readers.** Same, from the `publisher`, `implementer` and
`assessor` entries.
-3. **The cited figures.** 304, 563 and 867 render together with their
- attribution as one unit, because editorial rule 10 requires the attribution
- at every appearance and rendering them separately is what makes separating
- them possible. The component also states that they are not computed from the
- files, which is the distinction `corpus-stats.json` was built to preserve.
-4. **The running example.** The three-row SC-28 table reads every identifier out
+3. **The running example.** The three-row SC-28 table reads every identifier out
of the snippet that row names. `V-270747` and its `sc-28`, `sc-28.1`,
`sc-28.3`; `CloudTrail.2` and its absence of any framework control;
`cos_encryption_hyperprotect_key_configured` and its `sc-28`. Nothing in the
@@ -906,9 +892,8 @@ where the matrix and the slot fills create content after boot.
not repeated here, per the brief. The primer's job is to tell a reader the
disagreement exists, because it changes how they read everything after it.
3. **The AWS row of the running example is stated as a property of the shipped
- content**, at the time it was published, with Fritz Kunstler's own
- explanation quoted rather than characterised, and a link to slot 2 for why an
- empty tie is a position rather than an omission. The callout says plainly
+ content**, at the time it was published, with a link to slot 2 for the
+ distinction between an empty tie and a deficiency. The callout says plainly
that a rendering which scored it as a deficiency would be making an argument.
4. **"77 groups, one group per service"** rather than the plan's "77 services".
`corpus-stats.json` counts groups, and the AWS catalog groups are per
@@ -923,13 +908,13 @@ where the matrix and the slot fills create content after boot.
### Verification added
-`--quotes` grew from 53 to 59 checks with the new page. `--pages` now runs 465
+`--pages` now runs 465
checks, of which 82 are the primer's.
```
[snippets] 12 [schema] 15 [stats] 20 [data] 18
[css] 62 [a11y] 46 [diagrams] 312
-[quotes] 59 [pages] 1 (465 page checks behind it)
+[pages] 1 (465 page checks behind it)
545/545 checks passed
```
@@ -942,8 +927,6 @@ checks, of which 82 are the primer's.
is the wrong shape for a single-approach page. A per-approach equivalent will
be needed, and it should be one function over the eight slot rows so that the
three pages cannot diverge in structure.
-- Twenty-one quotations are still unused, and most belong to the approach pages
- and the open questions page. `--quotes` prints the list on every run.
- Cross-page anchors are still unchecked. The list of anchors later pages owe is
in the phase 4 notes, and `questions.html#evidence-8` now has a second caller.
@@ -991,7 +974,7 @@ Both are withdrawn.
reader, a practitioner who knows OSCAL but has not followed this argument
reads the site and restates the disagreement.
- **Everything else in the plan stands**, including all thirteen editorial rules,
- the six-slot spine, the fifteen criteria verbatim, and equal budget by
+ the six-slot spine, the fifteen criteria, and equal budget by
construction.
### 2. The house style, as it now stands
@@ -1010,7 +993,7 @@ exist.
| Name the constraint, then its consequence | Building to a consequence across a paragraph |
Retained from earlier phases and unaffected: no long dash anywhere; every
-quotation from `data/quotes.json` by id; every snippet from `data/snippets/`;
+snippet from `data/snippets/`;
schema fragments labelled separately from corpus content; no recommendation.
The boxed summary at the top of each page **stays**, and is now written in OSCAL
@@ -1172,33 +1155,19 @@ Three decisions, taken together:
1. **No quotations anywhere.** Every blockquote comes off every page. The
In their words section is deleted from the approach template.
2. **No personal names and no proponent organizations.** Structural names and
- option letters only. Option letters stay so that this site and the pre-read
- remain cross-referenceable.
+ option letters identify the approaches consistently across the analysis.
3. **The three empty slot states survive.** Where a state depends on a reason
- someone stated, the site states the reason in its own words and cites the
- document, without naming the speaker.
+ rather than published content, the site identifies that reason as analysis
+ rather than presenting it as a source-backed fact.
**This supersedes plan editorial rules 1, 3, 10 and 11 in part.** Rule 1's
"option letter and organization second" loses the organization. Rule 3's "a
proponent's own words" is withdrawn, leaving the other half: every
-characterization traces to a JSON pointer into a shipped file, or to a cited
-source document. Rule 10's advocacy marking survives but names the document
-rather than the organization behind it. Rule 11's settled items keep their
-marking and lose their attribution. **Rule 4 is unaffected and still binding:
-the site authors no criteria.**
-
-### What is kept, and why
-
-`data/quotes.json` is **retained with all 39 quotations**, and so are the
-`advocate` fields in `views.json` and the `raised_by` fields in `criteria.json`.
-Deleting them would destroy the record of what was said and where, which a later
-session may need and which nobody asked to lose. Each of those three files now
-carries a note saying in terms that the fields are retained and **not rendered**,
-so that a later session does not read their presence as permission to display
-them. `verify.py --quotes` asserts the note is there.
-
-`quotes.json` also earns its keep operationally: it is where the list of eight
-names that must not appear on any page comes from.
+characterization of published content traces to a JSON pointer into a shipped
+OSCAL file. Editorial interpretation is not source evidence. Rule 11's settled
+items keep their marking and lose their attribution. **The current criteria
+policy is the maintenance note above: 15 criteria maintained as analysis content,
+with structural verification rather than source-wording checks.**
---
@@ -1232,27 +1201,18 @@ questions-raised box on all three pages, which pushed the pair out of the
15 per cent tolerance, so the case box was trimmed to match rather than the
questions box padded back out.
-### What replaced each quotation
-
-Not deletion. Every claim a quotation carried is still made, in the site's own
-words, with the source document cited. The load-bearing ones:
-
-- **Slot 2, catalog-first.** The mapping props were removed before publication,
- pending a decision by this group, recorded in the working group pre-read. That
- is what keeps the cell at deliberately-not-asserted rather than absent, which
- is the distinction the whole slot 2 treatment rests on.
-- **Rule and check are separate.** The reason recorded in the pre-read is schema
- flexibility rather than semantics: one rule can be associated with a check
- identifier in Ansible, in Terraform, in OPA and in OpenSCAP.
-- **Criterion 3.** Requirement level is absent from OSCAL entirely, an
- orthogonal gap affecting every option. Rendered as a callout citing the
- pre-read's section 7.
-- **Evidence register item 8.** The question was to be posted to the NIST OSCAL
- team on 17 July, it is not established whether it was posted, and no response
- is in the record.
-- **The 6a and 6b distinction.** A system security plan captures how a control
- is satisfied; desired-state benchmarks are pass or fail. Attributed to a
- position paper submitted to the group and marked as advocacy.
+### Technical distinctions retained
+
+- **Catalog-first control links.** No mapping document is published in the
+ corpus; an available mechanism and a shipped artifact are different claims.
+- **Rule and check are separate.** One rule can be associated with check
+ identifiers in Ansible, Terraform, OPA and OpenSCAP; identity and execution
+ convention need not be the same thing.
+- **Criterion 3.** Requirement level has no dedicated core OSCAL field.
+ Namespaced properties in published examples do not make it a core field.
+- **The 6a and 6b distinction.** A system security plan records an implementation
+ claim; assessment results record observations and findings. Neither alone
+ demonstrates a complete lifecycle.
### The rule is enforced, not remembered
@@ -1261,8 +1221,7 @@ sessions:
- **`verify.py --quotes` inverted.** The flag keeps its name because the subject
is the same; the answer changed. No page may carry a blockquote or a
- `data-quote` reference, and no page may contain any of the eight names in
- `quotes.json`.
+ `data-quote` reference, and no page may present personal attribution.
- **`pagecheck.js` checks the rendered prose**, which is where a name could
arrive from a data file rather than from markup. It also checks proponent
organizations, which `verify.py` cannot: a snippet's source path legitimately
@@ -1287,16 +1246,10 @@ is provenance is what makes it possible to be strict about everything else.
2. **The three views table lost its On the record column.** The three readings
keep their definition, their implied layer and their implied model, which is
what makes them comparable. Who holds each one is no longer shown.
-3. **A criterion no longer says who raised it.** This is the sharpest conflict
- with the plan, whose rule 4 asks for the fifteen criteria "with their
- attributions shown". The criteria themselves are still verbatim and still
- unauthored, which is what rule 4 is for. The attributions remain in
- `criteria.json`. Flag this at the gate if the attribution mattered more than
- I have judged.
-4. **The cited figures name the document, not the organization.** 304, 563 and
- 867 still travel with their attribution as one unit, and are still marked as
- advocacy rather than measurement. The wording is now "a position paper
- submitted to the working group".
+3. **A criterion no longer says who raised it.** The criteria are now maintained
+ as analysis content; editorial review must assess their wording and fairness.
+4. **Unreproducible scale claims are not evidence.** Figures need a derivation
+ from published OSCAL examples before they can support the comparison.
5. **The glossary's who-uses-this fields were rewritten** to name the approach
rather than the person or organization, for example "Catalog-first, Option A"
in place of a person and an employer. The contested terms still show every
@@ -1307,8 +1260,8 @@ is provenance is what makes it possible to be strict about everything else.
1. **Read a slot with an empty state.** Slot 2 on the catalog-first page is the
one to read. Without the publisher's own words, does the reason still land as
a stated decision rather than as the site's inference?
-2. **Criterion attribution.** Point 3 above is a conflict I resolved against the
- plan's letter. Say if it should go back.
+2. **Criterion wording.** Check that each criterion fairly addresses all three
+ approaches without implying a preferred answer.
3. **The case boxes in section 7.** They were re-cut to hold the budget after
the names came out. Confirm none of the three lost something it needed.
4. **Two gates still open:** whether the plan document should be amended to
@@ -1338,21 +1291,20 @@ repeats. A page supplies only what has to differ: the gist, the per-slot prose,
the strongest case, the hardest questions, and the specifics that go into the
three status sentences.
-The generator refuses to write a page that breaks the budget. Five assertions
+The generator refuses to write a page that breaks the budget. Assertions
run before any file is opened:
- the gist is 75 to 85 words
- the two boxes in section 8 are within 15 per cent of each other
- the three page totals are within 10 per cent
-- no quotation appears twice on one page
-- no comparative language appears anywhere outside a quotation
+- no comparative language appears in the authored prose
-Four of the five fired during the build and each one was fixed by cutting the
+Budget failures during the build were fixed by cutting the
longer text, never by padding the shorter.
### Final word counts, prose only
-Snippets and quotations render from `data/` at load time, so the static markup
+Snippets render from `data/` at load time, so the static markup
holds exactly the authored prose. That is what is counted.
| Page | Words | Against the mean |
@@ -1362,8 +1314,8 @@ holds exactly the authored prose. That is what is counted.
| `component-first.html` | 2,126 | +2.8% |
Spread between the longest and the shortest is **6.3 per cent**, inside the ten
-per cent the brief allows. Every page carries five quotations in the fixed
-positions, six slot subsections, one layer-map variant, one slot strip and the
+per cent the brief allows. Every page carries
+six slot subsections, one layer-map variant, one slot strip and the
same three status sentences.
Catalog-first is the shortest, and the reason is structural rather than
@@ -1381,34 +1333,18 @@ not visible. The generator rejects `unlike`, `whereas`, `better than`,
`inferior` and their neighbours, and `tools/pagecheck.js` re-checks the rendered
pages.
-**Quotations are exempt.** A participant may compare, and the site may not
-paraphrase them into not comparing. The check skips `.quote` elements.
-
One phrase needed rewriting under this rule. The component-first page had said
that IBM ships the only assessment result in the three corpora. It now reads
that this is the corpus on this site that contains an assessment result, which
is the permitted form of factual uniqueness.
-### Two data additions, both to keep counts out of the prose
+### Data additions to keep counts out of the prose
**Five counts** were missing from `corpus-stats.json` and would otherwise have
been typed into the artifact inventories: `aws_catalog_files`, `ez_files`,
`ibm_cdef_files`, `ibm_ap_files`, `ibm_ar_files`. All five are now recomputed
from the corpora by `verify.py --stats`.
-**Two quotations** were added to `quotes.json`, because the brief requires both
-verbatim and nothing may be quoted from outside that file:
-
-- `aws-docs-future-considerations`, the whole Future Considerations section of
- AWS's `docs/COMPONENTS.md`, 185 words. This is where AWS's own sense of a
- validation component appears, a component enumerating the frameworks a service
- has been validated against, listed as a future expansion and not shipped. An
- earlier draft of the plan conflated that sense with IBM's. Quoting it whole is
- what stops the conflation recurring.
-- `ibm-open-questions`, IBM's four self-identified open questions from
- `component-rules.md`, verbatim including the typographic errors in the source.
- All four concern slots 4 and 5.
-
### The status annotation is data, not markup
Plan section 7 requires the three status annotations to be applied
@@ -1420,25 +1356,15 @@ is now a failing check rather than an oversight.
### Decisions made during the build
-1. **Section 3's quotation comes from `views.json`, with one fallback rule.**
- Where the view's canonical quotation is already carried by a slot on the same
- page, the view's supporting quotation is used instead. This fired once:
- Pranav Kothare's statement is both the canonical statement of the procedure
- reading and, per the brief, the required evidence at slot 6a on the
- assessment-first page. The rule is applied identically to all three pages
- rather than special-cased.
-2. **The lead-in to section 3 is a neutral label**, "On the record", because the
- speaker differs legitimately between pages and the quotation's own footer
- carries the attribution.
-3. **Extra blocks attach to the slot they concern.** The first draft had a fixed
+1. **Extra blocks attach to the slot they concern.** The first draft had a fixed
"slot 6 extra" slot, which put the catalog-first callout about the empty
control tie underneath slot 6 instead of slot 2. Extras are now keyed by slot
number, so each page attaches its block where it belongs: assessment-first at
3 and 6, catalog-first at 2 and 3, component-first at 3 and 6. Two each.
-4. **`rule-groups` is named as specification-only in prose**, with an explicit
+2. **`rule-groups` is named as specification-only in prose**, with an explicit
statement that there is no snippet because there is no content, so no reader
goes looking for one.
-5. **Repository links are rendered where one exists** and their absence is
+3. **Repository links are rendered where one exists** and their absence is
stated in the same sentence on the two pages that lack one. Only the AWS
content has a public repository on the record.
@@ -1447,27 +1373,25 @@ is now a failing check rather than an oversight.
`--pages` grew by 45 checks, all in a new `checkApproach`:
- the nine template sections, in order, with the exact heading text
-- exactly three quotations in section 2, one in section 3, one in section 4
- six slot subsections
- every snippet carries this approach's status annotation
- section 8 has two boxes and they are within 15 per cent
- section 9 uses the three shared frames
-- no comparative language outside a quotation
+- no comparative language in authored prose
- the alphabetical ordering is stated on the page
- the page carries its own layer-map variant and its own slot strip
-- no quotation appears twice
```
[snippets] 12 [schema] 15 [stats] 25 [data] 18
[css] 62 [a11y] 46 [diagrams] 312
-[quotes] 169 [pages] 1 (656 page checks behind it)
+[pages] 1 (656 page checks behind it)
660/660 checks passed
```
### Open for Gate 7
1. **Read your own page first.** Proponent review is the strongest neutrality
- instrument available and the pre-read has already set the norm: correct
+ instrument available: correct
anything about your approach that is wrong. The section to read hardest is
8.1, which is written as the advocates would write it and is therefore the
place where putting words in someone's mouth is easiest.
@@ -1475,9 +1399,8 @@ is now a failing check rather than an oversight.
Catalog-first is shortest because four of its slots are empty and an empty
slot takes fewer words to describe honestly. Say if that reads as short
measure rather than as an accurate account.
-3. **The two new quotations.** Both are long and both are load-bearing. Check
- `aws-docs-future-considerations` against the source, since it is the one that
- exists to prevent a conflation the plan made once already.
+3. **Proposed versus shipped constructs.** Confirm the examples support the
+ distinction rather than treating a planned feature as published content.
4. **Section 9 on all three pages.** The three sentences are the same frames
with different specifics, which is the rule. Read them side by side and
confirm none of the three reads as a criticism where the others read as a
@@ -1530,51 +1453,26 @@ it stops at section 7 rather than summing up, because a summary of a comparison
is a recommendation wearing a different hat. Both of those are now assertions in
`tools/pagecheck.js` rather than intentions.
-### The one thing this page can do that the pre-read cannot
+### What the published OSCAL files establish
-The pre-read's section 7 fills fifteen criteria by five options from the meeting
-record. This page fills the same criteria from the published files. That is the
-whole reason section 2 exists, and it only earns its place where the two
-readings differ.
+The comparison answered fifteen analysis criteria from the published files.
+For requirement level, the three CISA assessment plans carry a `criticality`
+prop in the `http://cisa.gov/ns/oscal` namespace, valued `SHALL` or `SHOULD`,
+on every step: 73 and 55 respectively in each of the three files. This is a
+namespaced property, not a dedicated field in the core schema.
-They differ in eight of the forty-five cells, and in every one of the eight a
-file answers something the record recorded as unanswered. The largest is
-criterion 3, requirement level. The pre-read's cell reads "Absent from OSCAL
-entirely. An orthogonal gap affecting every option." The three CISA assessment
-plans carry a `criticality` prop in the `http://cisa.gov/ns/oscal` namespace,
-valued `SHALL` or `SHOULD`, on every step: 73 and 55 respectively in each of the
-three files. It is a namespaced prop rather than core schema, which is criterion
-14 and is stated there, but it is shipped content and it answers the question.
+Other evidence retained its limits: the component-first observation names a
+subject typed `inventory-item`; its assessment result records no finding; all
+three approaches carry a description of what the check does. No corpus at this
+phase contained a system security plan, so SSP impact remained an open question
+rather than a measured scale claim.
-The other seven, in short:
+### Model coverage must follow the examples
-| Cell | The record | The files |
-| --- | --- | --- |
-| 2, assessment-first | Not established | `criticality` answers the must-versus-may half |
-| 8, component-first | Gap unresolved | the one observation names a subject typed `inventory-item` |
-| 10, component-first | cdef, SSP, AP, AR | the document has sections for three of those and none for the SSP |
-| 13, all three | Open | all three carry a description of what the check does |
-| 15, component-first | no assessment result | there is one, and it records no finding |
-
-Where the files are silent and the record is not, the cell hands the question
-back rather than inventing an answer. Two cells do that, both on criterion 7,
-SSP impact, where the figures on the record come from a position paper and no
-corpus contains a system security plan to check them against.
-
-### A claim on component-first.html that rested on a removed quotation
-
-Phase 6b took the quotations out. Section 6 of component-first.html said the
-proposal touches four models and cited its authors as stating the schema change
-surface in those terms, which was a quotation that no longer exists. Reading
-`IBM/component-rules.md` directly: it has sections for the component definition,
-the assessment plan and the assessment result, and no section for the system
-security plan.
-
-So the written proposal covers three models and the fourth is on the record
-only. The generator, the matrix note in `six-questions.json` and criterion 10 now all
-say that. This is exactly the failure mode Gate 7 created: removing an
-attribution can quietly leave a claim with nothing behind it, and the only way
-to find those is to re-read the source.
+Component definitions, an assessment plan and an assessment result are present
+in the component-first examples. A fourth model, the system security plan, is
+not demonstrated by that corpus. Describing a proposed lifecycle is not evidence
+that all of its models have been published.
### Decisions
@@ -1599,7 +1497,7 @@ to find those is to re-read the source.
the token block.
5. **One deliberate departure from alphabetical order.** Sections 1, 2 and 3 are
alphabetical by structural name, as everywhere else. Section 4 puts the three
- join diagrams in the pre-read's option-letter order, so that no approach
+ join diagrams in option-letter order, so that no approach
leads every table on the site. The departure is stated on the page and both
halves are asserted.
6. **Organization names stripped at render time, not from the data.** A stat's
@@ -1624,18 +1522,11 @@ have passed and did not: `dataset` not writing through, the missing `DOMParser`,
### tools/verify.py --criteria
-Twenty-five checks. Fifteen criteria in the source document, fifteen in
-`criteria.json`, numbered 1 to 15 with no gap; 45 cells answering each of them
-exactly three times; three declared cell states and no fourth; every snippet a
-cell points at exists; every figure a cell cites is a recomputed stat; a cell
-claiming a fact points at a file or a counted figure; every cell carries the
-record's own answer beside it; no cell names a person or a proponent
-organization; `raised_by` kept as provenance and absent from the page.
-
-The DOM half is in `pagecheck.js`, which is the only thing here that can see
-what rendered: exactly fifteen rows, no sixteenth, columns alphabetical, each
-row carrying the pre-read's question verbatim and its record answer attributed
-to section 7.
+The comparison checked fifteen analysis criteria numbered 1 to 15, with no gap,
+and 45 cells answering each exactly three times. Evidence pointers resolved to
+existing snippets or recomputed figures. The DOM checks confirmed the table's
+row count and column order. The current `--criteria` check validates the criteria
+and their question mappings structurally; it does not establish source wording.
Six mutations were run against the finished page to confirm the checks bite. A
sixteenth criterion, a fact cell stripped of its evidence, the join diagrams
@@ -1652,9 +1543,8 @@ pagecheck.js 916/916 (was 546)
### Open for Gate 8
-1. **The eight refined cells are the page's whole argument for existing.** Each
- one says a file answers something the record did not. If any of the eight is
- wrong, the correction is more valuable than the cell. Criterion 3 in
+1. **Read the evidence-bearing cells.** If a cell mischaracterizes a file,
+ the correction is more valuable than the cell. Criterion 3 in
particular: `criticality` is a namespaced prop, not core schema, and the
question is whether that counts as OSCAL representing requirement level.
2. **The local-defintions misspelling in criterion 15.** The IBM assessment plan
@@ -1782,10 +1672,8 @@ pagecheck.js 939/939 (was 916; 23 of the new ones are the
**Recorded by Pirooz, 2026-08-14. Binding on every later session.**
-Two decisions, taken before phase 8 began, on a conflict between the build
-brief and the Gate 7 decision. The brief for this phase asked for the evidence
-register with its requesters, and for three blocks verbatim. Gate 7 had removed
-every quotation and every personal name from the site.
+Two decisions, taken before phase 8 began. Gate 7's no-quotation and
+no-personal-attribution policy continues to apply to the open questions.
### 1. Gate 7 holds. The register is deidentified
@@ -1794,13 +1682,11 @@ requester column names the occasion rather than the person: *agreed by the
group, 20 March*, *requested 19 June*. Nothing on the site names anybody, and
the existing name check stands unchanged with no exemption for this page.
-### 2. Verbatim comes from files where a file exists
+### 2. Extracts and editorial questions are different content types
-Anything reproduced verbatim that lives in a published corpus file is extracted
-through `tools/extract.py` and rendered as a provenanced snippet, not as a
-quotation. Anything that exists only as a transcript in the pre-read is restated
-in the site's own words with the document cited. No blockquote returns to the
-site.
+Published OSCAL JSON is extracted through `tools/extract.py` and rendered as a
+snippet with provenance. Criteria and open questions are maintained as analysis
+content, not reproductions. No blockquote returns to the site.
---
@@ -1819,41 +1705,23 @@ behind them 1,182 page checks, up from 939.
questions.html nine sections, 1,247 words of prose in markup
data-quality.html five sections, 566 words, twelve items
index.html seven sections, 1,257 words, no concluding paragraph
-data/questions.json the register, three framed questions, four sources
+data/questions.json the register and framed questions
data/data-quality.json twelve items, four per approach, every denominator
data/six-questions.json one_line per approach; other_options for D and E
data/corpus-stats.json 31 figures added, 69 total, all recomputed
assets/site.js eighteen renderers added
assets/site.css .register, .two-up, .dq, .orientation, .position-group
-tools/extract.py markdown section slicing
tools/verify.py --questions, --appendix and --links implemented
tools/pagecheck.js checkQuestions, checkAppendix, checkIndex
```
-### The two source documents are now read by the build
-
-This is the phase's most useful addition and it is what makes the word
-"verbatim" mean something on this site.
-
-`questions.html` reproduces two Word documents: the pre-read's evidence register
-and the position paper's ten open questions. Until now, prose reproduced from a
-source document was checked structurally and trusted textually. `criteria.json`
-has fifteen entries and the checks confirm there are fifteen; nothing confirmed
-that the fifteenth still said what the document said.
+### Structural verification of analysis content
-`verify.py --questions` now opens both `.docx` files and asserts that every
-string the data file marks verbatim occurs in the document it names. A `.docx`
-is a zip with one XML body part, so this needs no dependency: forty lines of
-standard library. Rewording a register item, tidying a question's punctuation or
-dropping one from the ten each turn a named check red.
-
-Three of the eleven register items cannot be verbatim, because the pre-read's
-wording names a person or an organization in the evidence column itself. Those
-three are marked `verbatim: false`, each carries a `deidentified` field stating
-what was substituted, and the check asserts the converse too: an item that is
-not verbatim must declare why, and must genuinely not occur in the source. So
-the eight-and-three split is itself checked, and quietly relabelling a
-deidentified item as verbatim fails.
+The 15 criteria and open questions are now maintained as analysis content.
+Checks cover identifiers, meaningful question text, mappings and reasoning.
+They do not establish that wording was reproduced or that another party agrees
+with the framing. Published OSCAL extracts retain their separate file-and-pointer
+provenance checks.
### Equal budget on a page made entirely of defects
@@ -1911,23 +1779,17 @@ checked.
now reads "which questions each one answers ... and what it costs to answer
the rest". This is the one place where two binding instructions were in
direct conflict and the later one won.
-2. **`extract.py` gained markdown section slicing.** The four open questions the
- component-first proposal raises against itself live in a section of a
- published markdown file, so they come out through the extractor with a
- declared heading rather than being typed. The heading is matched exactly, so
- a reworded source fails the build here rather than shipping a different
- quotation. The whole section is taken, including its closing line about the
- sample content, because a section cut short is an undeclared trim.
-3. **A snippet's markdown section is part of its address and is displayed.**
- `renderSnippet` prints `file § heading` where a section is declared, since a
- pointer of `$` against a long document tells a reader nothing.
+2. **Open questions are editorial content.** Their wording and reasoning are
+ maintained in the analysis data rather than imported as snippets.
+3. **A snippet's JSON pointer is part of its address and is displayed.**
+ A source filename alone is insufficient to locate the evidence in a document.
4. **The two sides of the mapping-item question are held within fifteen per cent
by a check**, the same tolerance the approach pages use for their two boxes,
and are laid out in two columns of equal width. Length is the argument in
that one place on the site: a case at 300 words against a counter-argument at
80 is a recommendation whatever the words say. Currently 145 against 129.
-5. **The evidence register's state chip drops a duplicate lead-in.** Several of
- the pre-read's statuses are the state and nothing more, so the chip and the
+5. **The evidence register's state chip drops a duplicate lead-in.** Several
+ status descriptions are the state and nothing more, so the chip and the
text printed the same words twice. The chip stays, because it is what carries
the state to a reader scanning the column, and the duplicated lead-in is
dropped from the text.
@@ -1947,11 +1809,9 @@ checked.
within ten per cent of each other**, 37, 36 and 39 words. A card is the most
quotable thing on the site and the shortest, which makes it the easiest place
to be unfair by a clause.
-9. **`item 4` of the register keeps the pre-read's status and adds a
- refinement.** The record says no assessment result exists from anyone; a file
- says one does, and that it records no finding. Rather than overwrite the
- record's answer, the item carries both, in the same shape `compare.html` uses
- for the eight cells where the files answer what the record left open.
+9. **Assessment-result evidence keeps its qualifier.** The published
+ component-first assessment result exists and records no finding. Presence of
+ that file does not demonstrate a complete assessment lifecycle.
### Three registered checks were implemented, and one found a real defect
@@ -1971,19 +1831,17 @@ they are produced by a renderer at load time, so they are derived here from
`glossary.json` using the same rule `termAnchor()` uses. Five cross-page links
into the glossary were previously unchecked.
-### Fifteen mutations were run against the finished pages
+### Mutation checks on the finished pages
-Each turns red only the check that names it. Dropping a register item, rewording
-one, marking a deidentified one verbatim, tidying a position-paper question,
-dropping one of the ten, padding the mapping-item case, softening the
+The checks were exercised by padding the mapping-item case, softening the
distribution note, giving one approach a fifth appendix item, breaking an
appendix denominator, removing one publisher's statement, lengthening a card
summary, adding a concluding section to the index, removing the orientation's
label, breaking a cross-page anchor, and dropping the design-choice statement
from the strip caption.
-The script is not committed. It is thirteen edits and reverts against the data
-files and `index.html`, and the point of recording it here is that the checks
+The script is not committed. The point of recording the edits and reverts
+against the data files and `index.html` here is that the checks
were seen to fail rather than assumed to work.
### Totals
@@ -1994,7 +1852,7 @@ pagecheck.js 1182/1182 (was 939)
[snippets] 12 [schema] 15 [stats] 71 [data] 18
[css] 64 [a11y] 46 [diagrams] 312
-[quotes] 186 [criteria] 25 [questions] 74 [appendix] 74 [links] 108
+[appendix] 74 [links] 108
```
### Open for Gate 9
@@ -2002,10 +1860,8 @@ pagecheck.js 1182/1182 (was 939)
The remaining gates are readings a machine cannot stand in for, and the site is
now complete enough to be read end to end.
-1. **The evidence register, item by item.** It is the pre-read's list and this
- site now reproduces it for a wider audience. The three deidentified items are
- the ones to read: 5, 6 and 9. Each states what was substituted. Say if any
- substitution loses something the item needed.
+1. **The open questions, item by item.** Review their wording and reasoning for
+ fairness; structural checks cannot establish agreement with the framing.
2. **The mapping-item question, both sides.** They are the same length by
construction, which is not the same as being equally strong. Read the case
against it cold and say whether it is the argument its holders would actually
@@ -2093,7 +1949,7 @@ site open from a folder, publication metadata, and the report
tools/verify.py --slots --budget --conformance --methodology --bundle
added; --schema --links --a11y gained network halves
tools/bundle.py builds assets/bundle.js from data/
-tools/extract.py markdown sections; idempotent timestamps
+tools/extract.py idempotent timestamps
tools/axe_run.mjs serves the site and runs axe-core over every page
tools/pagecheck.js checkOffline: every page run the way a browser does
under file://
@@ -2122,9 +1978,6 @@ node tools/pagecheck.js 1280 passed, 0 failed
| `--css` | 62 | 0 | 0 |
| `--a11y` | 46 | 0 | 1 |
| `--diagrams` | 312 | 0 | 0 |
-| `--quotes` | 69 | 0 | 0 |
-| `--criteria` | 71 | 0 | 0 |
-| `--questions` | 57 | 0 | 0 |
| `--appendix` | 145 | 0 | 0 |
| `--slots` | 110 | 0 | 0 |
| `--budget` | 27 | 0 | 0 |
@@ -2238,18 +2091,7 @@ and `fetch` rejecting on every call, and asserts zero fetches, zero renderer
failures, every extract rendered, every diagram drawn, and the provenance line
stamped. All eleven pages pass.
-### Two source documents and the plan are now read by the build
-
-The previous phase started opening the two `.docx` files to check reproduced
-material. This phase extends that to the two places it had not reached.
-
-**The fifteen criteria.** Every question, every criterion name and every
-attribution is checked against section 6 of the pre-read. All forty-five strings
-occur verbatim. The count in the source document is read back too, so a sixteenth
-criterion added to the pre-read would surface as fifteen on the site against
-sixteen in the record. Until this existed, rule 4 was checked by counting and
-trusted for wording, which is the one rule the site cannot be trusted on because
-it is produced by a participant.
+### The editorial rules and the plan
**The thirteen editorial rules.** Parsed out of section 3 of the plan by a script,
not retyped, and each one asserted to occur in that document.
@@ -2266,11 +2108,10 @@ not retyped, and each one asserted to occur in that document.
count and the reason, in wording the build asserts is identical across the
three, and the departure is published on the methodology page. This settles the
snippet-count asymmetry that has been open since Gate 1.
-2. **The `--quotes` check keeps its inverted sense.** The brief asks that every
- blockquote resolve to a `quotes.json` id and that every quotation in that file
- be used. Gate 7 removed all quotations, so the check asserts the opposite: no
+2. **The `--quotes` check keeps its inverted sense.** Gate 7 removed all
+ quotations, so the check asserts that no
page carries a blockquote, no page carries a `data-quote` reference, and no
- page contains any of the eight names. The flag keeps its name because the
+ page presents personal attribution. The flag keeps its name because the
subject is the same. Applying the Gate 8 precedent rather than asking again.
3. **The thirteen rules are published in full, including the seven superseded in
part.** Each carries its status and, where something changed, what changed and
@@ -2323,19 +2164,17 @@ not retyped, and each one asserted to occur in that document.
`--methodology` asserts that while it has no entries `corrections.html` must
not exist, and that the moment it gains one the page must. That is what keeps
absent-by-decision distinguishable from absent-by-oversight.
-### Fourteen more mutations, each caught by the check that names it
+### More mutations, each caught by the check that names it
A reworded editorial rule, a dropped rule, a check advertised that the harness
does not have, an audit round missing what changed, a scope section that stops
admitting review has not happened, a matrix cell with an invented state, an
unanswered cell stripped of its reason, an approach page missing a figure, an
approach page that stops explaining its extract count, a stale offline bundle, a
-tidied criterion, an invented criterion attribution, a denominator label that
+denominator label that
embeds its own figure, and a weakened conformance mitigation.
-Twenty-one mutations were run in the previous phase. Thirty-five in total have
-been run against this harness and every one turned red only the check named for
-it.
+These mutations turned red only the checks named for them.
### What could not be verified
@@ -2603,7 +2442,6 @@ turned eight pages red immediately.
| `assets/diagrams/74-slot-strip.js` | a second copy of the state labels, so the strip tooltips still said "Filled" |
| `index.html` | two prose sentences |
| `methodology.html` | rule 5, reproduced verbatim from the plan |
-| `data/quotes.json` | three provenance strings |
The pattern in every case is that the text is generated or data-driven. A
grep of the pages could not have found any of it. The check that runs the
@@ -2799,7 +2637,7 @@ pagecheck.js 1392/1392
Reported from a screenshot. Fixed, and the cause is recorded below.
-### 2. The three approaches appear in the pre-read's option-letter order
+### 2. The three approaches appear in option-letter order
Catalog-first is option A, Component-first is B, Assessment-first is C, and that
is now the order everywhere on the site: navigation, cards, strips, matrix
@@ -2810,7 +2648,7 @@ tabs and page maps.
structural name. The reason rule 2 existed is unchanged and is still met: an
order a reader can verify from the record rather than one that looks chosen.
Option letters are the working group's own labelling, so they satisfy the same
-requirement and they match the document this site is a companion to.
+requirement without implying a ranking.
---
@@ -2863,25 +2701,6 @@ no valence by design, so which hue an approach has means nothing. The comment in
`site.css` now records the assignment as what it is: a fixed mapping made once,
not a rule that tracks the display order.
-### The two source documents have gone missing from the working copy
-
-`Hardening-Guidance-Options-Comparison.docx` and
-`Technology_Specific_Hardening_Guidance_in_OSCAL.docx` are no longer present in
-the corpora directory. The `.pptx` beside them is still there, so this looks like
-a cloud-sync eviction rather than a deletion.
-
-`--criteria` and `--questions` read those documents to assert that everything the
-site marks verbatim occurs in the source, and both crashed with a traceback. That
-is the wrong behaviour twice over: a contributor may legitimately not have the
-corpora, and a crash tells you less than a skip. Both phases now skip by name,
-with the document named and the reason stated, and a skip is still not a pass.
-
-**Three claims are therefore unverified in this run**, and they were verified in
-the previous one: the fifteen criteria and their attributions against section 6 of
-the pre-read, the eight register items marked verbatim, and the position paper's
-ten open questions. Restoring the two files and re-running `--all` re-establishes
-them. The skip count went from 9 to 12 for this reason and no other.
-
### Verification added
26 page checks, in one group: the order, asserted on every page for every
@@ -2894,16 +2713,13 @@ turns red exactly the two checks that name it and nothing else.
### Open for Gate 11
-1. **Restore the two `.docx` files** and re-run `python tools/verify.py --all`.
- Until then three verbatim claims are asserted by the data and checked against
- nothing.
-2. **Look at the rail again**, and at a page scrolled to the middle, since the
+1. **Look at the rail again**, and at a page scrolled to the middle, since the
indicator moves with the reader and only the resting state has been reasoned
about.
-3. **Eight pages still have the old shape**, unchanged from Gate 10. The
+2. **Eight pages still have the old shape**, unchanged from Gate 10. The
overview-first pattern is on the start page, the six questions and side by
side. `questions.html` is the longest page on the site.
-4. **The order is now the pre-read's and the site says so in five places.** Read
+3. **The order is now by option letter and the site says so in five places.** Read
one of them and confirm it states the reason rather than just the fact.
---
@@ -3233,9 +3049,9 @@ red the check that names it and nothing else.
### Open for Gate 14
1. **This is a correction about somebody else's approach, made by someone who is
- not its proponent.** It is well sourced: the pre-read's evidence register
- records the mapping model as the mechanism, and the plan's own binding-times
- table lists it. It is still exactly the class of claim `CORRECTIONS.md` exists
+ not its proponent.** The analysis names the mapping model as the mechanism,
+ but no mapping document is published in the corpus. It is exactly the class
+ of interpretation `CORRECTIONS.md` exists
to route through the publisher, and proponent review has not happened.
2. **Whether question 2 and question 2b should stay separate for this approach.**
They are now one mechanism described in two rows, which reads as duplication
@@ -3615,10 +3431,10 @@ is gone.
Mutating `six-questions.json` and `views.json` turns nothing red, which is correct and
worth stating. These checks assert that the page faithfully reflects the data,
-so mutating the data moves both sides together. What guards the data itself is
-`verify.py --questions` and `--criteria` against the pre-read, which is a
-different anchor and is currently skipped for a missing `.docx`. Mutating the
-renderers, which is what these checks do guard, turns red nine of them.
+so mutating the data moves both sides together. The current `--questions` and
+`--criteria` checks validate analysis structure, not the truth or fairness of
+editorial wording. Published OSCAL extracts have separate corpus-backed checks.
+Mutating the renderers, which is what these checks do guard, turns red nine of them.
`1307/1307` verify checks pass with 12 skips, `2549/2549` page checks pass.
@@ -3628,8 +3444,8 @@ renderers, which is what these checks do guard, turns red nine of them.
`if (window.TFGSlotStrip)` with no else rendered nothing and said nothing on
two pages for several phases. The same construct appears wherever a renderer
depends on an optional file. Only the legend one was fixed here.
-2. **Three verbatim claims remain unverified**, unchanged since Gate 13: both
- `.docx` sources are still absent from the corpora folder.
+2. **Editorial wording still needs review.** Structural validity is not
+ agreement with a question's framing.
3. **Eight pages still have the old shape**, unchanged since Gate 10.
4. **Proponent review has still never been sent.** `CORRECTIONS.md` is empty by
decision, not by response.
@@ -3641,9 +3457,8 @@ remove section 6 from the primer, and to remove the footer.
### Options D and E
-Options D and E were on the record in the pre-read with no published content,
-and the site carried them so that the size of the decision was not
-misrepresented. Removed on instruction. Gone from `data/six-questions.json`, from
+Options D and E had no published OSCAL content and were removed on instruction.
+Gone from `data/six-questions.json`, from
`renderOtherOptions` in `site.js`, from section 5 of `index.html` and section 7
of `compare.html`, from the two tables of contents, and from the pointer
sentences on `six-questions.html`, `compare.html` and the primer.
@@ -3655,16 +3470,10 @@ summary, and a summary of a comparison is a recommendation wearing a different
hat. The check now names the section that is last and still asserts the absence
of a closing argument.
-Two entries in `data/quotes.json`, `brian-distributed` and `banghart-abstract-ap`,
-existed only to source the removed section and are referenced by nothing.
-Removed with it, 39 quotes to 37. This is the one removal that touches the
-record of the pre-read rather than the site's own content, which is why it is
-recorded separately here.
-
### Section 6 of the primer
-"How to read this site", with the three tiers, the eleven-page map and the
-division of labour with the pre-read. Removed on instruction, with its table of
+"How to read this site", with the three tiers and the eleven-page map.
+Removed on instruction, with its table of
contents entry. The primer is five sections now.
The page map had a check worth naming before it went: it asserted the map listed
@@ -3859,8 +3668,8 @@ last of its own sections, not that any particular one is last.
**What came off with the scope box.** It was the only place stating that the
site does not resolve `capability`, does not cover the mapping models beyond
-question 2, and does not recommend, and the only place naming the pre-read on
-that page. That is recorded here rather than asserted anywhere.
+question 2, and does not recommend. That is recorded here rather than asserted
+anywhere.
### Section 6 of the primer, restored
@@ -4768,7 +4577,7 @@ cell with fewer lines than the tallest cell in its row is centred on its own, so
### Two sentences removed
The figure caption under diagram 76, which said what the drawing's own labels
-say, and the note under the three approach cards about the pre-read's
+say, and the note under the three approach cards about
option-letter order. Each card carries its own option letter, so the order is
visible rather than asserted, and the same sentence still appears on five other
pages. Six statements of one convention is five more than it needs.
@@ -5399,7 +5208,7 @@ that a shared block say what it covers.
## Session: pros and cons at the top of every approach page
**Date:** 2026-08-22
-**Scope:** section 1 of the three approach pages, from two submitted papers
+**Scope:** section 1 of the three approach pages
**Result:** complete. 1375 verification checks and 954 page checks pass.
### What was built
@@ -5408,16 +5217,10 @@ Four gains and four costs per approach, in `data/tradeoffs.json`, rendered as th
opening section of each approach page. The section that used to carry this
argument, section 6, two boxes at the foot of the page, is gone rather than
duplicated: a reader met a thousand words of description before being told what
-the thing is good and bad at. What the pre-read recorded and the papers do not
-is carried inside the new block as one line per approach, so promoting the
-argument lost nothing.
-
-Every entry cites a source. Two papers were the starting point, and two were not
-enough: several claims rest on the written proposal for one approach, on the
-pre-read, or on the model itself, and crediting those to a paper that says
-nothing on the point is the same defect as not citing at all. There are five
-sources now, and the verifier fails an entry citing one that is not declared, a
-source nobody cites, or a page that has quietly stopped reading both papers.
+the thing is good and bad at. Each entry is analysis: claims about published
+content need OSCAL example evidence, and claims about a model's constraints need
+schema evidence. Neither kind of evidence establishes agreement with a strength
+or risk as framed by the analysis.
### The block is where an asymmetry does the most damage
@@ -5436,8 +5239,8 @@ same length rather than the costs cut back.
### What the fact-check found
-The draft was checked line by line against the two papers, the three corpora and
-the OSCAL schemas, twice. It found four things worth recording.
+Review of the draft against the three corpora and the OSCAL schemas found four
+things worth recording.
**A claim can only be made against a component.** In a system security plan the
response is `by-component`, keyed by `component-uuid`, and it carries no subject
@@ -5477,11 +5280,11 @@ side page, where all three columns are visible at once.
A second reading found the block scoring three axes rather than describing them.
Tailoring was a headline cost on one page, absent from another, and a trailing
-clause on the third, when the position paper charges it to two of the three in
-the same words. The by-component limitation was a cost on one page, the mirror
+clause on the third. The same structural limitation must receive the same
+treatment wherever it applies. The by-component limitation was a cost on one page, the mirror
gain on another, and not charged at all on the third, whose own claim mechanism
-is a by-component response. The same figure was headlined as a plan of record
-tripling in one place and as desired state arriving in another. Two pages
+is a by-component response. Plan-of-record growth was framed as a cost in one
+place and as desired state arriving in another, without a consistent derivation. Two pages
softened their corpus shortfalls with a line saying the shortfall is the files
rather than the model; the third had no such line. All four are levelled now.
@@ -5517,10 +5320,9 @@ four, and the other two pages were cut to match, both in count and in length: a
block that ran a fifth longer on one page would be an argument made in the
layout.
-The block no longer cites anything on the page. The chips under each entry, the
-line of what the pre-read adds and the list of source documents are all gone,
-which is a decision rather than an omission. What each entry rests on is
-recorded here in this log. Where an entry turns on what a model can express, the
+The block no longer carries citation chips or a source list on the page.
+The entries are editorial analysis, not attributed statements. Where an entry
+turns on what a model can express, the
schema fragment behind it is still named in `data/tradeoffs.json` and still
checked, without being rendered.
@@ -5652,10 +5454,9 @@ to the model map, which is the other structural figure on those pages.
The fifteen criteria table and the four agreements were both unique to the page
and both dropped, on the call recorded in the conversation. `criteria-fill.json`
-went with the table. `criteria.json`, the questions themselves reproduced from
-the pre-read, stayed: the open questions page still quotes one criterion
-verbatim, and that quotation should keep coming from the data rather than being
-typed into the page.
+went with the table. `criteria.json` stays as the 15 evaluation criteria
+maintained as analysis content, with structural checks on the criteria and their
+question mappings.
### What came back from the dead
@@ -5738,9 +5539,9 @@ the page are the numbers in the data and neither can drift from the other.
### Two things went dead with the move
-`renderCited` and the `.cited` marker existed to render a quoted figure and mark
-it as quoted rather than counted. The scenario page writes those three numbers as
-text, generated from the same data at build time, so both are gone.
+`renderCited` and the `.cited` marker were removed. The scenario page generates
+its figures from scenario data with declared derivations; it does not inherit
+unsupported scale claims.
### Every tile now names its file, and a component definition says which kind
@@ -8067,9 +7868,9 @@ extract.
**Date:** 2026-08-25
-The page was twelve sections and about 3,900 words: a reproduced evidence
+The page was twelve sections and about 3,900 words: an evidence
register of eleven items, six questions each with its own headings and
-sub-headings, two reproduced lists, a block on what would settle the
+sub-headings, two question lists, a block on what would settle the
disagreement and a block on how to contribute. A reader arriving to find out
what is unresolved read an essay.
@@ -8082,9 +7883,8 @@ shape the questions were always in and the page was not.
Component-first 9
Assessment-first 1
-**The distribution is a finding.** Most of what is unresolved is about OSCAL
-rather than about any one approach, which is why the first section is the
-longest and why the page now says so in its opening line.
+**The distribution is editorial, not a measure of defects.** Section lengths
+reflect the selected questions, not the completeness or quality of an approach.
**The new question, and it is the one the reorganisation was for.** Do many
catalogs converge into one profile and one plan of record, or does each catalog
@@ -8095,18 +7895,14 @@ sits beside a regulatory one. The worked scenario assumes convergence, which is
why its figure is 18 files and not more, and a check now holds the question by
name so it cannot quietly leave the page.
-**Reproduced questions keep their wording, including their errors.** Fourteen of
-the twenty-three come from the position paper or the component-first proposal,
-and they are marked as asked and carry the document they came from. Three of the
-paper's items run past the length an authored question is held to and two are
-statements rather than questions. Both rules were scoped rather than applied:
-cutting someone else's question to fit, or adding a question mark to their
-statement, is editing it, and editing a question is a way of answering it.
+**Questions are maintained as analysis content.** Their wording and reasoning
+can be revised through editorial review. Structural checks preserve identifiers
+and validate the question structure; they do not establish reproduction or
+attribution. Existing anchors remain stable when the prose changes.
**What was dropped, on the call in the conversation.** The evidence register,
-the settle block and the contribute block. The register reproduced somebody
-else's list of the group's conversations and was the longest thing on a page
-meant to be scannable.
+the settle block and the contribute block. The register was the longest block
+on a page meant to be scannable; open issues now live in the question lists.
**Re-validated against the site as it now is, which mattered.** The platform
semantics question still described questions 4 and 5 as answered by six
@@ -8154,9 +7950,8 @@ the start page is a list of what was read.
and none reaches a page: the directory each corpus is read from, which is a path
on disk; the titles inside the published files, which are read off the documents
rather than written here; and the repository link, which is a location a reader
-can go and check the counts against. The site already keeps provenance it does
-not render, in `quotes.json` and in the advocate fields of `views.json`, and
-this is the same distinction.
+can go and check the counts against. These are properties of the published OSCAL
+examples, not attribution of editorial statements.
**The check now has no branch.** It read "if this is the artifacts page, assert
it does name publishers; otherwise assert it does not". One rule, no exception,
@@ -8492,7 +8287,7 @@ to the engine's row, and putting "nothing to write" back.
**Date:** 2026-08-25
-Six questions off the page: four from the across-all section and two reproduced
+Six questions off the page: four from the across-all section and two
catalog-first ones.
- `parameters`, where a rule's parameter goes
@@ -8561,14 +8356,10 @@ walks ``, so the head was exempt, and nothing on the page showed it. A
search result and a link preview would have shown it to everyone. Gate 7 now
reads the title and description too.
-*Two data files hold attributed quotations of named third parties.*
-`data/quotes.json` carries 37 quotes from nine people at AWS, IBM, NIST and
-elsewhere; `data/criteria.json` attributes criteria to individuals. No page
-fetches either, and both would have been published verbatim by a naive copy of
-`data/`. `assets/bundle.js` mirrors all of `data/`, so it is rebuilt over the
-shipped subset rather than copied; copying it would have shipped those quotes
-inside a script tag. They stay in the working repository, which is where the
-evidence belongs.
+*The folder-based fallback must match the package.* `assets/bundle.js` mirrors
+all of `data/` in the working site, so packaging rebuilds it over the shipped
+subset rather than copying it. This keeps the fallback aligned with the files
+the package includes.
**What was proved rather than asserted.** The package was served over plain
HTTP with no rewrite rules, the way object storage does, and all 83 URLs the site
@@ -8577,10 +8368,78 @@ link depends on a directory index, a redirect, or a case-insensitive filesystem.
The `file://` mirror was checked to hold exactly the 48 entries the site asks for
and no more. Then the zip was unpacked to a clean directory and served again.
-There are no orphans to delete. Everything under `assets/` and `data/` is read by
-the browser or by a generator or by the harness. Three extracted snippets are
-rendered by no page: they are cited from `data/provenance.json` and
-`data/quotes.json` as evidence, which is a reason to keep them and a reason not
-to ship them.
+Runtime inclusion and verification evidence are separate. An OSCAL extract may
+be retained for a declared evidence pointer without being fetched by a page;
+packaging selects browser inputs rather than copying all build inputs.
`2619/2619` verify checks and `649/649` page checks pass.
+
+## Session: the examples become curated, and validate
+
+### Gate decision: the examples are curated, not verbatim
+
+**Date:** 2026-09-10
+
+Pirooz: the repository does not need verbatim copies of what each publisher
+released. Example files may be repaired, replaced or added. The fingerprint index
+stays, so an edit is still something the build notices; what changes is that a
+deliberate edit has a sanctioned path, `copy_examples.py --rebaseline`, and a
+place to be recorded, which is this log.
+
+### The four schema defects repaired, and the SSP chain made local
+
+**Date:** 2026-09-10
+**Scope:** examples/assessment-first, the example index and lock, three corpus
+figures, the link check
+**Result:** every assessment-first example validates against NIST OSCAL 1.2.1;
+`--all --offline` 2717/2717.
+
+**What changed in the examples, file by file.**
+
+*`CISA BOD 25-01/ap-cisa-scuba-maester.json`* and *`ap-cisa-scuba-scubagear.json`*:
+each of the seven `associated-activities` under `tasks/0` gained a `subjects`
+block naming the same inventory item the task already assesses,
+`791778c1-234b-4e30-8490-07ad2e6fec92`, as `include-subjects`. Maester's
+task-level subject, which had been written as a bare `subject-uuid` and failed
+the schema's `anyOf`, was rewritten in the same `include-subjects` shape. The
+schema requires `subjects` on every associated activity; both `oscal-cli` 3.1.0
+and the verifier reported the same seven paths per file.
+
+*`DISA/.../win2019.json`* and *`win2022.json`*: one STIG rule in each
+(V-205665, V-254418) carried a line break inside its title, and the two step
+titles derived from it inherited the break. The break was removed from the six
+titles. Descriptions, which may contain line breaks, were not touched.
+
+*`CISA BOD 25-01/sample-ssp.json`*, new: the system security plan the three
+SCuBA plans import. Their shared back-matter resource `080172e1-…` used to point
+at `./ssp.xml`, `./ssp.json` and `./ssp.yaml`, none of which existed, so
+`oscal-cli` in its default mode stopped at the import and never reached the
+schema. All three plans now point at `./sample-ssp.json`.
+
+*`examples/NIST_SP-800-53_rev5_catalog.json`*, new, at the examples root: the
+SSP's `import-profile` used to resolve through a profile on registry.oscal.io
+whose own catalog link returned 404. The SSP now imports the local catalog
+directly, so the whole chain, plan to SSP to catalog, resolves from this
+repository. The catalog is indexed under a new `shared` list in
+`data/examples.json`, because it belongs to no single approach.
+
+**What moved with them.** The Easy Dynamics set is 19 files, so
+`tools/source-lock.json` says 19 and the index was rebaselined. Six snippets
+re-extracted; five changed only their source hash, and `ez-cisa-task-timing`
+now shows the task with its subjects, which is what a reader should see. Three
+corpus figures moved: `cisa_files` 5 to 6, `ez_ssp_files` 0 to 1,
+`ez_subjects_inventory_item` 11 to 26. `oscal-artifacts.json` gained an SSP row.
+
+**One check loosened, narrowly.** cisa.gov answers 403 to every non-browser
+client, including GitHub's runners, so the link to BOD 25-01 failed the
+reachability check although the page is live. `verify.py` now carries a short
+list of hosts known to block automated clients, with the date a person last
+opened the link; a 403 from a listed host passes and says why. Any other status,
+or a 403 from any other host, still fails.
+
+**What still fails under `oscal-cli` with constraints on.** The SCuBA plans
+report Metaschema constraint findings the JSON schema does not express:
+`oscal-activity-type-cardinality` on every activity, duplicate links within a
+step, and prop names outside the allowed set. These are the publisher's
+modelling choices, they do not affect the verifier's checks, and they are left
+as they are.
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/CORRECTIONS.md b/docs/analysis/2026-08-automating-technical-hardening-guidance/CORRECTIONS.md
index 6d66243..2b6b359 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/CORRECTIONS.md
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/CORRECTIONS.md
@@ -52,12 +52,12 @@ field names.
## The request that has not been sent
Recorded here so that when it goes out, what was asked is on the record too. The
-norm is the pre-read's own: correct anything about your approach that is wrong.
+request is to correct anything about your approach that is wrong.
> This site describes three published bodies of OSCAL content, including yours.
-> Everything on it is extracted from your published files at declared pointers
-> and can be re-derived with one command, but three things are judgements the
-> build cannot check, and they are the three worth your time.
+> Its extracts come from published OSCAL files at declared pointers and can be
+> re-derived. Encodings, criteria and open questions are maintained as analysis
+> content. Three judgements need review beyond the structural checks.
>
> First, section 7 of your approach's page states the case for it as its
> proponents would state it. If that is not the case you would make, that is the
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/README.md b/docs/analysis/2026-08-automating-technical-hardening-guidance/README.md
index 57b7013..c3f6cb4 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/README.md
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/README.md
@@ -3,89 +3,86 @@
A comparison site for the OSCAL Foundation Technical Focus Group on Automated
Assessments.
-Three organizations have published working OSCAL content that answers the same
-question three different ways: **where does technical hardening guidance live in
-OSCAL, and how does an automated check attach to it?** This site puts the three
-side by side against the same six questions, writes the same two rules out in all
-three shapes so that the only thing differing between the columns is the
-modelling, and names the join key that makes each one work.
-
-**The JSON on the question pages is ours.** The three groups ship content for
-different products, so quoting what each one published would set a certificate
-control beside an object-store rule beside a Linux STIG, which compares subject
-matter rather than modelling. So two rules were chosen once, both published
-Ubuntu 24.04 LTS requirements keeping their real identifiers, and written out in
-each approach's own shape by `tools/pattern_examples.py`. What is authored is the
-encoding and nothing else: every property carries the namespace of the approach
-it illustrates and none of them is ours. What the three groups have actually
-published is inventoried separately, on `oscal-artifacts.html`, one row per
-document with its contents counted from the file rather than described. Extracts
-at declared pointers into the published files are still carried where a claim
-rests on one, and they are still re-derived on every build.
-
-Published hardening guidance from four publishers was read as input: CIS, DISA,
-CISA and AWS. The introduction tabulates it one row per benchmark or guide, in a
-disclosure that is closed until it is wanted, and every row carries what stands
-behind it. A file icon downloads one of the 16 documents recorded under
-`sources/`, 29.0 MB in all, and names the file, its type and its size on
-hover; a globe opens
-the publisher's own page for guidance that is not a document to hold. Every one
-of them opens in a new tab. **Only inputs are listed.** The OSCAL written from
-this guidance is published separately, so `sources/oscal/` is in the repository
-but carries no row: `tools/sources_files.py` excludes it from the inventory, as
-it excludes `disa/U_Readme_SRG_and_STIG.pdf`, which is about the STIG packages
-as a set rather than about any one guide. `verify.py --sources` recomputes every
-count from the corpora,
-confirms every link resolves to a file, confirms no file sits in `sources/` unlinked,
-and confirms nothing from the excluded tree is linked. Terms differ by publisher and
-each file carries its own.
-
-**The CIS material is here on a recorded basis.** `sources/cis/` holds the two
-CIS Benchmarks in both their JSON and PDF form, 19.7 MB of the 29.0 MB. CIS
-licenses its Benchmarks under its own Agreed Terms of Use, which on their face
-say a Benchmark may not be redistributed or posted on any website. The material
-is here because CIS is a stakeholder receiving this brief and confirmed that
-copying and linking infringes nothing. That call is recorded in `BUILD-LOG.md`,
-and each of the four files carries the basis rather than a general grant in its
-own terms line: *"Reproduced here with the publisher's participation in this
+Three organizations have published OSCAL content addressing the question:
+**where does technical hardening guidance live in
+OSCAL, and how does an automated check attach to it?** The analysis compares
+three approaches against six questions, encodes
+the same two rules in all three model structures to isolate modelling
+differences, and identifies the join key for each approach.
+
+**The JSON encodings on the question pages were authored for the analysis.**
+The published content covers different products: a certificate control, an
+object-store rule, and a Linux STIG would compare subject matter rather than
+modelling. Instead, `tools/pattern_examples.py` encodes two published Ubuntu
+24.04 LTS requirements in each approach's structure, retaining the published
+identifiers. Only the encoding is authored; property namespaces come from the
+illustrated approaches, not the analysis authors. `oscal-artifacts.html`
+inventories the published content separately, one row per document, with
+contents counted from each file. Extracts supporting claims retain declared
+pointers into published files and are re-derived on every build.
+
+The analysis uses published hardening guidance from CIS, DISA, CISA, and AWS.
+The introduction lists one row per benchmark or guide in a collapsed disclosure,
+with links to source material. File icons download the 16 documents recorded
+under `sources/`, totalling 29.0 MB; hover text gives the filename, type, and
+size. Globe icons link to publisher pages for guidance without a downloadable
+document. All source links open in new tabs. **Only inputs are listed.** OSCAL
+content derived from the guidance is published separately.
+`tools/sources_files.py` excludes `sources/oscal/` from the inventory and also
+excludes `disa/U_Readme_SRG_and_STIG.pdf`, which describes STIG packages rather
+than an individual guide. `verify.py --sources` recomputes counts from the
+corpora and checks link resolution, coverage of included files in `sources/`,
+and absence of links into the excluded tree. Each file lists publisher terms.
+
+**The basis for including CIS material is recorded.** `sources/cis/` holds two
+CIS Benchmarks in JSON and PDF, accounting for 19.7 MB of the 29.0 MB. On their
+face, CIS's Agreed Terms of Use prohibit redistributing a Benchmark or posting a
+Benchmark on a website. CIS is a stakeholder receiving the brief and confirmed that copying
+and linking infringes nothing. `BUILD-LOG.md` records the confirmation. Each of
+the four files states the basis for inclusion, not a general grant:
+*"Reproduced here with the publisher's participation in this
review. The Benchmarks carry CIS's own Agreed Terms of Use; consult the
publisher before reusing them elsewhere."* **A fork or a mirror made outside
that conversation does not inherit the basis.** The DISA material is a work of
the United States Government, 13 files and 9.3 MB, 12 of them with a row.
-**It makes no recommendation.** There is no ranking, no score, and no summary
-that adds up to one. Where an approach carries a cost, the cost is stated and the
-reader prices it.
+**No recommendation is made.** The analysis provides no ranking, score, or
+implied recommendation. Costs are stated for readers to evaluate.
## Status
-Ready to publish, not published. Eight pages, all built: `index.html`,
+Active analysis with eight built pages: `index.html`,
`six-questions.html`, the three approach pages, `scenario.html`, `questions.html`
-and `oscal-artifacts.html`. What remains is not a build step:
-
-- **Proponent review has not happened.** No request for corrections has been sent
- to the publishers of the three bodies of content, so none has been received and
- nobody has declined. This is stated on the site rather than left implicit.
-- Four checks cannot run without network and are skipped locally. They run in CI.
-- Two more skip wherever the pre-read and the position paper are not on disk.
- Both are Word documents, both live beside the site rather than in it, and
- neither is in the corpora repository the workflow checks out, so `--criteria`
- and `--questions` skip their verbatim halves in CI as well as locally. Put the
- two documents at the root of the corpora directory and both run.
+and `oscal-artifacts.html`. Strict verification is not fully passing. Remaining
+review and verification items:
+
+- **Proponent review has not happened.** No correction requests have been sent
+ to the publishers; no corrections have been received, and no publisher has
+ declined review. The site states the review status.
+- Schema, external-link and browser checks need their dependencies and network
+ access; offline skips are not strict passes.
+- The examples are curated: four published assessment-plan schema defects were
+ repaired in the committed copies on 2026-09-10, detailed below and in
+ `BUILD-LOG.md`.
+- Full checks require the repository-defined sources: committed examples and
+ the verified public AWS cache. Prepare the cache explicitly before working
+ offline; CI prepares it before corpus-dependent checks.
+
+The 15 evaluation criteria and the open questions are maintained as analysis
+content and verified structurally. They are not reproduced or attributed text.
+Published OSCAL example evidence is checked against the locked source inputs.
`BUILD-LOG.md` records every phase, every decision, and the open items for each
review gate.
## Viewing the site
-This analysis is one area of the Pattern Library site and is served with it
-rather than on its own. It carried its own `serve.cmd` and `tools/serve.py`
-when it was a standalone repository; both are gone, because a second server
-rooted here would serve this folder as if it were the whole site and hide the
-thing a reader arrives through.
+The analysis is served within the Pattern Library. The former standalone
+`serve.cmd` and `tools/serve.py` have been removed. A server rooted in the
+analysis folder would exclude the library landing pages.
-From the repository root, serve `docs/` and open this area from the analysis
-index. Pressing F5 in VS Code does both:
+From the repository root, serve `docs/` and open the analysis from the analysis
+index. Press F5 in VS Code to start the server and open the site:
```
python3 -m http.server --directory docs 4173
@@ -93,8 +90,8 @@ npx serve docs
```
Or install the recommended Live Preview extension and click the preview button
-on any page; `.vscode/settings.json` already points its server root at `docs/`.
-Either way this analysis is at:
+on a page; `.vscode/settings.json` sets the server root to `docs/`.
+The analysis path is:
```
/analysis/2026-08-automating-technical-hardening-guidance/
@@ -102,170 +99,264 @@ Either way this analysis is at:
### Why a server, and what happens without one
-Every page is markup plus data: the markup carries hooks and `assets/site.js`
-fills them from `data/` at load time, so regenerating data never touches markup.
-A browser gives a `file://` page an opaque origin and blocks `fetch()`, so a page
-opened by double-clicking cannot read its own data files.
+Page markup contains hooks populated by `assets/site.js` from `data/` at load
+time. Regenerating data leaves markup unchanged. Browsers assign opaque origins
+to `file://` pages and block `fetch()`, preventing direct access to data files.
-Opening `index.html` directly still works. `assets/bundle.js` carries a copy of
-every data file and every diagram, and the page reads that instead and says so in
-one line at the top:
+Opening `index.html` directly still works: `assets/bundle.js` contains copies
+of every data file and diagram. The page reads the bundle and displays a notice:
> Opened from a folder rather than a server, so this page read its content from
> `assets/bundle.js`, a mirror of `data/` that the build checks byte for byte ...
-**That line is the site telling you which copy you are reading, not an error.**
-The content is identical: `tools/verify.py --bundle` rebuilds the mirror and fails
-on any difference. Serving the site reads `data/` directly and the line does not
-appear. GitHub Pages serves over HTTP, so a published copy never shows it.
+**The notice identifies the content source, not an error.**
+`tools/verify.py --bundle` rebuilds the mirror and fails on any content
+difference. Served pages read `data/` directly without the notice. GitHub Pages
+serves over HTTP, so published pages do not display the notice.
## Verifying it
-One command:
+Run these commands from this analysis directory. CI uses Python 3.12, Node.js
+20 and the DejaVu fonts (`fonts-dejavu-core` on Ubuntu).
+```sh
+pip install pyyaml pillow 'jsonschema[format]' regex
+node tools/bannercheck.js
+test -f tools/test_verify.py && python -m unittest discover -s tools -p 'test_*.py' -v
+python tools/verify.py --data --css --quotes --bundle --source --pages --offline
```
-pip install pyyaml pillow
-python tools/verify.py --all
-```
-
-Pillow is not optional: `verify.py` imports `svgrender`, which imports it at
-module scope to rasterise the diagrams for `--diagrams`.
-The corpora are read from `TFG_CORPORA` when it is set, and from the
-`corpora_root` in `tools/manifest.yaml` when it is not. This site sits under
-`docs/analysis/` in a repository the corpora are not a sibling of, so set it:
-
-```
-export TFG_CORPORA=/path/to/tfg-automated-assessments
+This subset checks local content, CSS, absence of quotation and attribution hooks,
+bundled data, source-code sanity and page rendering without preparing the public
+source cache. Unit discovery includes verifier and source-resolver tests.
+`--pages` runs
+[tools/pagecheck.js](tools/pagecheck.js); it can also be run directly with Node.
+`--example` is not corpus-independent: it invokes the artifact inventory
+generator, so it remains in the full pass below.
+
+Pillow is required at import time by [tools/svgrender.py](tools/svgrender.py).
+Formal OSCAL validation uses `jsonschema[format]` and `regex`; format dependencies
+enforce timestamps and URIs, and `regex` supports Unicode patterns in the NIST schemas.
+`compliance-trestle` is not used.
+Install dependencies before disconnecting from the network.
+
+### Repository-defined sources
+
+[tools/source-lock.json](tools/source-lock.json) defines the source inventory;
+[tools/source_inputs.py](tools/source_inputs.py) resolves it without environment
+overrides or implicit downloads. No personal corpus folder, second repository
+checkout, source-repository Actions variables, or private corpus upload is
+required.
+
+| Source | Authoritative input | JSON files |
+|---|---|---:|
+| IBM | Committed [examples/component-first/](examples/component-first/) | 6 |
+| Easy Dynamics | Committed [examples/assessment-first/](examples/assessment-first/) | 18 |
+| AWS | Public [awslabs/oscal-content-for-aws-services](https://github.com/awslabs/oscal-content-for-aws-services/tree/4a1779ffb556c4ab8fb3dad94a19d4d198116803), revision `4a1779ffb556c4ab8fb3dad94a19d4d198116803` | 231 |
+
+The committed local examples are the source of truth. Their inventory, byte
+sizes and SHA-256 fingerprints must match [data/examples.json](data/examples.json).
+Missing, extra or changed JSON inputs fail validation; regenerating the index
+is not a way to bless an unexpected local change. Restore the committed files
+and index unless changing the inputs is an explicitly reviewed change.
+
+Fetch once while online, before the full offline pass or regeneration:
+
+```sh
+python tools/source_inputs.py --fetch
+python tools/source_inputs.py --check
```
-Eighteen checks. Each prints `PASS` or `FAIL` with detail. A check that cannot run
-in the current environment prints `SKIP` with the reason and the exact command it
-would have run, and is reported separately from the checks that passed. **A skip is
-never counted as a pass.**
-
-```
-python tools/verify.py --snippets re-extract every extract and diff
-python tools/verify.py --schema every OSCAL constraint the argument rests on
-python tools/verify.py --conformance labelled conformant validates, proposed fails
-python tools/verify.py --example our own encodings, and what must hold across them
-python tools/verify.py --quotes no page quotes anyone or names anyone
-python tools/verify.py --criteria the fifteen are the group's, verbatim
-python tools/verify.py --stats recompute every cited figure from source
-python tools/verify.py --sources the guidance read as input, recomputed
-python tools/verify.py --matrix every matrix cell resolves and is classified
-python tools/verify.py --diagrams structure, colour, geometry, join literals
-python tools/verify.py --css colour lives only in the token block
-python tools/verify.py --links every internal link, anchor and path
-python tools/verify.py --budget equal budget across the three approach pages
-python tools/verify.py --a11y contrast, then axe-core over every page
-python tools/verify.py --bundle the offline fallback matches data/
-python tools/verify.py --questions the reproduced material matches its source
-python tools/verify.py --data internal consistency of data/
-python tools/verify.py --pages run each page and inspect what it rendered
+Only explicit `--fetch` may download or repair the public AWS cache. The pinned
+codeload archive is authenticated against the lock's byte size and SHA-256
+before extraction. The cache is rooted at
+`.cache/oscal-sources/aws/4a1779ffb556c4ab8fb3dad94a19d4d198116803/` within this
+analysis directory, with the authenticated archive retained as
+`.source-archive.tar.gz` alongside the selected JSON, LICENSE and NOTICE files.
+The cache is ignored by Git; it is not a committed source copy or a runtime
+download dependency. The resolver does not upload or read a private/local
+corpus outside this repository.
+
+`--check` is offline: it revalidates the local fingerprints, retained archive
+and complete cached inventory. Missing or corrupt cached inputs fail; they are
+never counted as an empty corpus, skipped, or fetched implicitly. Run `--fetch`
+explicitly again to repair the public cache or prepare a changed pin. A valid
+cache is reused without downloading.
+
+Changing an input pin is an explicit tracked change to the source lock, not a
+branch update or a machine-specific override. Update the archive URL, digest,
+size, inventory and pinned link metadata together, and regenerate affected
+provenance, example/link indexes and generated outputs, including the bundle.
+Intentional local input changes likewise require reviewed updates to the
+committed examples and their fingerprint index, and to the lock if inventory
+counts change. Do not change published inputs merely to make checks pass.
+
+### Offline and strict passes
+
+After source preparation and dependency installation, run offline:
+
+```sh
+python tools/source_inputs.py --check
+python tools/verify.py --all --offline
```
-`node tools/pagecheck.js` runs behind `--pages` and can be run alone, including
-against one page: `node tools/pagecheck.js six-questions.html`.
+`--offline` prevents verifier network access; it does not replace or waive
+source checks. Network-dependent checks report `SKIP`, separately from `PASS`
+and `FAIL`. **An offline pass is not proof of strict verification.**
-**In CI**, `--strict` turns every skip into a failure, on a runner that has the
-network and the validators. That is what stops a skipped check from staying
-skipped. See `.github/workflows/verify-2026-08-hardening-guidance.yml` at the
-root of this repository.
+With the same locked inputs and network access available, run every check
+with every skip treated as a failure:
-### What needs network
+```sh
+npm install --no-save axe-core puppeteer
+python tools/source_inputs.py --check
+python tools/verify.py --all --strict
+```
-| Check | Needs | Command it would run |
-|---|---|---|
-| `--schema`, second half | The published NIST 1.2.1 schemas | `curl` the schema, compare each stored fragment |
-| `--conformance` | An OSCAL validator | `pip install compliance-trestle` |
-| `--a11y`, second half | axe-core and a headless browser | `npm install --no-save axe-core puppeteer` |
-| `--links`, external half | The links themselves | `curl -o /dev/null -w '%{http_code}'` per link |
+| Check | Additional requirement for strict verification |
+|---|---|
+| `--schema`, `--conformance` | Published NIST OSCAL 1.2.1 schemas; `jsonschema` and `regex` installed above |
+| `--a11y` | axe-core and Puppeteer's headless browser |
+| `--links` | Reachable external link targets |
+
+Schema downloads use the pinned NIST 1.2.1 release assets, not generated-file
+paths absent from the source tag. Refresh full schema evidence explicitly with
+`python tools/schema_evidence.py assessment-subject by-component metadata`, then
+regenerate the bundle. Do not rewrite published OSCAL examples to make validation pass.
+
+The full `--all` pass retains extraction, corpus statistics, source inventory,
+scenario, example, schema and conformance checks alongside structural checks.
+Individual flags select checks for diagnosis; they do not replace the full pass.
+
+In VS Code, run **analysis 2026-08: prepare sources** once while online before
+**analysis 2026-08: verify** or **analysis 2026-08: regenerate**. Preparation is
+deliberately not an automatic dependency. Both later tasks begin with
+`--check` and never fetch inputs; **verify** runs `--all --offline`.
+Use the strict command above when network-dependent verification is required.
+
+### Curated examples
+
+The files under `examples/` are curated OSCAL examples, not verbatim copies of
+what each publisher released. `data/examples.json` records the path, byte count
+and SHA-256 of every file, `tools/source-lock.json` records how many files each
+set holds, and every build re-verifies both before any check that reads them, so
+an unnoticed edit fails the build. A deliberate repair, replacement or addition
+is accepted by running `python tools/copy_examples.py --rebaseline` after
+updating `expected_files` in the lock, and recording what changed and why in
+`BUILD-LOG.md`.
+
+Every assessment-first example validates against the NIST OSCAL 1.2.1 JSON
+schemas under `--conformance`. The 2026-09-10 entry in `BUILD-LOG.md` lists the
+repairs that made that true, and what each one changed.
+
+### CI source preparation
+
+The [verification workflow](../../../.github/workflows/verify-2026-08-hardening-guidance.yml)
+runs banner tests, all verifier/source-resolver/workflow unit tests and the
+corpus-independent offline subset in both jobs before source preparation.
+Each job then runs `python tools/source_inputs.py --fetch` followed by
+`python tools/source_inputs.py --check` before corpus-dependent phases.
+Downloads and dependency installation precede `--all --offline`; the verifier
+itself does not access the network in that pass. Source preparation or integrity
+failure stops the job, with no fallback to an unpinned checkout or missing inputs.
+The strict pass retains schema, external-link, browser and accessibility checks,
+and treats every skip as a failure. After browser dependencies are installed, a
+separate strict accessibility audit runs even if another check fails. Audit
+errors and violations fail the job; they are not suppressed.
+
+After the full offline pass, CI regenerates outputs in dependency order and
+requires no changes in the generated-output paths, including additions,
+deletions and untracked files. Its generation sanity step rechecks sources
+offline and runs [tools/copy_examples.py](tools/copy_examples.py) before
+[tools/oscal_artifacts.py](tools/oscal_artifacts.py). The existing data diff
+covers [data/examples.json](data/examples.json), alongside provenance and other
+data, [assets/bundle.js](assets/bundle.js), diagrams and generated pages.
+The Pages-build job, publication workflow and organization Pages settings are
+unchanged. No private corpus upload, additional credential or runtime network
+change is part of this source preparation.
## How the content is produced
-Nothing on this site is transcribed, and nothing is typed twice. Content on this
-site comes from one of two places and always says which. An **extract** is taken
-from a real published file at a declared JSON pointer and is re-derived on every
-build. An **encoding** is written by a generator from data held in that
-generator, is labelled on its own bar as ours, and is regenerated and diffed on
-every build so it cannot be hand-edited. Every figure, in either case, is
-recomputed from the corpora rather than stated.
+Published evidence and authored analysis are distinguished. An **extract** comes
+from a published file at a declared JSON pointer and is re-derived on every build. An
+**encoding** comes from generator-held data, is labelled as authored for the
+analysis, and is regenerated and diffed on every build to detect hand edits.
+Every figure is recomputed from the corpora.
```
+python tools/source_inputs.py --check # require prepared inputs; never fetch here
python tools/extract.py # rebuild data/snippets and data/provenance.json
python tools/pattern_examples.py # write the two rules in all three shapes
+python tools/copy_examples.py # rebuild data/examples.json from verified inputs
python tools/oscal_artifacts.py # inventory what the three groups have published
python tools/sources_files.py # rebuild data/source-files.json from sources/
python tools/diagrams.py # rebuild every published SVG in assets/diagrams
python tools/approach_pages.py # rebuild the three approach pages
python tools/scenario_page.py # rebuild the worked scenario page
python tools/bundle.py # rebuild the offline fallback
-python tools/verify.py --all # prove the site says what the files say
+python tools/verify.py --all --offline # verify offline; run strict separately
```
-That is the order the workflow runs them in, and it is the order they depend on
-each other in: the bundle mirrors everything upstream of it, so it goes last.
-Four of them take `--check`, which compares instead of writing and exits non-zero
-if the committed file is stale: `pattern_examples.py`, `oscal_artifacts.py`,
-`sources_files.py` and `bundle.py`. `approach_pages.py` does the same job the
-other way round: it records the hash of every page it writes and refuses to
-overwrite one that has been hand-edited since, so an edit made in the page rather
-than in the data stops the build instead of disappearing into it.
-
-`tools/manifest.yaml` is the declarative source of truth for the extracts. Each
-of its 29 entries names a source file, an RFC 6901 pointer, the question the
-extract illustrates, and any trimming applied. Trimming is always declared and is
-marked in the rendered output; there is no silent truncation.
+The workflow runs generators in the listed dependency order. The bundle runs
+last to mirror all preceding output. Five generators accept `--check` to compare
+without writing and exit non-zero for stale committed files:
+`pattern_examples.py`, `copy_examples.py`, `oscal_artifacts.py`, `sources_files.py`,
+and `bundle.py`.
+`approach_pages.py` records generated-page hashes and refuses to overwrite
+hand-edited pages. Editing a generated page instead of source data stops the
+build rather than losing the edit.
+
+`tools/manifest.yaml` declares 32 snippets, all JSON. Each entry names a published
+OSCAL JSON source file, an RFC 6901 pointer, the illustrated question, and any
+trimming applied. Trimming is declared and marked in rendered
+output; there is no silent truncation.
`data/provenance.json` records the SHA-256 of both the source file and the
extracted content.
-`tools/pattern_examples.py` is the source of truth for the encodings. Two rules,
-one binary and one carrying a value, because the pair is what shows where each
-approach puts a parameter. The pair is written into each of the seven question
-rows in each approach's shape, plus one composite that puts the whole chain for
-one rule in three panes. Where an approach answers a question with nothing, as
-assessment-first does for 6a, nothing is encoded and nothing is invented.
-`--example` holds the encodings to the disciplines the extracts are held to: real
-published identifiers, a real namespace on every property that carries one and
-none of them ours, nobody named, and the same rules in the same order in every
-column.
-
-`verify.py` does more than diff. It asserts named facts against the corpora,
-recomputes every figure the site cites, and, when the two source documents are on
-disk, opens them to confirm that everything the site marks verbatim occurs in the
-document it names: the fifteen criteria and their attributions against the
-pre-read, the eleven evidence-register items, and the position paper's ten open
-questions. When they are not on disk it skips those by name rather than passing
-them. The editorial rules were checked against the development plan by a
-`--methodology` phase, which went when the methodology page it checked was
-removed; they are no longer machine-checked.
+`tools/pattern_examples.py` is the source of truth for encodings. Two rules, one
+binary and one carrying a value, demonstrate parameter placement. The generator
+encodes the rules for each of seven question rows in each approach's structure.
+A composite shows one rule's complete chain in three panes. Unanswered questions
+receive no encoding. `--example` checks the same
+constraints as extracts: published identifiers, approach namespaces where
+required rather than invented namespaces, no named parties, and identical
+rule order across columns.
+
+`verify.py` asserts OSCAL example facts against the corpora and recomputes cited
+figures. The 15 criteria and open questions are analysis content: `--criteria`
+and `--questions` check structure, identifiers, question mappings and reasoning,
+not attribution or text reproduction. The former `--methodology` phase checked
+editorial rules against the development plan.
+Removal of the methodology page also removed the check; editorial rules are no
+longer machine-checked by that phase.
## Layout
```
data/
- snippets/ 29 files, one per extract, never edited by hand
+ snippets/ 32 JSON files, one per extract, never edited by hand
schema-evidence/ 8 verbatim OSCAL 1.2.1 schema fragments with their constraints
six-questions.json the six questions and the answer matrix, the central claim set
pattern-examples.json the two rules, written in all three shapes. Ours
oscal-artifacts.json what each of the three groups has published, counted
- criteria.json the fifteen evaluation criteria, verbatim from the pre-read
- criteria-fill.json the forty-five cells, answered from the files
+ examples.json committed local fingerprints and pinned public links
+ criteria.json the 15 evaluation criteria, maintained as analysis content
sources.json the guidance read as input, one row per benchmark
source-files.json every file under sources/, generated, with size and type
views.json the three views of what a rule is
glossary.json the vocabulary, including the terms the group has not
settled. Rendered as term cards in place; there is no
glossary page
- questions.json the evidence register, the open questions, and their sources
- quotes.json the record of what was said. Retained, and never rendered
+ questions.json editorial open questions and their reasoning, in four sections
corpus-stats.json every figure cited, each with its derivation
provenance.json generated
tools/
+ source-lock.json tracked local inventories and pinned public archive metadata
+ source_inputs.py explicit public fetch and offline input integrity checks
manifest.yaml the declarative extract manifest
extract.py builds data/snippets and data/provenance.json
pattern_examples.py builds data/pattern-examples.json, the site's own encodings
+ copy_examples.py builds data/examples.json from verified source inputs
oscal_artifacts.py builds data/oscal-artifacts.json from the three corpora
sources_files.py builds data/source-files.json from sources/
diagrams.py builds the published SVGs in assets/diagrams from data/
@@ -278,141 +369,132 @@ tools/
axe_run.mjs serves the site and runs axe-core over every page
```
-Eight of those are generators and the files they produce must not be edited by
-hand: `data/snippets/*.json` and `data/provenance.json`,
-`data/pattern-examples.json`, `data/oscal-artifacts.json`,
-`data/source-files.json`, `assets/diagrams/*.svg`, `data/criteria-fill.json`, the
-three approach pages, and `assets/bundle.js`. The workflow regenerates all of
-them and fails if the result differs from what was committed.
-
-`tools/diagrams.py` builds 19 diagrams and writes 9. The other 10, the base layer
-map, the three stakeholder variants and the rest, were only ever on a component
-gallery that has been removed. The builders are kept, because the drawing code
-belongs in one place, and the `PUBLISHED` constant at the foot of the file is the
-list of what reaches `assets/diagrams/`. Add a name there to publish one.
+Nine tools run in the regeneration pipeline. Do not hand-edit generated files:
+`data/snippets/*.json` and `data/provenance.json`,
+`data/pattern-examples.json`, `data/examples.json`, `data/oscal-artifacts.json`,
+`data/source-files.json`, `assets/diagrams/*.svg`, the
+three approach pages, `scenario.html`, and `assets/bundle.js`. The workflow regenerates the files
+and fails on differences from committed versions.
+The local files under `examples/` are authoritative inputs, not disposable
+generator output; their committed fingerprints must already pass source checks
+before regeneration.
+
+`tools/diagrams.py` builds 19 diagrams and writes 9. The remaining 10 appeared
+only in a removed component gallery, including the base layer map and three
+stakeholder variants. The builders remain together in the drawing code.
+`PUBLISHED`, at the foot of the file, lists diagrams written to
+`assets/diagrams/`. Add a diagram name to `PUBLISHED` to publish the diagram.
## Editorial policy
-Thirteen rules govern every page. They live in section 3 of the development
-plan, `TFG-Rules-and-Checks-Site-Plan.md`, including the seven that a later
-decision superseded in part. They were also published on the site, on a
-methodology page that has since been removed. The load-bearing ones:
+Thirteen rules govern every page, as recorded in section 3 of the development
+plan, `TFG-Rules-and-Checks-Site-Plan.md`. A later decision partly superseded
+seven rules. The rules also appeared on the removed methodology page. Key rules:
-- **The site authors no evaluation criteria.** The fifteen come from the pre-read
- unchanged. Their arithmetic is checked on every build, and their wording is
- checked against the pre-read on any build that can reach it.
+- **The 15 criteria and open questions are maintained as analysis content.**
+ Checks validate structure and mappings; editorial review assesses the wording
+ and whether the questions fairly address each approach.
- **The site carries no quotations and names nobody.** Every characterization
- traces to a JSON pointer into a published file, or to the document the claim
- comes from. Structural names and option letters only. `tools/pagecheck.js`
- enforces it per page, over rendered prose rather than markup, with a file path
- exempt because a path is provenance. **`oscal-artifacts.html` is exempt by
- name**, and is required to name publishers rather than merely permitted to: an
- inventory of who published what is useless with the publisher redacted, and
- that page weighs nothing and states no position. Every other page is held to
- the rule.
-- **Equal budget is enforced by construction**, not by judgement. One generator
- writes the three approach pages and refuses to write them if their word counts
- differ by more than ten per cent.
-- **Non-verbal encoding counts as editorializing.** A badge, a hollow cell or a
- hatch fill argues in a channel a word count cannot see, so every annotation type
- applies to all three approaches or to none.
+ of published content traces to an OSCAL example at a declared JSON pointer.
+ Editorial questions and modelling choices are identified as analysis. Use
+ structural names and option letters only. `tools/pagecheck.js` checks rendered
+ prose per page, exempting file paths as provenance.
+ Guidance publishers and source paths remain identified for provenance;
+ the artifact inventory describes published content, not proponent positions.
+- **Equal budget is enforced by construction.** One generator writes the three
+ approach pages and rejects word-count differences above ten per cent.
+- **Non-verbal encoding counts as editorializing.** Badges, hollow cells, and
+ hatch fills convey arguments outside word counts. Every annotation type
+ applies to all three approaches or none.
- **Consequences, not verdicts.** State the cost; let the reader price it.
- **Every figure carries its denominator**, and every figure is recomputed from
the corpora on every build.
-One rule could not be met. Rule 5 asks for the same number of extracts on each
-approach page, which is unreachable for a structural reason rather than an
-editorial one: an unanswered question has nothing to extract, and a corpus that
-answers a question with one construct needs one extract where a corpus that
-answers it with three needs three. The counts today are 1, 1 and 2. Each page
-states its own count and the reason instead, in identical wording, and says that
-the count is not a measure of how well documented an approach is. The departure is
-stated on each page rather than quietly met in a weaker form.
+Equal budgets apply to the authored comparison, not to the volume of evidence
+a publisher happens to supply. Published extracts are selected to support claims;
+extract counts do not measure documentation quality or rank the approaches.
## Contributing a correction
-**If something about your approach is stated wrongly here, that correction is
-more valuable than anything else you could send.** Open an issue or a pull
-request. Corrections are published on the site, unedited, with the correction
-attributed to whoever made it.
-
-Four kinds are worth more than the others, and none of them is a matter of
-opinion:
-
-1. **A characterization of your approach that is wrong.** Section 7 of each
- approach page states the case for that approach as its proponents would state
- it. If it is not the case you would make, say so; that is the one thing no
- check on this site can catch.
-2. **An encoding written in the wrong shape.** The JSON on the question pages is
- ours, not yours: two rules written out in each approach's shape so the columns
- are comparable. The build checks that the shape is well formed, uses real
- identifiers and invents no namespace. It cannot check that it is the shape you
- would actually write, and that is the correction worth the most.
-3. **An extract that is unrepresentative.** Every extract is provably what the
- file says at the pointer declared. Whether it is the right fragment to show is
- a judgement, and the site's author made it.
-4. **A figure that is out of date.** Every count is recomputed from the corpora
- on each build, so a figure here is what the files said when they were read. If
- a publisher has since corrected one, that is worth reporting.
-
-If an extract looks wrong, run `python tools/verify.py --snippets`. If that
-passes and it still looks wrong, the manifest pointer is aimed at the wrong
-place, which is a real defect. If an encoding looks wrong, the defect is in
-`tools/pattern_examples.py` rather than in a pointer, and
-`python tools/verify.py --example` is the check that covers it.
-
-A criterion cannot be added here. Editorial rule 4 forbids the site from
-authoring evaluation criteria, so a sixteenth goes to the working group and this
-site follows.
+**Report mischaracterizations of an approach through an issue or pull request.**
+Corrections are published unedited and attributed to the contributor.
+
+Priority correction types:
+
+1. **Mischaracterization of an approach.** Section 7 of each approach page
+ presents the proponents' case. Proponents should report differences from the
+ intended argument; automated checks cannot establish agreement.
+2. **Incorrect encoding.** The analysis authors encoded two rules in each
+ approach's structure for comparison. The build checks structure, published
+ identifiers, and absence of invented namespaces, but cannot confirm that
+ proponents would use the same encoding.
+3. **Unrepresentative extract.** Verification proves the extract matches the
+ declared file pointer. Selecting a representative fragment remains an
+ editorial judgement by the analysis author.
+4. **Outdated figure.** Counts are recomputed from the corpora on each build.
+ Report publisher corrections made since the files were read.
+
+For a suspected extract error, run `python tools/verify.py --snippets`. A
+passing check with an unrepresentative extract indicates a manifest-pointer
+selection defect. Encoding defects belong in `tools/pattern_examples.py`, not
+the manifest; run `python tools/verify.py --example` to check encodings.
+
+Submit changes to the 15 evaluation criteria or open questions for analysis
+review, and update their structural checks when the agreed structure changes.
## Adding a fourth approach
-The site is built so that this is a data change and a page, not a rewrite.
+Adding an approach requires data changes and a page, not a site rewrite.
-1. **Add the corpus.** Put the published files where `corpora_root` in
- `tools/manifest.yaml` can reach them.
+1. **Define the source inputs.** Extend [tools/source-lock.json](tools/source-lock.json)
+ and [tools/source_inputs.py](tools/source_inputs.py) together, with tests,
+ to authorize the new local inventory or pinned public archive. Record
+ fingerprints and publisher terms; never rely on a personal folder or upload
+ a private corpus. Prepare public inputs explicitly and check them offline.
2. **Declare the extracts.** Add manifest entries with a source file, an RFC 6901
- pointer, and the question each one illustrates. Run `python tools/extract.py`.
-3. **Add the approach to `data/six-questions.json`.** One entry under `approaches` with
- a structural name, an option letter, a primary model, which of the three views
- of a rule its proponents hold, which reader it serves first, and its status
- annotation. Then one `matrix` cell for each of the seven question rows, each
- with a state, a note that becomes its tooltip, and the extracts that evidence
- it. An unanswered cell must say which of the three kinds of unanswered it is.
-4. **Write the two rules in your shape.** Add a fourth column to
+ pointer, and the illustrated question. Run `python tools/extract.py`.
+3. **Add the approach to `data/six-questions.json`.** Add an `approaches` entry
+ with a structural name, option letter, primary model, proponents' view of a
+ rule among the three views, primary reader, and status annotation. Add a
+ `matrix` cell for each of the seven question rows, with a state, tooltip note,
+ and supporting extracts. Classify unanswered cells using one of the three
+ unanswered states.
+4. **Encode the two rules in the approach's structure.** Add a fourth column to
`tools/pattern_examples.py`: the same two rules, in the same order, for every
- question row the approach answers, each block naming the OSCAL construct that
- carries it and carrying your own namespace on any property that needs one. A
- question the approach answers with nothing gets no block.
+ answered question row. Each block names the containing OSCAL construct and
+ uses the approach's namespace on properties requiring a namespace.
+ Unanswered questions receive no block.
5. **Add a one-line summary** to the same `data/six-questions.json` entry, within
ten per cent of the length of the others.
6. **Add the page content** to `tools/approach_pages.py`: the gist, the per-question
- prose, the case and the questions against it, and the three status sentences.
- The generator supplies the structure and refuses to write pages that break the
- budget.
+ prose, the case for the approach, questions about the approach, and three
+ status sentences. The generator supplies the structure and rejects pages
+ exceeding the budget.
7. **Regenerate and verify.** Run the generators in the order given under *How the
content is produced*, then `python tools/verify.py --all`.
-The checks will tell you what is missing. `--matrix` will reject an unclassified
-cell, `--example` will reject a column whose rules do not match the others,
-`--budget` will reject an unequal page, and `--criteria` will reject a criteria
-table that does not answer all fifteen for the new approach.
+Checks identify omissions: `--matrix` rejects unclassified cells, `--example`
+rejects columns with mismatched rules, `--budget` rejects unequal pages, and
+`--criteria` validates the 15 criteria and their mappings to question rows.
-Two more things. The inventory page needs a fourth entry in the `PUBLISHERS` list
-in `tools/oscal_artifacts.py`, naming the corpus directory and the option letter;
-everything else on that page is counted off the files and nothing about it is
-described by hand. And `sources/` lists the hardening guidance read as input, not
-the OSCAL written from it, so a new corpus does not go there.
+Add a fourth entry to `PUBLISHERS` in `tools/oscal_artifacts.py`, naming the
+corpus directory and option letter. The inventory derives the remaining content
+from files rather than hand-authored descriptions. Keep the OSCAL corpus outside
+`sources/`, which lists input hardening guidance, not derived OSCAL content.
## License
-CC BY 4.0. See `LICENSE`. The site's own text, diagrams and encodings are under
-that licence.
-
-Nothing else here is. The three OSCAL corpora belong to their publishers and are
-not redistributed; only extracts at declared pointers, with provenance in
-`data/provenance.json`. Under `sources/`, the DISA material is a work of the
-United States Government; the CIS Benchmarks are here on the publisher's
-participation in this review rather than on a grant in their Agreed Terms of
-Use, which is why that basis is written on each of those files rather than
-assumed. Each file in `data/source-files.json` carries its own terms.
+CC BY 4.0 applies to analysis-authored text, diagrams, and encodings. See
+`LICENSE`.
+
+The licence does not cover source material. The OSCAL corpora belong to their
+publishers. The 6 IBM and 18 Easy Dynamics JSON files already committed under
+`examples/` are source inputs; AWS documents are linked at the pinned public
+revision and cached only for build-time verification. Extracts retain declared
+pointers and provenance in `data/provenance.json`. Source preparation does not
+authorize additional redistribution or uploading a private corpus.
+Under `sources/`, DISA
+material is a work of the United States Government. CIS Benchmarks are included
+on the basis of publisher participation in the review, not a grant under the
+Agreed Terms of Use. Each CIS file states the basis for inclusion.
+`data/source-files.json` records terms for each file.
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/analysis.json b/docs/analysis/2026-08-automating-technical-hardening-guidance/analysis.json
index 09072b0..ea375c1 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/analysis.json
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/analysis.json
@@ -26,8 +26,8 @@
],
"corpora": {
- "repository": "OSCAL-Foundation/tfg-automated-assessments",
- "note": "Read by the build through TFG_CORPORA. Not vendored here: every extract on the site is re-derived from it and diffed on each run."
+ "source_lock": "tools/source-lock.json",
+ "note": "Repository-defined inputs: 6 committed IBM and 18 committed Easy Dynamics JSON files, checked against data/examples.json fingerprints, plus 231 public AWS JSON files from the pinned archive and verified cache declared in the lock. Prepare explicitly with python tools/source_inputs.py --fetch; python tools/source_inputs.py --check verifies inputs offline. Missing or corrupt inputs fail rather than being skipped or counted as empty."
},
"verification": {
diff --git a/docs/analysis/2026-08-automating-technical-hardening-guidance/assessment-first.html b/docs/analysis/2026-08-automating-technical-hardening-guidance/assessment-first.html
index 7dce04a..80ece04 100644
--- a/docs/analysis/2026-08-automating-technical-hardening-guidance/assessment-first.html
+++ b/docs/analysis/2026-08-automating-technical-hardening-guidance/assessment-first.html
@@ -4,16 +4,16 @@
Assessment-first | Automating Technical Hardening Guidance with OSCAL
-
+
-
+
-
+