diff --git a/AGENTS.md b/AGENTS.md index 4843871..7b3f89d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,285 +1,133 @@ -# Instructions For AI Agents - -## Primary Scope - -When analyzing this repository, focus on only these files: - -- [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) -- [schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json) - -The rest of the repository is supporting infrastructure. The `tools` directory, -tests, and READMEs can help with validation and orientation, but they are not -the rules and should not be treated as authoritative rule content. - -## Source Of Truth - -[fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) is the -source of truth for the FedRAMP Consolidated Rules for 2026. - -[schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json) -is the source of truth for the expected data shape. - -## Rules JSON Edit Guardrail - -Do not modify -[fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) unless the -user specifically instructs you to edit that file. - -If a task appears to require changing -[fedramp-consolidated-rules.json](fedramp-consolidated-rules.json), stop before -editing it. Propose a concise plan that identifies the specific rule, -definition, indicator, metadata, or structural paths you intend to change, then -wait for the user's explicit confirmation before making those edits. - -Analysis, validation, structured reads, and reports may use -[fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) without -additional permission. The guardrail applies to file modifications. - -## Test Creation Guardrail - -When the user asks to add or update tests for the tooling, test harness, or -validation behavior, assume the requested test may expose existing rules data -issues, warnings, or intentionally failing cases. That is often the reason the -test is being added. - -Do not fix test failures or warnings by editing -[fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) unless the -user explicitly asks for rule-content changes. If a newly added test reports -errors or warnings against the current rules file, report the result and keep -the change scoped to test or tooling support. - -If a test cannot be made meaningful without changing the rules JSON, stop before -editing it. Explain the specific rule, definition, indicator, metadata, or -structural path that would need to change and wait for explicit confirmation. - -## Dataset Structure - -The JSON file has four top-level sections: - -- `info` - Dataset metadata, including title, description, version, `last_updated`, and - default artifact expectations. -- `FRD` - FedRAMP Definitions. Use these definitions to resolve terms used in rules and - indicators. -- `FRR` - FedRAMP Rules process documents. These contain process-oriented requirements - and recommendations. -- `KSI` - Key Security Indicators. These describe security capabilities and evidence - expectations. - -### FRD - -`FRD` entries are controlled definitions. Definition IDs follow `FRD-XXX`. -Important fields include `term`, `definition`, `alts`, references, notes, and -`updated` history. - -The FRD data container uses applicability buckets. Shared definitions live under -`FRD.data.all`; framework-specific definitions, if present, live under -`FRD.data.20x` or `FRD.data.rev5`. - -FRD effective metadata may be common (`FRD.info.effective`) or split into -paired framework-specific blocks (`FRD.info.20x.effective` and -`FRD.info.rev5.effective`). - -When a defined term appears in an FRR rule or KSI indicator, use the FRD -definition instead of assuming the plain-language meaning. - -### FRR - -`FRR` is keyed by process short names such as `VDR`, `FRC`, `CCM`, and `SCN`. -Each process contains: - -- `info` - Rule metadata, purpose, status, effective metadata, subset definitions, and - optional flow descriptions. Effective metadata may be common - (`info.effective`) or split into paired framework-specific blocks - (`info.20x.effective` and `info.rev5.effective`). Subsets and flows may also - be common or framework-specific. -- `data` - The rule tree. - -The rule tree is organized as: - -```text -FRR -> process -> data -> applicability -> subset -> requirement ID -``` - -Applicability keys are `all`, `20x`, and `rev5`. Subsets identify actors, -scopes, or process buckets. Requirement IDs follow the -`PROCESS-SUBSET-KEY` pattern, such as `VDR-CSO-123`. - -Each requirement contains either: - -- a single `statement` and `force`, or -- a `varies_by_class` object with class-specific statements and force values. - -Class-specific variants may also include `following_information`, `artifacts`, -notes, effective dates, simple timeframes, and `pain_timeframes`. - -Other useful top-level fields include `affects`, `controls`, `artifacts`, -`following_information`, `following_information_bullets`, `examples`, -`notification`, simple timeframes, terms, related rule references, references, -corrective actions, effective dates, and `updated` history. - -### KSI - -`KSI` is keyed by security theme short names such as `IAM`, `CNA`, `MLA`, and -`SCR`. Indicator IDs follow `KSI-THEME-KEY`. - -Indicators describe security capabilities. They include statements or -class-specific variants, mapped controls, optional artifact expectations, -terms, references, and update history. - -## Analysis Best Practices - -- Parse the JSON with a real JSON parser. Do not analyze it with ad hoc text - matching when structured access is practical. -- Validate the rules file against the schema before relying on automated - analysis. -- Select the correct applicability path: `all`, `20x`, or `rev5`; `all` - means shared across frameworks. -- Check common `info.effective` or the framework-specific - `info.20x.effective` / `info.rev5.effective` before deciding whether a rule - applies to a framework or timeline. -- Check each document `status`; `placeholder` and `empty` content should be - treated differently from `stable` content. -- Resolve relevant terms through `FRD`. -- Resolve FRR subset definitions from common `info.subsets` plus any matching - framework-specific `info.20x.subsets` or `info.rev5.subsets`. -- Respect `varies_by_class` before applying a rule to a specific service class, - including class-specific following information, artifacts, notes, and - timeframes. -- Treat `MUST` and `MUST NOT` as hard requirements, `SHOULD` and `SHOULD NOT` - as expected practices with possible justified exceptions, and `MAY` as - optional or permitted behavior. -- Cite stable IDs for every finding, mapping, or recommendation. -- Use `affects`, `controls`, `artifacts`, `default_artifacts`, notifications, - related rule references, and timeframes as mapping signals. They are aids for - analysis, not replacements for the rule statement. -- Distinguish evidence found, evidence missing, and conclusions inferred from - evidence. Do not claim compliance from silence. - -## Cloud Code, Codex, And MCP Analysis - -For cloud code, infrastructure-as-code, Codex workflows, and MCP servers, use -the rules as a structured mapping source: - -- Start with KSI themes for capability review: - `IAM` for identity and access, `MLA` for monitoring and auditing, `SVC` for - service configuration, `CNA` for cloud-native architecture, `CMT` for change - management, `SCR` for supply chain risk, `INR` for incident response, and - `RPL` for recovery planning. -- Use FRR documents for process obligations such as vulnerability response, - significant changes, certification, continuous monitoring, incident - communication, cryptographic modules, and marketplace listing. -- For code repositories, map rule and indicator IDs to concrete evidence: - configuration files, IaC modules, CI workflows, policy files, access-control - definitions, logging configuration, vulnerability workflows, dependency - manifests, deployment pipelines, and operational runbooks. -- For Codex-style agents, produce traceable outputs: scope, assumptions, - matched IDs, evidence paths, missing evidence, confidence, and recommended - next actions. -- For MCP servers, pay particular attention to tool permissions, - authentication, authorization, audit logging, secret handling, data boundary - controls, dependency provenance, and incident reporting paths. -- Prefer narrowly scoped findings with exact citations over broad claims about - FedRAMP readiness. - -## Changelog Generation - -When asked to generate a changelog for the active branch, produce a screen-only -summary of the branch delta against `main`; do not create a changelog file -unless the user explicitly asks for one. - -- Output the changelog as copy/pasteable Markdown. When responding in chat, - place the changelog itself inside a fenced `markdown` code block; keep any - explanatory notes outside the block. -- Use plain repository paths inside the changelog instead of clickable Markdown - file links so the copied text remains portable. -- Use the branch merge base with `main` as the starting point and the current - branch tip as the ending point. Prefer `git diff main...HEAD`, - `git diff --name-status main...HEAD`, and - `git log --reverse --format='%h %s' main..HEAD`. -- If `main` is missing or stale and network access is available, fetch it first; - otherwise state which local ref was used. -- Treat committed branch changes as the changelog scope by default. Mention - uncommitted workspace changes separately only when they affect the requested - analysis or the user asks to include them. -- Validate the rules file against the schema before relying on automated JSON - analysis. If validation cannot be run, say so and continue carefully. -- Parse JSON with a real JSON parser when comparing - [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) and - [schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json); - avoid text-only diff analysis for rule content whenever structured access is - practical. -- Compare the initial branch state to the final branch state, not commit by - commit, unless a commit-level explanation is specifically requested. -- Detect and highlight breaking changes when summarizing underlying changes to - [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) or the - schema. Use the software compatibility meaning of breaking change: a - backwards-incompatible change to the machine-readable public contract that - would make existing parsers, validators, exporters, queries, or integrations - fail, reject previously valid data, silently misread data, or require code - changes to continue processing the dataset. Examples include renamed or - removed properties such as `primary_key_word` to `force`, changed required - fields, changed property types, changed statement shapes, changed ID formats, - controlled vocabulary changes that invalidate existing values, renamed - top-level sections, renamed applicability or subset bucket keys when those - keys are part of the schema contract, or stricter validation rules that reject - files accepted by the previous schema. -- Do not mark rule-content taxonomy changes as breaking merely because a rule, - definition, or indicator moves to a different ruleset, process, applicability - path, subset, or ID. Treat those as Rules Content Changes and describe the - user-visible mapping or migration impact. Only mark such movement as breaking - when it also changes the documented data shape, schema vocabulary, required - fields, or other machine-readable contract in a way that breaks existing - tooling. -- Mark every breaking change bullet with `**Breaking:**` at the start of the - bullet in the relevant changelog section. Include the old shape and the new - shape when known, and briefly state the practical impact. For example, - changing FRR metadata from `info.labels` to `info.subsets` is breaking - because tools or consumers that still look for `labels` will fail to find the - declarations and may reject or misread the FRR data until updated. -- Use stable IDs in every rule-content bullet: `FRD-XXX`, `FRR` requirement IDs - such as `VDR-CSO-123`, and `KSI-THEME-KEY`. -- For each substantively changed rule, definition, or indicator, write one - sentence describing the user-visible change. Include additions, removals, - renamed terms, wording changes, actor/scope changes, applicability moves, - artifact changes, control mappings, examples, notifications, related rule - references, external references, timeframes, and class-specific variants. -- Group purely mechanical metadata churn, such as mass `updated` date resets or - property ordering changes, instead of listing every affected rule separately. -- Separate evidence from inference. When a conclusion comes from schema shape, - property names, or structural movement rather than explicit wording, label it - as structural. -- Use exactly these changelog sections, in this order: - 1. `Rules Content Changes` - Summarize changes inside `fedramp-consolidated-rules.json` itself. Focus - on rule, definition, indicator, FRR document, and metadata meaning changes. - 2. `Schema And Structure Changes` - Summarize changes to - `schemas/fedramp-consolidated-rules.schema.json` and corresponding - structural changes in the rules JSON, such as top-level `info` changes, - property additions, renamed applicability buckets, required fields, - controlled vocabularies, and object shapes. - 3. `Tooling And Test Changes` - Summarize support-code changes, CLI behavior, validators, fixers, - package scripts, test harnesses, and test coverage. -- Keep bullets simple and high signal. Prefer a single line per bullet unless - the change is complex enough that a short second sentence prevents ambiguity. -- End with a brief validation note naming the commands run, such as - `bun run check`, or explain why validation was not run. - -## Editing Guidance - -If asked to edit the rules: - -- Edit [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) and, - only when necessary, the schema. -- Keep IDs stable unless the requested change requires a new or corrected ID. -- Preserve schema-driven property order. -- Update `updated` history when changing rule, definition, or indicator - meaning. -- Run the tooling checks when available. +# Instructions For Information Analysis + +## Start Here + +Use these two authoritative files: + +- [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json): the + FedRAMP Consolidated Rules for 2026, including definitions and indicators. +- [schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json): + the expected data shape and allowed values, using JSON Schema Draft 2020-12. + +Default to read-only analysis. Parse the JSON with a real JSON parser and +validate it against the local schema before relying on automated analysis. +If validation fails or cannot be run, disclose that limitation and avoid +unsupported conclusions. Read the relevant entries with their surrounding +metadata; this guide is a navigation aid, not a substitute for the source. + +The `tools/` directory is only relevant to FedRAMP developers during project +maintenance; most users and information-analysis agents should ignore it. +For maintenance tasks, including edits, tooling support, or branch changelogs, +first read [tools/AGENTS-TOOLS.md](tools/AGENTS-TOOLS.md). + +## Locate The Information + +The schema requires four top-level sections; the current dataset also includes +the optional `CTL` section: + +| Section | Contents | Lookup path | +| ---------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- | +| `info` | Dataset title, description, version, update date, and default artifacts | `info` | +| `FRD` | Controlled definitions and their metadata | `FRD.data..` | +| `FRR` | Process documents, requirements, and recommendations | `FRR..data...` | +| `KSI` | Security themes and indicators | `KSI..indicators.` | +| `CTL` (optional) | Control guidance and parameters | `CTL..` | + +For `CTL`, read each control's common `guidance` and `parameters` and any +`varies_by_class` entries. Schema support does not imply that every optional +field or class variant is populated; inspect the JSON before drawing conclusions. + +**Definitions:** IDs follow `FRD-XXX`, such as `FRD-ACV`. Read `term`, +`definition`, `alts`, and any notes or references. Use the FRD meaning whenever +a defined term appears in a rule or indicator; use plain-language meaning when +no definition exists. Shared definitions are in `FRD.data.all`; the schema also +allows framework-specific definitions in `FRD.data.20x` and `FRD.data.rev5`. +Definition IDs are object keys, not an `id` field in each definition. + +**Process rules:** Process keys include `VDR`, `FRC`, `CCM`, and `SCN`. +Each process has `info` metadata and a `data` tree. Subsets identify actors, +scopes, or process buckets. Requirement IDs follow `PROCESS-SUBSET-KEY`, with +three-character segments; the final segment can contain letters or digits. +For example, `AFC-FRP-VRE` is at `FRR.AFC.data.all.FRP.AFC-FRP-VRE`. +Requirement IDs are object keys. + +**Security indicators:** Theme keys include `IAM`, `CNA`, `MLA`, and `SCR`. +Indicator IDs follow `KSI-THEME-KEY`, such as `KSI-CED-RAT` at +`KSI.CED.indicators.KSI-CED-RAT`. Theme metadata, including `status`, lives +directly on the theme. KSI does not use FRR's `info`/`data`/subset hierarchy, +and KSI indicators and their class variants do not have a `force` field. + +## Interpret Applicability And Meaning + +1. **State the scope.** Record `info.version` and `info.last_updated`, the + framework (`20x` or `rev5`), certification path, service class, actor, and + relevant date. Identify unknowns that could change the answer. +2. **Include shared content.** For FRD and FRR, consider `all` plus the matching + framework bucket when present. `all` means shared across frameworks, not + universally applicable to every actor or class. Resolve FRR subsets from + common `info.subsets` plus matching `info.20x.subsets` or + `info.rev5.subsets`. Read their descriptions and `applicability.types`, + `paths`, `classes`, and `affects`, together with each requirement's `affects`. + Preserve schema vocabulary and case: for example, the bucket `rev5` differs + from the certification type value `Rev5`. +3. **Check status and timing.** FRD and FRR status is under their document + `info.status`; KSI status is `KSI..status`. Distinguish `stable`, + `placeholder`, and `empty`. For FRD and FRR, effective metadata is either + common `info.effective` or paired `info.20x.effective` and + `info.rev5.effective`. Read `is` (`required`, `optional`, or `no`), comments, + warnings, and the separate obtain, maintain, optional-adoption, and grace + dates. Check entry-level and class-specific `effective_date` where present. + Neither `stable` nor an update date alone establishes current applicability. +4. **Select the statement shape.** FRR has either top-level `statement` and + `force`, or `varies_by_class` with statements and forces inside each class. + KSI has either a top-level `statement` or class-specific statements. + Class keys are lowercase `a`, `b`, `c`, and `d`; not all are necessarily + present. Do not invent missing variants or copy another class's statement. + Read class-specific following information, notes, artifacts, control lists, + effective dates, and timeframes where the schema permits them, together with + the entry's common information. +5. **Respect the force.** In FRR, `MUST` and `MUST NOT` are hard requirements; + `SHOULD` and `SHOULD NOT` are expected practices with possible justified + exceptions; `MAY` is optional or permitted behavior. Interpret KSI through + its capability statement and applicable process rules without inventing a + normative force. +6. **Read the supporting details.** Include following information and bullets, + notes, examples, corrective actions, notifications, references, related IDs, + and timeframes as relevant. Consult `info.default_artifacts.FRR` or + `info.default_artifacts.KSI` and applicable entry/class `artifacts` buckets + (`all`, `20x`, `rev5`). Control mappings and artifact lists are analysis + signals; they do not replace the statement or prove implementation. + +## Produce Traceable Analysis + +Cite stable definition, rule, or indicator IDs and relevant JSON paths for each +finding, mapping, or recommendation. For document or dataset metadata, cite its +exact path. Resolve related IDs and terms from the dataset instead of guessing. + +When reviewing a system, codebase, infrastructure configuration, or operational +process, map IDs to concrete evidence such as configuration, access controls, +logs, tests, policies, or runbooks. State evidence found, evidence missing, and +conclusions inferred, with assumptions, confidence, and next actions where +useful. Prefer narrowly scoped findings; do not claim compliance from silence +or from a control mapping alone. + +## Additional Context + +Use these resources when the analysis needs information beyond this dataset: + +- [FedRAMP/2026](https://github.com/fedramp/2026): narrative text and the website + project accompanying the structured rules. +- [FedRAMP/2026-markdown](https://github.com/fedramp/2026-markdown): generated + Markdown combining structured rules and narrative text for reading and AI + ingestion; `_sources.json` records the source commits. +- [FedRAMP community discussions](https://github.com/FedRAMP/community/discussions/): + community questions, announcements, and discussion. +- [FedRAMP 2026 discussions](https://github.com/FedRAMP/2026/discussions/): + discussion associated with the 2026 project. +- [FedRAMP Help](https://help.fedramp.gov): help articles and support information. + +Cite the specific page, discussion, or comment when using external context, +and distinguish participant opinions or proposals from published requirements. +Compare source commits and dates with the dataset version; generated content +and discussions may describe a different revision. Report discrepancies rather +than silently replacing local rule content with external text. diff --git a/README.md b/README.md index 567761e..99225d3 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,56 @@ # FedRAMP Consolidated Rules This repository contains the machine-readable FedRAMP Consolidated Rules for -the 2026. +2026. Use it to read, analyze, and integrate structured definitions, process +rules, and security indicators. -The source of truth is: +## Repository Contents -- [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) +- [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) is the + canonical rules dataset. It contains dataset metadata (`info`), FedRAMP + Definitions (`FRD`), FedRAMP Rules (`FRR`), Key Security Indicators (`KSI`), + and control guidance and parameters (`CTL`, an optional schema section). - [schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json) + defines the dataset's expected structure, required fields, and allowed values. -Everything else in this repository supports those two files. +The JSON defines the rule content; the schema defines its machine-readable +shape. Other files in this repository provide supporting documentation and +maintenance infrastructure. -## What Is Here +## Using The Information -- [fedramp-consolidated-rules.json](fedramp-consolidated-rules.json) - The canonical rules dataset. -- [schemas/fedramp-consolidated-rules.schema.json](schemas/fedramp-consolidated-rules.schema.json) - The schema for the dataset. -- [AGENTS.md](AGENTS.md) - Guidance for AI agents analyzing the dataset. -- [tools](tools) - Validation, normalization, tests, and export tooling. +Start with the dataset and schema for structured analysis. Definitions explain +terms used in the rules. Process rules describe requirements and recommendations; +security indicators describe capabilities and evidence expectations. Account for +framework applicability, service class, document status, and effective dates +when interpreting the information. + +**AI agents:** Read [AGENTS.md](AGENTS.md) before ingesting or analyzing the +information. For maintenance tasks, also read +[tools/AGENTS-TOOLS.md](tools/AGENTS-TOOLS.md). + +## Related Resources -## Working With The Repository +- [FedRAMP/2026](https://github.com/fedramp/2026) contains the narrative content + and website project that accompanies the structured rules. +- [FedRAMP/2026-markdown](https://github.com/fedramp/2026-markdown) provides + generated Markdown combining the structured rules and narrative content for + direct reading and AI ingestion. Its `_sources.json` records source commits. +- [FedRAMP community discussions](https://github.com/FedRAMP/community/discussions/) + and [FedRAMP 2026 discussions](https://github.com/FedRAMP/2026/discussions/) + provide additional discussion and context. +- [FedRAMP Help](https://help.fedramp.gov) provides help articles and support. -Use the JSON file and schema for analysis. +Related resources can reflect different revisions. Check their source versions +and dates when comparing them with this dataset. -From [tools](tools), the primary maintenance commands are: +## Maintenance -```bash -bun run check -bun run fix -``` +The [tools/](tools/) directory is internal maintenance infrastructure for +FedRAMP developers. Most users and agents analyzing the information should +ignore it; installing or running these tools is not required to consume the +dataset. -See [tools/README.md](tools/README.md) for the tooling workflow and -[AGENTS.md](AGENTS.md) for agent-focused analysis guidance. +FedRAMP developers can use [tools/README.md](tools/README.md) for setup, +validation, normalization, tests, exports, and Git hooks. Maintenance agents +must also follow [tools/AGENTS-TOOLS.md](tools/AGENTS-TOOLS.md). diff --git a/fedramp-consolidated-rules.json b/fedramp-consolidated-rules.json index feb4009..9760964 100644 --- a/fedramp-consolidated-rules.json +++ b/fedramp-consolidated-rules.json @@ -2,8 +2,8 @@ "info": { "title": "FedRAMP Consolidated Rules for 2026", "description": "This datafile contains the Consolidated Rules for FedRAMP in structured machine-readable text. It includes definitions, requirements, recommendations, and key security indicators.", - "version": "2026.07.14.01", - "last_updated": "2026-07-14", + "version": "2026.09.13.01", + "last_updated": "2026-09-13", "default_artifacts": { "FRR": [ "Explanation of how the rule is followed, or an explanation of the reason and resulting risk to customers for not following the rule.", @@ -1654,11 +1654,15 @@ "name": "Agency Liaison Program", "statement": "Agencies SHOULD assign at least 1 federal employee to be an active participant in the FedRAMP Agency Liaison program.", "reference": "Agency Liaison Program", - "reference_url": "https://www.fedramp.gov/preview/2026/agencies/support/liaisons", + "reference_url": "https://www.fedramp.gov/2026/agencies/support/liaisons", "force": "SHOULD", "affects": ["Agencies"], "terms": ["Agency"], "updated": [ + { + "date": "2026-09-13", + "comment": "Fixed broken reference URL for the Agency Liaison Program." + }, { "date": "2026-06-24", "comment": "Official launch of the FedRAMP Consolidated Rules for 2026." @@ -1686,7 +1690,7 @@ "statement": "Agencies MUST complete the Authorization to Operate process for federal information systems that use FedRAMP Certified cloud service offerings.", "note": "FedRAMP provides technical assistance to help agencies navigate this process.", "reference": "Using a FedRAMP Certified Cloud Service Offering", - "reference_url": "https://fedramp.gov/preview/2026/agencies/use", + "reference_url": "https://www.fedramp.gov/2026/agencies/use", "force": "MUST", "affects": ["Agencies"], "terms": [ @@ -2014,7 +2018,7 @@ "OCR": { "CCM-OCR-AVL": { "name": "Report Availability", - "statement": "Providers MUST supply an Ongoing Certification Report to all necessary parties every 3 months, covering the entire period since the previous summary, in a consistent format that is human readable; this report MUST include high-level summaries of at least the following information:", + "statement": "Providers MUST supply an Ongoing Certification Report to all necessary parties every 3 months, covering the entire period since the previous summary, in a consistent format that is human readable; this report MUST include high-level summaries of at least the following information (if applicable):", "following_information": [ "Changes to FedRAMP Certification Data", "Planned changes to FedRAMP Certification Data during at least the next 3 months", @@ -2037,6 +2041,8 @@ "name": "FedRAMP Ongoing Certification Report (CCM-OCR-AVL)", "url": "https://fedramp.gov/schemas/fedramp-ongoing-certification-report-schema-2026-06-24.json" }, + "timeframe_type": "months", + "timeframe_num": 3, "terms": [ "Accepted Vulnerability", "Agency", @@ -2053,6 +2059,10 @@ "Vulnerability" ], "updated": [ + { + "date": "2026-09-13", + "comment": "Added (if applicable) to clarify that some of these items are not always required depending on the FedRAMP Certification Type or Class." + }, { "date": "2026-06-24", "comment": "Official launch of the FedRAMP Consolidated Rules for 2026." @@ -2305,6 +2315,9 @@ "statement": "Providers SHOULD regularly schedule Quarterly Reviews to occur at least 3 business days after releasing an Ongoing Certification Report AND within 10 business days of such release.", "force": "SHOULD", "affects": ["Providers"], + "timeframe_type": "bizdays", + "timeframe_num_min": 3, + "timeframe_num_max": 10, "terms": [ "FedRAMP Certification Report", "Ongoing Certification", @@ -3260,7 +3273,7 @@ "maintain": "2027-07-01", "optional_adoption": "2026-07-04", "grace": { - "default": "2027-01-01", + "default": "2027-07-01", "until_next_assessment": true } } @@ -3272,7 +3285,7 @@ "applicability": { "types": ["Rev5"], "paths": ["Program", "Agency"], - "classes": ["A", "B", "C", "D"], + "classes": ["B", "C", "D"], "affects": ["Providers"] } } @@ -3543,7 +3556,7 @@ "applicability": { "types": ["Rev5"], "paths": ["Agency"], - "classes": ["A", "B", "C", "D"], + "classes": ["B", "C", "D"], "affects": ["Providers"] } } @@ -5828,7 +5841,7 @@ "name": "Ongoing Incident Reports", "varies_by_class": { "a": { - "statement": "Providers with Class A Certifications SHOULD responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the the following additional information that is available and/or the current relevant status for each item:", + "statement": "Providers with Class A Certifications SHOULD responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the following additional information that is available and/or the current relevant status for each item:", "following_information": [ "Observed incident activity", "Indicators of compromise", @@ -5881,7 +5894,7 @@ } }, "b": { - "statement": "Providers with Class B Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the the following additional information that is available and/or the current relevant status for each item:", + "statement": "Providers with Class B Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the following additional information that is available and/or the current relevant status for each item:", "following_information": [ "Observed incident activity", "Indicators of compromise", @@ -5934,7 +5947,7 @@ } }, "c": { - "statement": "Providers with Class C Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the the following additional information that is available and/or the current relevant status for each item:", + "statement": "Providers with Class C Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the following additional information that is available and/or the current relevant status for each item:", "following_information": [ "Observed incident activity", "Indicators of compromise", @@ -5987,7 +6000,7 @@ } }, "d": { - "statement": "Providers with Class D Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the the following additional information that is available and/or the current relevant status for each item:", + "statement": "Providers with Class D Certifications MUST responsibly notify all affected parties of ongoing activity as new information becomes available during incident response for FedRAMP Reportable Incidents, including updates (or lack of updates) to all previously reported information and as much of the following additional information that is available and/or the current relevant status for each item:", "following_information": [ "Observed incident activity", "Indicators of compromise", @@ -6074,6 +6087,10 @@ "Vulnerability Response" ], "updated": [ + { + "date": "2026-09-13", + "comment": "Removed the extra the in all statements." + }, { "date": "2026-06-24", "comment": "Official launch of the FedRAMP Consolidated Rules for 2026." @@ -7101,6 +7118,8 @@ "related": ["IVV-CSF-PCA"], "force": "MUST", "affects": ["Providers"], + "timeframe_type": "years", + "timeframe_num": 3, "terms": ["FedRAMP Independent Assessment", "Provider"], "updated": [ { @@ -7604,6 +7623,8 @@ ], "force": "MUST", "affects": ["Advisors"], + "timeframe_type": "bizdays", + "timeframe_num": 5, "terms": ["Advisor"], "updated": [ { @@ -7664,6 +7685,8 @@ ], "force": "MUST", "affects": ["Providers"], + "timeframe_type": "years", + "timeframe_num": 2, "terms": ["Certification Class", "Provider"], "updated": [ { @@ -9383,6 +9406,8 @@ "statement": "Providers MUST verify and validate the status of non-machine-based information resources at least once every 3 months.", "force": "MUST", "affects": ["Providers"], + "timeframe_type": "months", + "timeframe_num": 3, "terms": [ "Information Resource", "Machine-Based (Information Resources)", diff --git a/schemas/fedramp-consolidated-rules.schema.json b/schemas/fedramp-consolidated-rules.schema.json index fbf8a33..9f3e053 100644 --- a/schemas/fedramp-consolidated-rules.schema.json +++ b/schemas/fedramp-consolidated-rules.schema.json @@ -607,6 +607,8 @@ }, "timeframe_type": { "$ref": "#/$defs/timeframe_type" }, "timeframe_num": { "$ref": "#/$defs/positive_number" }, + "timeframe_num_min": { "$ref": "#/$defs/positive_number" }, + "timeframe_num_max": { "$ref": "#/$defs/positive_number" }, "notification": { "type": "array", "items": { @@ -631,8 +633,26 @@ "updated": { "$ref": "#/$defs/updated_list" } }, "dependentRequired": { - "timeframe_type": ["timeframe_num"], - "timeframe_num": ["timeframe_type"] + "timeframe_num": ["timeframe_type"], + "timeframe_num_min": ["timeframe_type", "timeframe_num_max"], + "timeframe_num_max": ["timeframe_type", "timeframe_num_min"] + }, + "dependentSchemas": { + "timeframe_type": { + "oneOf": [ + { + "properties": { "timeframe_num": {} }, + "required": ["timeframe_num"] + }, + { + "properties": { + "timeframe_num_min": {}, + "timeframe_num_max": {} + }, + "required": ["timeframe_num_min", "timeframe_num_max"] + } + ] + } }, "additionalProperties": false }, diff --git a/tools/AGENTS-TOOLS.md b/tools/AGENTS-TOOLS.md new file mode 100644 index 0000000..8b27570 --- /dev/null +++ b/tools/AGENTS-TOOLS.md @@ -0,0 +1,190 @@ +# Instructions For Maintenance Agents + +This guide is for AI agents supporting FedRAMP developers during maintenance of +the dataset, schema, tooling, tests, documentation, and branch changelogs. +For information analysis, use the root [AGENTS.md](../AGENTS.md); most consumers +can ignore this directory. + +Read this guide before maintenance work, including work on files outside +`tools/`. It is explicitly linked from the root guide; do not assume the custom +filename `AGENTS-TOOLS.md` is automatically loaded by your agent environment. +See [README.md](README.md) for setup, command syntax, flags, and troubleshooting. + +## Rules JSON Edit Guardrail + +Do not modify +[fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) unless the +user specifically instructs you to edit that file. + +If a task appears to require changing +[fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json), stop before +editing it. Propose a concise plan that identifies the specific rule, +definition, indicator, metadata, or structural paths you intend to change, then +wait for the user's explicit confirmation before making those edits. + +Analysis, validation, structured reads, and reports may use +[fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) without +additional permission. The guardrail applies to file modifications. + +## Test Creation Guardrail + +When the user asks to add or update tests for the tooling, test harness, or +validation behavior, assume the requested test may expose existing rules data +issues, warnings, or intentionally failing cases. That is often the reason the +test is being added. + +Do not fix test failures or warnings by editing +[fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) unless the +user explicitly asks for rule-content changes. If a newly added test reports +errors or warnings against the current rules file, report the result and keep +the change scoped to test or tooling support. + +If a test cannot be made meaningful without changing the rules JSON, stop before +editing it. Explain the specific rule, definition, indicator, metadata, or +structural path that would need to change and wait for explicit confirmation. + +## Editing Guidance + +If asked to edit the rules: + +- Edit [fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) and, + only when necessary, the schema. +- Keep IDs stable unless the requested change requires a new or corrected ID. +- Preserve schema-driven property order. +- Update `updated` history when changing rule, definition, or indicator + meaning. +- Run the tooling checks when available. + +## Implementation Boundaries + +- The [rules JSON](../fedramp-consolidated-rules.json) defines rule content. + The [schema](../schemas/fedramp-consolidated-rules.schema.json) defines the + data contract, including required fields, object shapes, scalar constraints, + and controlled vocabularies. Tooling and test expectations are not rule content. +- Reuse [src/schema-metadata.ts](src/schema-metadata.ts) to read schema-owned + constraints. Standard object property order follows the schema's `properties` + order; repository-specific dynamic key and array ordering belongs in + [order-config.json](order-config.json). +- Resolve canonical file paths through [src/config.ts](src/config.ts) and + [fedramp-rules.config.json](fedramp-rules.config.json). Use + [src/rules.ts](src/rules.ts) for loading and cloning documents and + [src/traversal.ts](src/traversal.ts) for FRD, FRR, and KSI traversal. +- Keep validation read-only. Reuse [src/schema-validation.ts](src/schema-validation.ts) + and [src/consistency.ts](src/consistency.ts); keep fix planning and application + in [src/fix.ts](src/fix.ts), with CLI orchestration in [fix.ts](fix.ts). +- Use in-memory fixtures or cloned documents for tooling tests. A failing test + can be the requested result when it exposes a data issue; report the issue + with stable IDs and paths without changing the canonical rules to make it pass. + +## Commands And Side Effects + +Run maintenance commands from `tools/`; consult [README.md](README.md) for the +full reference. + +- `bun run check` runs typechecking and the test runner without rewriting the + canonical files. Use focused tests while developing and the full check for + changes to rules, schema, tooling, or tests. +- `bun run fix` and every `fix:*` alias write to the configured rules JSON by + default. They also format that file even when no normalization is needed. + There is no CLI dry-run mode. An alternate `--output` path can produce a + separate candidate when fixes are needed; it does not authorize replacing the + canonical file. Apply the Rules JSON Edit Guardrail to direct and indirect edits. +- `bun run export` writes a spreadsheet. `bun run hooks:install` changes the + repository's Git hook configuration. +- The [pre-commit hook](../.githooks/pre-commit) formats and stages **both** the + rules JSON and schema before running checks, even for a documentation or + tooling commit. Inspect its potential changes before committing; the hook + does not grant permission to change the rules JSON. + +For documentation-only work, verify links, command references, and the diff; +do not run fixers or add tests solely to check prose. For other maintenance, +run checks appropriate to the change and report commands, failures, and warnings. +Keep existing data findings separate from regressions introduced by the change. +Metadata freshness, subset force order, and unused subset warnings are advisory; +they do not authorize rules edits. Review the final diff for unintended data +changes, generated files, and staging changes. + +## Changelog Generation + +When asked to generate a changelog for the active branch, produce a screen-only +summary of the branch delta against `main`; do not create a changelog file +unless the user explicitly asks for one. + +- Output the changelog as copy/pasteable Markdown. When responding in chat, + place the changelog itself inside a fenced `markdown` code block; keep any + explanatory notes outside the block. +- Use plain repository paths inside the changelog instead of clickable Markdown + file links so the copied text remains portable. +- Use the branch merge base with `main` as the starting point and the current + branch tip as the ending point. Prefer `git diff main...HEAD`, + `git diff --name-status main...HEAD`, and + `git log --reverse --format='%h %s' main..HEAD`. +- If `main` is missing or stale and network access is available, fetch it first; + otherwise state which local ref was used. +- Treat committed branch changes as the changelog scope by default. Mention + uncommitted workspace changes separately only when they affect the requested + analysis or the user asks to include them. +- Validate the rules file against the schema before relying on automated JSON + analysis. If validation cannot be run, say so and continue carefully. +- Parse JSON with a real JSON parser when comparing + [fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) and + [schemas/fedramp-consolidated-rules.schema.json](../schemas/fedramp-consolidated-rules.schema.json); + avoid text-only diff analysis for rule content whenever structured access is + practical. +- Compare the initial branch state to the final branch state, not commit by + commit, unless a commit-level explanation is specifically requested. +- Detect and highlight breaking changes when summarizing underlying changes to + [fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) or the + schema. Use the software compatibility meaning of breaking change: a + backwards-incompatible change to the machine-readable public contract that + would make existing parsers, validators, exporters, queries, or integrations + fail, reject previously valid data, silently misread data, or require code + changes to continue processing the dataset. Examples include renamed or + removed properties such as `primary_key_word` to `force`, changed required + fields, changed property types, changed statement shapes, changed ID formats, + controlled vocabulary changes that invalidate existing values, renamed + top-level sections, renamed applicability or subset bucket keys when those + keys are part of the schema contract, or stricter validation rules that reject + files accepted by the previous schema. +- Do not mark rule-content taxonomy changes as breaking merely because a rule, + definition, or indicator moves to a different ruleset, process, applicability + path, subset, or ID. Treat those as Rules Content Changes and describe the + user-visible mapping or migration impact. Only mark such movement as breaking + when it also changes the documented data shape, schema vocabulary, required + fields, or other machine-readable contract in a way that breaks existing + tooling. +- Mark every breaking change bullet with `**Breaking:**` at the start of the + bullet in the relevant changelog section. Include the old shape and the new + shape when known, and briefly state the practical impact. For example, + changing FRR metadata from `info.labels` to `info.subsets` is breaking + because tools or consumers that still look for `labels` will fail to find the + declarations and may reject or misread the FRR data until updated. +- Use stable IDs in every rule-content bullet: `FRD-XXX`, `FRR` requirement IDs + such as `VDR-CSO-123`, and `KSI-THEME-KEY`. +- For each substantively changed rule, definition, or indicator, write one + sentence describing the user-visible change. Include additions, removals, + renamed terms, wording changes, actor/scope changes, applicability moves, + artifact changes, control mappings, examples, notifications, related rule + references, external references, timeframes, and class-specific variants. +- Group purely mechanical metadata churn, such as mass `updated` date resets or + property ordering changes, instead of listing every affected rule separately. +- Separate evidence from inference. When a conclusion comes from schema shape, + property names, or structural movement rather than explicit wording, label it + as structural. +- Use exactly these changelog sections, in this order: + 1. `Rules Content Changes` + Summarize changes inside `fedramp-consolidated-rules.json` itself. Focus + on rule, definition, indicator, FRR document, and metadata meaning changes. + 2. `Schema And Structure Changes` + Summarize changes to + `schemas/fedramp-consolidated-rules.schema.json` and corresponding + structural changes in the rules JSON, such as top-level `info` changes, + property additions, renamed applicability buckets, required fields, + controlled vocabularies, and object shapes. + 3. `Tooling And Test Changes` + Summarize support-code changes, CLI behavior, validators, fixers, + package scripts, test harnesses, and test coverage. +- Keep bullets simple and high signal. Prefer a single line per bullet unless + the change is complex enough that a short second sentence prevents ambiguity. +- End with a brief validation note naming the commands run, such as + `bun run check`, or explain why validation was not run. diff --git a/tools/README.md b/tools/README.md index 6363ca5..1a8d0dc 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,194 +1,202 @@ -# FedRAMP Rules Tooling +# FedRAMP Rules Maintenance Tools -This directory contains the Bun and TypeScript tooling used to maintain the -FedRAMP Consolidated Rules dataset. +This directory contains internal Bun and TypeScript tooling for FedRAMP +developers maintaining the rules dataset, schema, and supporting tools. Most +users consuming the information should use the [root README](../README.md) +and can ignore this directory. -The tools validate, normalize, test, and export the canonical files: - -- [../fedramp-consolidated-rules.json](../fedramp-consolidated-rules.json) -- [../schemas/fedramp-consolidated-rules.schema.json](../schemas/fedramp-consolidated-rules.schema.json) - -The tooling is support infrastructure. It does not define the rules; the JSON -dataset and schema do. +The [rules JSON](../fedramp-consolidated-rules.json) defines the content; +the [schema](../schemas/fedramp-consolidated-rules.schema.json) defines its +shape. Tooling supports those files. **Maintenance agents must read +[AGENTS-TOOLS.md](AGENTS-TOOLS.md)** for edit guardrails, testing guidance, and +changelog instructions. ## Setup -From this directory: +Run the commands in this guide from `tools/`. Use Bun 1.3.14 to match the +current [CI workflow](../.github/workflows/check.yml). ```bash -bun install +bun install --frozen-lockfile ``` -Install the repository Git hooks: +Installation writes local dependencies and may require network access. The +current check suite uses local files and does not make live rule-schema URL +requests once dependencies are installed. + +## Configuration And Implementation + +[fedramp-rules.config.json](fedramp-rules.config.json) centralizes the canonical +paths, resolved relative to that configuration file: + +| Setting | Value | +| ------------ | --------------------------------------------------- | +| `rulesFile` | `../fedramp-consolidated-rules.json` | +| `schemaFile` | `../schemas/fedramp-consolidated-rules.schema.json` | + +Standard object property order follows each schema object's `properties` order. +[order-config.json](order-config.json) owns repository-specific ordering for +dynamic object keys and array items. + +| Area | Implementation | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | +| Test runner and final reports | [test.ts](test.ts) | +| Fix CLI and shared planning/application | [fix.ts](fix.ts), [src/fix.ts](src/fix.ts) | +| Spreadsheet export | [export-spreadsheet.ts](export-spreadsheet.ts) | +| Paths and document loading/cloning/writing | [src/config.ts](src/config.ts), [src/rules.ts](src/rules.ts) | +| FRD, FRR, and KSI traversal | [src/traversal.ts](src/traversal.ts) | +| Schema constraints and validation | [src/schema-metadata.ts](src/schema-metadata.ts), [src/schema-validation.ts](src/schema-validation.ts) | +| Consistency checks and metadata freshness | [src/consistency.ts](src/consistency.ts), [src/metadata-freshness.ts](src/metadata-freshness.ts) | +| Property and dynamic ordering | [src/property-order.ts](src/property-order.ts), [src/order-config.ts](src/order-config.ts) | +| IDs, normative force, and terms | [src/id-alignment.ts](src/id-alignment.ts), [src/keywords.ts](src/keywords.ts), [src/terms.ts](src/terms.ts) | +| Types and CLI helpers | [src/types.ts](src/types.ts), [src/cli.ts](src/cli.ts) | + +Command definitions are in [package.json](package.json); tests are in +[tests/](tests/). + +## Checks + +These commands inspect the project without rewriting the canonical files: + +| Command | Behavior | +| ------------------- | ------------------------------------------------------------------------- | +| `bun run check` | Runs typechecking, then the full test runner if typechecking passes. | +| `bun run typecheck` | Runs `tsc --noEmit`. | +| `bun run test` | Runs all Bun tests through `test.ts`, then prints additional diagnostics. | + +Run `bun run check` for changes to rules, schema, tooling, or tests. Coverage +includes schema validation, formatting, ID/container alignment, subset +applicability, effective dates, normative force, terms, property and array +ordering, artifact applicability, update history, text hygiene, class variants, +controlled vocabulary, cross-references, and fix behavior. + +The runner prints human-readable consistency and property-order failure reports. +It also reports advisory warnings for metadata freshness, FRR subset force +ordering, and unused subsets; those warnings alone do not make the command fail. + +Use focused aliases while working: + +| Command | Focus | +| -------------------------------- | ---------------------------------------------------- | +| `bun run test:schema` | Dataset/schema validation and schema contract cases. | +| `bun run test:schema-validation` | Schema error messages and locations. | +| `bun run test:formatting` | Prettier formatting of both canonical JSON files. | +| `bun run test:ids` | Requirement ID alignment. | +| `bun run test:effective-dates` | Certification-specific timing rules. | +| `bun run test:force` | Statement/force consistency. | +| `bun run test:terms` | Definition casing and term synchronization. | +| `bun run test:order` | Schema-driven and configured ordering. | +| `bun run test:consistency` | Cross-entry consistency and related reporting. | +| `bun run test:fix` | Fix planning and application. | + +Focused aliases invoke Bun directly and do not include the full runner's final +reports. Artifact-applicability and metadata-warning tests are included in the +full suite and can also be run directly with `bun test` and their test paths. + +## Fixes + +**Fix commands write to the configured rules JSON by default.** They also run +Prettier on that file even when no normalization is needed. There is no CLI +dry-run mode. Maintenance agents must follow the rules-edit guardrail in +[AGENTS-TOOLS.md](AGENTS-TOOLS.md) before any direct or indirect rules edit. + +`bun run fix` selects the `auto` scope, which applies the supported +normalizations. Focused aliases select individual scopes: + +| Command | Normalization | +| ---------------------------- | ------------------------------------------------------------------------------- | +| `bun run fix:terms` | Definition title casing and `terms` synchronization. | +| `bun run fix:ids` | Renames requirement keys to match their parent subsets; collisions are skipped. | +| `bun run fix:order` | Schema property order and configured dynamic key/array order. | +| `bun run fix:related` | Adds missing related-rule references found in text. | +| `bun run fix:display-names` | Repairs inline rule IDs and their parenthesized display names. | +| `bun run fix:subset-affects` | Aligns FRR subset applicability `affects` with its requirements. | + +Pass flags after `--`: + +| Flag | Behavior | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--scope ` | Selects `auto`, `terms`, `ids`, `order`, `related`, `display-names`, or `subset-affects`; aliases set this automatically. | +| `--output ` | Writes changed rules to that path and skips in-place formatting. Use a separate path to leave the source untouched. If no fixes are needed, no output file is created. | +| `--report ` | Writes the ID fix report when ID fixes are needed; supported only with the `ids` scope. It does not prevent rules edits. | +| `-comment` or `--comment` | Adds the standard term-sync history comment when term synchronization changes are written; supported only with `auto` or `terms`. | +| `--date ` | Overrides dates used in generated fix metadata; defaults to the source dataset's `info.last_updated`, not today's date. | + +For example, generate a separate candidate and an ID report: ```bash -bun run hooks:install +bun run fix:ids -- --output ./fedramp-consolidated-rules.fixed.json --report ./id-report.json ``` -The hook runs `bun check` before commits. - -## Configuration - -All commands read canonical file locations from -[fedramp-rules.config.json](fedramp-rules.config.json). -Repository-only ordering rules for dynamic object keys and array items live in -[order-config.json](order-config.json). Standard object property order is -derived directly from each schema object's `properties` order. - -Current configuration: - -- rules file: `../fedramp-consolidated-rules.json` -- schema file: `../schemas/fedramp-consolidated-rules.schema.json` - -Keeping these paths centralized ensures that tests and fixes operate on the -same dataset. - -## Primary Commands - -### `bun run check` - -Runs the full local verification suite: - -1. `bun run typecheck` -2. `bun run test` - -Use this before committing changes to the rules JSON, schema, tests, or -tooling. - -### `bun run test` - -Runs the Bun test suite through [test.ts](test.ts). Coverage includes: - -- schema validity -- rule schema URL reachability and JSON validity -- JSON formatting -- ID alignment -- FRD, FRR, and KSI container alignment -- FRR subset declaration consistency -- force consistency -- term casing and synchronization -- schema-driven property ordering -- config-driven dynamic key and array item ordering -- update history checks -- text hygiene -- class-variant sanity checks -- FRR subset force ordering warnings -- FRR unused subset warnings -- controlled vocabulary consistency -- internal cross-reference integrity -- fix planning and application behavior - -When consistency validation fails, the runner prints a human-readable summary -after the regular Bun output. - -The rule schema URL check makes live network requests to each `schema.url` -referenced by a rule, so `bun run test`, `bun run check`, and the pre-commit -hook all require network access to succeed. - -### `bun run typecheck` - -Runs `tsc --noEmit` against the TypeScript project. - -### `bun run fix` - -Runs [fix.ts](fix.ts), which plans and applies fixable normalizations: - -- term title casing and `terms` synchronization -- ID alignment -- inline rule display names -- related rule references -- schema-driven property ordering and config-driven dynamic key ordering - -Useful variants: +For an authorized in-place term update with history comments: ```bash -bun run fix -- -comment -bun run fix -- --date 2026-05-04 +bun run fix:terms -- -comment --date 2026-09-13 ``` -`-comment` adds the standard term-sync update comment when term changes are -written. `--date` overrides the date used in generated fix metadata. - -## Common Workflow +Review the output and diff. Fixers normalize supported issues; they do not +resolve every consistency finding or decide substantive rule changes. After +applying authorized changes to the canonical files, run `bun run check` again. +Checks still read the canonical paths in the configuration, even when a fixer +has written a separate candidate. -1. Edit the rules JSON, schema, or tooling. -2. Run `bun run check`. -3. Run `bun run fix` if the check reports fixable normalization issues. -4. Run `bun run check` again. +ID fixes also record entry history and update dataset version/date metadata. +They do not rewrite references to renamed IDs; inspect references when reviewing +an ID change. -## Focused Commands +## Exports -Focused test aliases: +`bun run export` writes `../fedramp-consolidated-rules.xlsx` by default. To choose +another destination: -- `bun run test:fix` -- `bun run test:formatting` -- `bun run test:schema` -- `bun run test:schema-validation` -- `bun run test:schema-urls` -- `bun run test:ids` -- `bun run test:force` -- `bun run test:terms` -- `bun run test:order` -- `bun run test:consistency` +```bash +bun run export -- --output ./fedramp-consolidated-rules.xlsx +``` -Focused fix aliases: +The workbook contains `FRD Definitions`, `FRR Requirements`, and `KSI Indicators` +sheets. Export reads the dataset and writes the spreadsheet without changing the +rules or schema. Output paths are relative to the current working directory; +an existing destination file is overwritten. The spreadsheet is a flattened +view; use the JSON for complete nested information. -- `bun run fix:terms` -- `bun run fix:ids` -- `bun run fix:order` -- `bun run fix:related` -- `bun run fix:display-names` +## Git Hooks And CI -Examples: +Install the repository hook configuration with: ```bash -bun run fix:terms -- -comment -bun run fix:ids -- --report ./id-report.json -bun run fix:ids -- --output ./fedramp-consolidated-rules.fixed.json -bun run fix:order -- --output ./fedramp-consolidated-rules.ordered.json -bun run fix:related -bun run fix:display-names +bun run hooks:install ``` -## File Structure - -Primary entrypoints: - -- [test.ts](test.ts) - Test runner used by `bun run test`. -- [fix.ts](fix.ts) - CLI entrypoint for all fix flows. - -Shared implementation: - -- [src/config.ts](src/config.ts) - Resolves repository paths and shared configuration. -- [src/order-config.ts](src/order-config.ts) - Loads repository-only ordering rules from [order-config.json](order-config.json). -- [src/rules.ts](src/rules.ts) - Loads, clones, and writes configured rules and schema documents. -- [src/fix.ts](src/fix.ts) - Shared fix planning and application logic. -- [src/consistency.ts](src/consistency.ts) - Read-only consistency validation checks and reporting. -- [src/schema-validation.ts](src/schema-validation.ts) - Schema validation logic and error formatting. -- [src/schema-urls.ts](src/schema-urls.ts) - Collects rule `schema.url` references for reachability checks. -- [src/id-alignment.ts](src/id-alignment.ts) - ID alignment detection and rewrite logic. -- [src/keywords.ts](src/keywords.ts) - Force consistency logic. -- [src/terms.ts](src/terms.ts) - Term extraction, casing, and synchronization logic. -- [src/property-order.ts](src/property-order.ts) - Schema-driven property-order and config-driven dynamic object-key ordering. -- [src/traversal.ts](src/traversal.ts) - Shared FRD, FRR, and KSI traversal helpers. -- [src/types.ts](src/types.ts) - Shared TypeScript types. -- [src/cli.ts](src/cli.ts) - CLI helpers for flags, colors, and JSON output. - -Tests live in [tests](tests). Command definitions live in -[package.json](package.json). +This sets `core.hooksPath` to `.githooks`. On every commit, the +[pre-commit hook](../.githooks/pre-commit): + +1. Runs Prettier in write mode on both the rules JSON and schema. +2. Stages both files with `git add`. +3. Runs `bun check` from `tools/`. + +These writes and staging changes occur even for documentation or tooling +commits. The hook can include existing edits to the canonical files in the +commit, and a failed check does not undo its earlier formatting or staging. +Inspect the working tree and staged diff before committing. The hook's +`bunx prettier` invocation may need network access if Prettier is not available +locally; this is separate from the check suite. + +The [CI workflow](../.github/workflows/check.yml) runs on pushes with Bun 1.3.14, +installs dependencies using `bun install --frozen-lockfile`, and runs +`bun run check` from `tools/`. + +## Troubleshooting + +- **Stale URL-test alias:** `package.json` still defines `test:schema-urls`, + but its target `tests/schema-urls.test.ts` is absent. It is not a supported + focused check, and the full suite does not test live schema URL reachability. +- **Bun version mismatch:** [.tool-versions](.tool-versions) currently specifies + Bun 1.3.1, while CI uses 1.3.14. Use the CI version when reproducing checks. +- **Warnings or data failures during tooling work:** Report the affected IDs + and paths. Keep existing rules issues separate from tooling regressions; + do not edit the dataset merely to clear a warning or make a new test pass. +- **Skipped ID collisions or remaining fix issues:** Review the report and + source entries before deciding on a manual correction. A fixer is not + authorization to rename or merge rules. +- **Documentation-only changes:** Check links, command references, and + `git diff --check`. Do not use fix commands to validate documentation. diff --git a/tools/tests/schema.test.ts b/tools/tests/schema.test.ts index c8d4d63..6a6de02 100644 --- a/tools/tests/schema.test.ts +++ b/tools/tests/schema.test.ts @@ -328,6 +328,52 @@ test("the schema requires notification names", () => { expectSchemaRejects("notification without a name", document); }); +for (const [hasType, hasNum, hasMin, hasMax, valid] of [ + [false, false, false, false, true], + [false, false, false, true, false], + [false, false, true, false, false], + [false, false, true, true, false], + [false, true, false, false, false], + [false, true, false, true, false], + [false, true, true, false, false], + [false, true, true, true, false], + [true, false, false, false, false], + [true, false, false, true, false], + [true, false, true, false, false], + [true, false, true, true, true], + [true, true, false, false, true], + [true, true, false, true, false], + [true, true, true, false, false], + [true, true, true, true, false], +]) { + test(`FRR timeframe fields (type=${hasType}, num=${hasNum}, min=${hasMin}, max=${hasMax}) validate as ${valid}`, () => { + const document = minimalRulesDocument(); + (document as any).FRR.ABC.data = { + all: { + CSO: { + "ABC-CSO-TST": { + name: "Example Timeframe", + statement: "Providers MUST complete the review.", + force: "MUST", + affects: ["Providers"], + ...(hasType ? { timeframe_type: "days" } : {}), + ...(hasNum ? { timeframe_num: 5 } : {}), + ...(hasMin ? { timeframe_num_min: 1 } : {}), + ...(hasMax ? { timeframe_num_max: 10 } : {}), + updated: [{ date: "2026-01-01", comment: "Added timeframe." }], + }, + }, + }, + }; + + if (valid) { + expectSchemaAccepts("complete, exclusive timeframe", document); + } else { + expectSchemaRejects("incomplete or mixed timeframe", document); + } + }); +} + test("the schema owns requirement vocabularies and scalar constraints", () => { const document = minimalRulesDocument(); (document as any).FRR.ABC.info.subsets = {