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 `