Complete end-to-end walkthrough for FORGE — Framework for OSCAL Risk & Governance Execution.
git clone https://github.com/policy-forge/forge.git
cd forge
cargo build --release
./target/release/forge --versionDownload the selected published binary for your platform from GitHub Releases. The release workflow is configured to publish SHA-256 checksums and SLSA provenance. Check the evidence attached to the selected published tag for the archive hashes and any verified SLSA level.
Verify your installation:
forge --helpThe help output lists conversion, validation, profile, mapping, migration,
configuration, drift, traceability, and lifecycle workflows. Use
forge <SUBCOMMAND> --help for the exact command contract in this release.
For local agent queries, see the MCP guide. forge mcp serve exposes
seven read-only tools over stdio, with an explicit project and reviewed disclosure
scope. Static discovery does not authorize project data. The guide also records
the separate F20 /2 development checkpoint;
those candidate inputs do not activate additional shipped MCP features.
FORGE accepts Markdown files (.md / .markdown) with optional YAML frontmatter. Headings become OSCAL groups; list items, tables, and paragraphs become control statements.
Create a file named policy.md:
---
title: "Access Control Policy"
version: "1.0.0"
author: "Security Team"
date: "2026-01-15"
---
# Access Control
All users must authenticate before accessing systems.
## Authentication Requirements
- Users must use multi-factor authentication
- Passwords must be at least 12 characters
- Sessions must timeout after 30 minutes of inactivity
## Authorization
- Access must follow principle of least privilege
- Role-based access control must be enforced
# Data Protection
## Encryption
- Data at rest must be encrypted using AES-256
- Data in transit must use TLS 1.2 or higher
- Encryption keys must be rotated annually- YAML frontmatter sets metadata:
title,version,author,date - Level-1 headings (
#) become top-level OSCAL groups - Level-2+ headings (
##,###) become nested groups - List items (
-) become individual controls - Paragraphs become control statements
- Compound requirements like "Systems must X and must Y" are automatically split into atomic controls
FORGE detects and processes:
- Requirement atomization — splits "must X and must Y" into separate controls
- Modality detection — classifies statements as mandatory (MUST/SHALL) or advisory (SHOULD/MAY)
- Parameter extraction — turns prose thresholds (e.g., "12 characters", "30 minutes") into structured OSCAL parameters; enforcement depends on separately configured consumers
- Citation extraction — URLs and references become OSCAL back-matter resources
- Content-derived identifiers — UUID v5 tags repeat for the same normalized requirement text; substantive text or duplicate-occurrence changes can change them. These tags are not integrity or approval anchors.
25 sample policies are included in example_data/ covering topics from acceptable use to incident response.
PDF and DOCX source documents are also accepted directly — Word heading and list styles are mapped to the document model automatically. For other formats, convert to Markdown first using pandoc or markitdown.
Converts a Markdown policy document into an OSCAL Catalog or Component Definition.
Produces an OSCAL Catalog with groups, controls, and statements:
# Basic conversion — outputs JSON to stdout
forge convert policy.md --strategy catalog --format json
# Write to a file
forge convert policy.md --strategy catalog --format json --output catalog.json
# Output as XML
forge convert policy.md --strategy catalog --format xml
# Output as YAML
forge convert policy.md --strategy catalog --format yamlProduces an OSCAL Component Definition with implemented requirements. Requires --source-profile for schema-valid output:
# With a source profile (OSCAL Profile JSON)
forge convert policy.md --strategy component --format json \
--source-profile baseline-profile.json
# With source profile + XML output
forge convert policy.md --strategy component --format xml \
--source-profile baseline-profile.json --output component.xml# Override max input file size (default: 10 MB)
forge convert large-policy.md --strategy catalog --format json --max-size 20
# Enable verbose pipeline logging (shows each stage)
forge -v convert policy.md --strategy catalog --format json
# Suppress all non-essential output (OSCAL artifact only)
forge -q convert policy.md --strategy catalog --format json
# Detect substantive changes against a baseline
forge convert policy-v2.md --strategy catalog --format json \
--stable-id-baseline policy-v1.md
# Generate an Assessment Plan alongside the Catalog
forge convert policy.md --strategy catalog --format json \
--import-ssp system-security-plan.json
# Print a conversion summary dashboard to stderr
forge convert policy.md --strategy catalog --format json --summary
# Batch conversion (multiple files)
forge convert pol-*.md --strategy catalog --format json --output out/
# Batch with parallel jobs
forge convert pol-*.md --strategy catalog --format json --output out/ --jobs 4Converts a supported Catalog or Component Definition between JSON, XML and YAML. The input format is detected from its extension; other OSCAL models are not supported by export.
# JSON to XML
forge export catalog.json --format xml
# XML to YAML
forge export catalog.xml --format yaml
# YAML to JSON, written to a file
forge export catalog.yaml --format json --output catalog.json
# JSON Component Definition to XML
forge export component.json --format xmlFile extensions recognized: .json, .xml, .yaml, .yml.
The Catalog or Component Definition model is detected from the document root. For JSON/YAML inputs and JSON/YAML targets, export validates the complete decoded JSON-compatible tree against the pinned OSCAL schema and semantic checks before publication. Supported native fields and array order remain in that tree; invalid unknown schema fields are rejected rather than silently discarded. Only numeric values represented exactly as i64/u64 integers are admitted: every f64 representation is refused, including 1.0, 1e0 and oversized JSON integers decoded as floating point. JSON object order, whitespace, original bytes and YAML tags/comments/anchors are outside this decoded-tree contract. XML input/output and direct typed helper APIs still use a partial model projection, so retain the original for those paths. See the prerequisite scope and verification obligations.
Validates supported OSCAL JSON artifacts against the pinned OSCAL v1.2.3 JSON schemas with semantic checks. Supported older declarations use the same pinned baseline; metadata never selects or downloads another schema.
# Basic validation with human-readable output
forge validate catalog.json
# Machine-parseable JSON output
forge validate catalog.json --format json
# Override auto-detected model type
forge validate artifact.json --schema-type catalog
forge validate artifact.json --schema-type component-definition
# Validate an OSCAL Assessment Results document (auto-detected from its root)
forge validate assessment-results.json
forge validate assessment-results.json --schema-type assessment-results
# Write validation results to a file
forge validate catalog.json --output validation-report.txtOn valid: prints "Valid: catalog artifact passes all validation." and exits 0. On invalid: renders the error report to stderr and exits non-zero.
Assessment Results documents are validated against the pinned v1.2.3
schemas/oscal_assessment-results_schema.json with the same report, formats and
exit codes as other models (schema errors exit 3). This checks native schema
conformance only: it does not verify the Assessment Plan, SSP, Profile or
evidence context that forge assessment results build checks, and it is not an
assessment conclusion. --round-trip, export and diff do not support
Assessment Results. This is an approved small scope expansion beyond PRD 054
(F10 in the 2026-10-25 owner dispositions).
Tests format fidelity by running the artifact through a full conversion chain (JSON → XML → YAML → JSON) via oscal-cli, then comparing the result against the original:
# Requires oscal-cli on PATH
forge validate catalog.json --round-trip
# Custom oscal-cli path and timeout
forge validate catalog.json --round-trip \
--oscal-cli-path /usr/local/bin/oscal-cli --timeout 60
# Machine-parseable round-trip results
forge validate catalog.json --round-trip --format jsonReports any divergences with classification markers: FORGE-FIX, OSCAL-CLI, ACCEPT.
Resolves an OSCAL Profile into a flat Catalog baseline by delegating to oscal-cli. Requires oscal-cli on PATH (Java-based).
# Resolve a Profile (requires .json input)
forge resolve nist-800-53-profile.json
# Custom output path
forge resolve profile.json --output resolved-catalog.json
# Custom timeout (default: 60s)
forge resolve profile.json --timeout 120
# Custom oscal-cli binary path
forge resolve profile.json --oscal-cli-path /usr/local/bin/oscal-cli
# Check oscal-cli availability without resolving
forge resolve --checkDefault output path: <input-stem>-resolved.json in the same directory.
Generates a traceability report mapping OSCAL elements back to their source policy locations.
# Trace an OSCAL artifact against its source policy
forge trace catalog.json --source policy.md
# Write report to a file
forge trace catalog.json --source policy.md --output trace-report.txtThe output is a column-aligned table:
OSCAL Element ID Element Type Source Section Source Line
---------------- ------------ -------------- -----------
access-control group Access Control —
POL-AC-001 control Access Control 10
POL-AC-002 control Access Control 25
POL-DP-001 control Data Protection 27
[unmapped] control [unmapped] [unmapped]
Summary: 5 elements, 4 mapped, 1 unmapped (80.0% coverage)
- Groups with a section but no specific line show an em dash (—) for Source Line
- Unmapped elements show
[unmapped]in source columns - A staleness warning appears if the source file has been modified since conversion
Compares two OSCAL artifacts (Catalogs or Component Definitions) and shows differences.
# Compare two catalogs
forge diff catalog-v1.json catalog-v2.json
# Compare two component definitions
forge diff component-old.json component-new.jsonThe output includes:
OSCAL Diff Report
=================
Old: catalog-v1.json (catalog)
New: catalog-v2.json (catalog)
Summary
-------
Controls (old): 5 | Controls (new): 6
Added: 1 | Removed: 0 | Changed: 1 | Unchanged: 4 | UUID changes: 0
Added (1)
─────────
+ POL-DP-003 [uuid: ...]
Changed (1)
───────────
~ POL-AC-001
title: "Old title" → "New title"
Exits 1 if differences are found (useful in CI pipelines).
Compares the complete parsed JSON value of committed and newly generated
Catalog or Component Definition artifacts. It ignores only the generated root
uuid and metadata.last-modified; every nested UUID and all other metadata and
policy-derived fields remain significant.
# Human-readable status
forge drift committed/catalog.json staged/catalog.json
# Machine-readable status for CI orchestration
forge drift committed/catalog.json staged/catalog.json --format jsonBoth output formats contain only status, artifact type, and comparison-contract
version. They do not include file paths, control identifiers, titles, prose, or
JSON excerpts. Exit 0 means clean, exit 1 means drift, and exit 2 means the
inputs could not be compared. This is a comparison primitive, not schema
validation; enforcement workflows must run forge validate first.
Creates an OSCAL Profile by selecting specific controls from a source Catalog.
# Include specific controls
forge profile --catalog nist-800-53.json \
--include "ac-1,ac-2,ac-3,ia-1,ia-2"
# Exclude specific controls
forge profile --catalog nist-800-53.json \
--exclude "ac-1,ac-2"
# Output as XML or YAML
forge profile --catalog catalog.json --include "ac-1" --format xml
forge profile --catalog catalog.json --include "ac-1" --format yaml
# Write to a file
forge profile --catalog catalog.json \
--include "ac-1,ac-2" --output my-profile.json
# Set parameter overrides in the Profile's modify section
forge profile --catalog catalog.json --include "ac-2" \
--set-param ac-2_prm_1 "30 days" \
--set-param ac-2_prm_2 "12 characters"
# Override last-modified timestamp (ISO 8601) for reproducible output
forge profile --catalog catalog.json --include "ac-1" \
--timestamp "2026-01-15T12:00:00Z"--include and --exclude are mutually exclusive. At least one must be provided (unless using only --set-param, which produces a Profile with empty imports and a warning).
Control Mapping accepts explicit reviewer decisions from a closed,
versioned forge.mapping-manifest/1 JSON document. It never downloads
framework content, follows OSCAL links, invokes oscal-cli, generates
relationship candidates, or interprets gaps as compliance failures.
# Deterministic unapproved scaffold; add reviewers, rationale, and maps before build
forge mapping init --source policy-catalog.json --target framework-catalog.json \
--output mapping-manifest.json
# Profiles need a caller-produced resolved Catalog companion
forge mapping init --source policy-catalog.json --target framework-profile.json \
--target-resolved-catalog framework-resolved.json \
--output mapping-manifest.json
# OSCAL JSON and reports always use separate streams/files
forge mapping build --manifest mapping-manifest.json \
--output mapping.json \
--report mapping-report.json --report-format json
# Read-only baseline impact check for CI
forge mapping check --manifest mapping-manifest.json \
--baseline mapping.json --report-format json --fail-on anyThe manifest declares control-only or control-plus-statement review scope,
stable collection/mapping/map keys, resource paths and expected hashes,
reviewer parties, provenance, and one or more explicit maps. Many-to-many sets
remain one map and source/target direction is never reversed. Missing controls,
wrong semantic types, stale scaffold inventories, duplicate IDs/keys, invalid
vocabulary, and confidence/coverage values outside 0..=1 fail before output.
For a Profile, the reviewer must set resolved_catalog_attestation: true after
confirming that the explicit companion represents that Profile; FORGE records
both hashes but does not authenticate the reviewer or independently prove the
resolver lineage.
Reports label ratios as review participation, never compliance coverage.
By default they contain IDs, counts, hashes, and stable machine finding codes.
--include-excerpts adds bounded titles/prose and makes the report as sensitive
as its source frameworks. Exit 0 means analysis completed without the selected
review policy firing, exit 1 means completed analysis requires human review,
and exit 2 means no trustworthy artifact or report could be produced.
Reviewer names and rationale become durable artifact data. FORGE preserves but does not authenticate identity, authority, approval, or signatures. Users are responsible for permission to process and share framework content; FORGE ships no third-party framework catalogs and defaults reports to IDs and hashes.
New lifecycle records use the closed, bounded forge.policy-lifecycle/2 JSON
contract. Legacy /1 records remain readable by check and status; migrate
them non-destructively before transitions or attestations. One file describes
one immutable policy version, its source and
generated-artifact hashes, declared parties, versioned approval policy,
date-only review schedule, current state, optional replacement, and append-only
transition events. Unknown or duplicate JSON keys, unsupported versions,
sequence gaps, invalid event UUIDs, unsafe aliases, and exceeded limits fail.
forge lifecycle init --source policy.md --artifact catalog.json \
--output policy-lifecycle.json --policy-key access-control \
--version-key v1 --title "Access Control Policy" --owner alice \
--party alice=owner,author --party bob=reviewer --party carol=approver \
--next-review 2027-08-25 --separate-reviewer-approver
# Preserve a legacy /1 file and produce a context-bound /2 replacement.
forge lifecycle migrate --record policy-lifecycle-v1.json \
--output policy-lifecycle-v2.json
# Without --apply, transition writes a complete proposal to stdout or --output.
forge lifecycle transition --record policy-lifecycle.json --to in-review \
--actor bob --role reviewer --at 2026-08-25T17:00:00Z \
--rationale "Review completed" --apply
forge lifecycle transition --record policy-lifecycle.json --to approved \
--actor carol --role approver --at 2026-08-25T18:00:00Z \
--rationale "Approved for publication" --apply
forge lifecycle check --record policy-lifecycle.json --format json
forge lifecycle status --record policy-lifecycle.json \
--as-of 2026-08-25 --format json --gate publication
# Explicit portfolio review queue grouped by owner and date
forge lifecycle queue --record policy-lifecycle.json \
--as-of 2026-08-25 --format json --gate publication
# Deterministic unsigned evidence suitable for a separate signing system
forge lifecycle attest --record policy-lifecycle.json \
--output approval-attestation.jsonApproval evidence must use identical fingerprints and meet every declared role
count. Additional distinct evidence can be supplied as repeatable
--assertion ACTOR=ROLE values. Separation rules compare declared actor keys;
they do not prove identity or authority. When author/reviewer or
author/approver separation is enabled, the review window must include at least
one declared author assertion; missing author evidence fails closed. An
approved record whose current bytes differ reports approved-drifted; a
generated artifact type or root-UUID change is also reported as action required
with artifact-identity-changed, rather than invalid JSON. status classifies
the next-review date itself as due-soon and only later dates as overdue.
due-soon is informational under the publication gate. The gate blocks
overdue, drifted, artifact-identity-changed, draft, in-review, superseded, and
retired records, so historical portfolios must be curated for publication.
check validates structure, artifact drift, and portfolio relationships without
inventing an --as-of date. Check/status JSON is always an array, even for one
record. Repeat --record for deterministic portfolio status and
supersession-cycle validation. queue emits forge.policy-lifecycle-queue/1
JSON grouped by owner and next-review date. A transition entering in-review
can preserve bounded, sorted PRD-057 reasons with repeatable
--impact-finding-id values; duplicate flags are collapsed. Those IDs are
included in status and queue output. attest emits deterministic
forge.policy-approval-attestation/1 JSON containing the approved event,
declared assertions, approval policy, exact fingerprints, and review date. It
does not sign anything and refuses records that are not currently approved or
whose approved bytes have drifted. Exit 0 means valid under the selected gate,
exit 1 means valid but action is required, and exit 2 means the record,
artifacts, portfolio, or transition is invalid.
Event IDs bind policy metadata, parties, approval rules, review configuration,
and transition evidence. Direct edits to those surrounding fields invalidate
existing /2 history. Migration retains each /1 event ID as
legacy_event_id and calculates a new context-bound ID without modifying the
input record. Transition writes use durable atomic replacement and a final
byte comparison, but portable filesystems do not provide conditional rename;
concurrent lifecycle transitions or external writers therefore require
external serialization. FORGE does not claim multi-writer transaction safety.
Applicability analysis consumes one closed forge.applicability/1 manifest,
one exact local Catalog or Profile baseline, and zero or more PRD 055 Mapping
Collections. Omitted controls remain under-review. FORGE never derives scope
from mappings and never labels a mapped control as satisfied.
# Catalog scaffold: omitted decisions make every inventoried control under-review
forge applicability init --framework framework-catalog.json \
--output applicability.json
# Profile scaffold: caller supplies the resolved Catalog used for inventory
forge applicability init --framework framework-profile.json \
--resolved-catalog framework-resolved.json \
--output applicability.json
# Text, JSON, and static HTML share the same deterministic report model
forge applicability analyze --manifest applicability.json --format text
forge applicability analyze --manifest applicability.json --format json \
--output applicability-report.json
forge applicability analyze --manifest applicability.json --format html \
--output applicability-report.htmlThe scaffold records resource type, relative label, raw SHA-256, root UUID,
metadata version, OSCAL version, resolved-Catalog hash when applicable, and a
sorted control inventory. To keep large valid inventories bounded, the scaffold
starts with an empty decisions array; the manifest contract classifies every
omitted control as under-review. For a Profile, a reviewer must change
resolved_catalog_attestation to true only after confirming the companion.
Each explicit decision uses one of applicable, not-applicable, deferred,
or under-review. Applicable decisions require reviewer and review time;
exclusions additionally require rationale; deferrals additionally require a
YYYY-MM-DD revisit date. Explicit under-review records may carry only an
optional assignee (reviewer_key) and note.
Every control receives exactly one primary classification:
applicable-mapped, applicable-reviewed-no-relationship,
applicable-unmapped, not-applicable, deferred, or under-review. Positive
mapping participation wins when a control has both positive and explicit
no-relationship edges, while both edge counts remain visible. The JSON/HTML
review queue uses stable reason codes and retains owner, revisit date, and
policy-source metadata.
Control and statement subjects retain PRD 055 granularity. A relationship that targets only a statement is validated as part of its Mapping Collection but does not implicitly classify the statement's parent control as mapped or reviewed-no-relationship. Authors must map the control explicitly when that is the reviewed conclusion.
Detail filters never change framework-wide totals. Persisted applicability reports must reconcile the six classification counts with the inventory total; invalid or overflowing sums are rejected. Unfiltered category counts match the visible inventory exactly, while filtered details may be a subset. Workspace currentness additionally requires comparison with recomputed analysis.
For example, select a subset without changing the complete denominator:
forge applicability analyze --manifest applicability.json --format json \
--group access-control \
--control-prefix ac- \
--state applicable-unmapped \
--reviewer scope-reviewer \
--policy-source policy-catalog.jsonThe explicit CI gates are never (default), applicable-unmapped,
any-review-action, and overdue-deferred. The overdue gate requires a caller-
supplied date so repeated runs do not depend on the wall clock:
forge applicability analyze --manifest applicability.json \
--fail-on overdue-deferred --as-of 2026-10-01The gate treats a deferral as overdue only when its revisit_date is strictly
earlier than --as-of. It does not fire on the revisit date itself.
Analysis is offline and bounded. Unknown/duplicate manifest keys, unsupported
versions, stale inventories or subject fingerprints, conflicting decisions or
relationships, contradictory policy-source identities, duplicate or unstable
Mapping UUIDs, undeclared map reviewers, mismatched framework sides, absolute
local report paths, and output/input aliases fail before any report is written. Exit 0
means valid analysis without the selected gate condition, exit 1 means a
valid report requires human review, and exit 2 means analysis failed.
Artifact and Mapping Collection paths are trusted local file instructions
resolved from the manifest directory and may intentionally contain ..; the
manifest is not a filesystem-confinement boundary. Output parent directories
must already exist.
The command compares two caller-supplied OSCAL Catalogs or two attested Profile-plus-resolved-Catalog pairs. It traverses optional PRD 055 Mapping Collections built against the exact old framework and can incorporate one raw PRD 056 applicability manifest as the authoritative prior scope and gap state. It does not fetch framework content, infer renamed controls, copy prose into the report, or modify dependencies.
{
"schema_version": "forge.framework-impact/1",
"old": {
"type": "catalog",
"artifact": "framework-v1.json",
"expected_sha256": "<64 lowercase hex characters>",
"root_uuid": "<catalog lineage UUID>",
"document_version": "1.0.0",
"oscal_version": "1.2.3"
},
"new": {
"type": "catalog",
"artifact": "framework-v2.json",
"expected_sha256": "<64 lowercase hex characters>",
"root_uuid": "<new Catalog root UUID>",
"document_version": "2.0.0",
"oscal_version": "1.2.3"
},
"mapping_collections": [
{"artifact": "policy-mapping.json", "framework_role": "target"}
],
"applicability_manifest": "applicability.json",
"successor_map": "successor-map.json",
"prior_report": "prior-impact-report.json",
"disposition_file": "impact-dispositions.json"
}For a Profile, each old and new object additionally requires
resolved_catalog, resolved_catalog_attestation: true, and
expected_resolved_catalog_sha256. The raw Profile provides resource identity;
the attested companion Catalog provides the control inventory and canonical
control hashes.
forge framework impact --manifest framework-impact.json \
--format json --output framework-impact-report.json
# Fail on informational findings too; the default threshold is review-required
forge framework impact --manifest framework-impact.json \
--format json --fail-on any
# Emit deterministic GitHub workflow commands without posting them
forge framework impact --manifest framework-impact.json --format github
# Produce deterministic review artifacts from the same report model
forge framework impact --manifest framework-impact.json --format markdown \
--output framework-impact.md
forge framework impact --manifest framework-impact.json --format html \
--output framework-impact.html
# Narrow displayed detail with exact-match filters
forge framework impact --manifest framework-impact.json --format json \
--group access-control --decision-state applicable \
--policy-source policies/access-control.json \
--priority review-required --owner security-governanceControl identity is exact: a similar new ID is added while the missing old ID
is removed. Same-ID canonical subtree changes are content-changed; stable ID
and stable fingerprint are unchanged. Mapping inputs must carry the exact old
resource evidence and subject hashes or the complete analysis fails with exit
2 and no report. If applicability_manifest is present, its old resource and
complete Mapping Collection set must match the impact manifest's target-side
portfolio exactly. Applicability findings retain the prior six-state gap
classification, reviewer owner, and policy-source labels. Removed mapped
controls are blocking; changed mapped controls, added controls, and affected
applicability decisions require review. Other unmapped removals and changes are
informational.
successor_map accepts the same closed forge.successor-map/1 contract used by
forge migrate. Declared one-to-one successors, one-to-many splits, and
many-to-one merges become identity-migrated groups with sorted old/new control
IDs, hashes, cardinality, reviewer, timestamp, and rationale. A declaration is
evidence supplied by the caller, not an authenticated approval; FORGE never
infers a successor.
Durable review state requires prior_report and disposition_file together.
The closed forge.framework-impact-dispositions/1 file binds itself to the
prior report's SHA-256 and assigns each prior finding exactly one of resolved,
accepted-risk, or still-open, with reviewer, time, and rationale. Raw current
findings and priority totals remain unchanged. Resolved and accepted-risk
findings no longer fire the selected gate; still-open and undispositioned
findings do. Dispositions whose findings are absent from the current raw result
remain visible as prior_only_dispositions for audit continuity.
Detail filters are available as --group, --decision-state,
--policy-source, --priority, and --owner. Multiple filters use AND
semantics. Group matching uses the deterministic old/new group-ID union for a
finding, including every side of an identity migration; decision state is the
validated prior PRD 056 applicability decision rather than its derived gap
classification. Policy source and owner use exact string matching. Filters
narrow the rendered review queue only: framework-wide change and priority
totals, raw disposition accounting, and gate evaluation still cover the full
validated analysis, including findings omitted from display.
The default review-required gate exits 1 for blocking or review-required
findings. blocking is a weaker threshold and any is stricter; there is no
disabled gate. Exit 0 means the selected threshold did not fire, not that the
organization remains compliant. Stable finding IDs can be carried into PRD 058
policy review history:
forge lifecycle transition --record lifecycle.json --to in-review \
--actor reviewer --role reviewer --at 2026-08-25T14:00:00Z \
--rationale "Framework impact requires review." \
--impact-finding-id <finding-uuid> --applyMarkdown and static HTML escape caller-controlled table and markup content and
contain no scripts, remote assets, or runtime timestamps. The GitHub format
emits error, warning, and notice workflow commands for blocking,
review-required, and informational findings respectively. It escapes
workflow-command data, includes no framework prose or absolute paths, and does
not call GitHub or mutate repository state.
forge migrate old-policy.md new-policy.md --format json \
--successor-map successor-map.jsonThe optional closed forge.successor-map/1 JSON file uses the same
successor, split, and merge cardinalities accepted by framework impact.
Every declaration requires non-empty approved_by, RFC 3339 approved_at, and
rationale. Conflicting, reused, self-mapped, absent, malformed, oversized, or
unsafe declarations fail with exit 2 before output. Valid declarations remain
read-only and appear as declared—not authenticated—migration outcomes.
Create a context-bound draft, then add explicit assessor-authored observations, findings, risks, provenance, and relationships:
forge assessment results init --assessment-plan assessment-plan.json \
--ssp ssp.json --profile profile.json --catalog catalog.json \
--output assessment-results-manifest.json
forge assessment results build --manifest assessment-results-manifest.json \
--output assessment-results.json \
--report assessment-results-review.json --report-format jsonThe optional --evidence-index input is an identity-only PRD 060
forge.linkage-index/1 artifact. FORGE copies evidence keys and hashes, not
content, and does not treat a link as sufficient evidence. Use --baseline to
report stable-identity revision impacts; the default --fail-on any exits 1
when review actions exist. The baseline must contain exactly one result epoch;
a plural baseline exits 2 before publication, including with --fail-on never.
Static HTML is available with --report-format html.
The build remains local, JSON-only, deterministic, and validated against the
pinned official OSCAL 1.2.3 Assessment Results schema. It records declared
judgments without authenticating assessors or inferring compliance,
effectiveness, certification, or remediation ownership. See
OSCAL Assessment Results for the complete contract and
trust boundaries.
forge assessment results append-epoch \
--request epoch-request.json \
--output next-assessment-results.json \
--report next-epoch-report.jsonBoth output names must be new portable JSON filenames on the request's parent.
The saved report is always JSON. Optional --view-format json|text|html selects a
complete stdout view after both files are published; omitted view leaves stdout
empty. A valid append returns 1 for descriptive review actions, or 0 with
--fail-on never; errors return 2 and a late error can leave complete files.
This profile requires the same Assessment Plan and context and sealed ordered
windows. An appended epoch may add roles and parties, and new findings may link
to earlier observations; earlier objects never change.
See sealed assessment epochs for complete risk
classification, continuity, bounds, source rebinding and remaining S-4 gates.
Start with an empty scaffold from forge poam init. Supply a closed
forge.poam-risk-authoring/1 request containing the complete authored workflow
and exact reviewed risk references:
forge assessment results export-poam \
--scaffold /absolute/bundle/empty-plan.json \
--authoring requests/reviewed-risks.json \
--as-of 2026-10-04 --output plan-workflow.json--authoring is relative to the scaffold's parent. --output is a new single
.json filename in that same directory; omit it for stdout. You supply every
owner, date, milestone and planned initial history event. Export exits 0 for
complete admitted output and 2 for invalid input or output failure; subsequent
POA&M check/build retain their separate 0/1/2 meanings. See
reviewed-risk authoring for source
inventory selection, platform publication limits, consumption and remaining
acceptance gates.
To add new work to an existing plan, replace --scaffold with
--existing-plan /absolute/bundle/plan-workflow.json. This opt-in mode is
add-only. The request carries only new planned items, plus the plan's exact
source, roles and parties. Existing items and their history are never changed,
and the plan file is never rewritten. Reviewed risks already referenced by the
plan, and source mismatch or staleness, are refused. See
add new work to an existing plan.
forge poam init emits an unselected forge.poam/1 scaffold from one exact
Assessment Results result UUID and stable key plus its local Assessment Plan,
SSP, Profile and Catalog companions. Document metadata is explicit; no work,
actors, remediation ownership, deadlines or status assertions are inferred.
forge poam check --manifest ./assessment-bundle/poam.json \
--source-only --format json
forge validate native-poam.json --schema-type poamThe first command verifies the captured source identities and emits a complete
finding/risk inventory. It requires --source-only, refuses nonempty items,
roles and parties. The second command performs
native POA&M structural validation and the system-identity assembly check; it
does not establish source binding or remediation workflow acceptance. POA&M
format conversion through forge export, source trace and generic diff remain
unsupported.
See POA&M source foundation for the exact inputs, bounded
source profile, publication limits and remaining gates.
An explicitly authored plan uses a separate workflow scope:
forge poam check --manifest ./assessment-bundle/authored.json \
--workflow --as-of 2026-02-06 --due-soon-days 7 --format json
forge poam build --manifest ./assessment-bundle/authored.json \
--as-of 2026-02-06 --output native-poam.json --report schedule.jsonEvery item selects exact source finding/risk identities and supplies declared
owners, dates, ordered milestones and attributed append-only history. The as-of
date is required. Exit 0 means valid ungated state, 1 a valid schedule action,
and 2 invalid input or publication. completed-asserted and
accepted-risk-asserted need an independent reviewer and hashed evidence with an
explicit captured_at; they are assertions, never verified closure, and are never
overdue. Reopen work with a new item that sets supersedes. Both
new output filenames use the manifest directory so relative native source links
retain their base. Artifact/report publication is separate and may leave a new
artifact if the later report fails. See authored POA&M commands
for explicit baselines, bounds, portable destinations and remaining acceptance.
Compare a prior declaration separately, including revisions refused by native production:
forge poam baseline --manifest ./assessment-bundle/authored.json \
--baseline prior.json --as-of 2026-02-06 --format jsonExit 0 means a complete comparison needs no review; 1 means its complete report
needs review; 2 means invalid input/output. Prior source tuples are checked against
the actual current source capture, without reconstructing historical freshness.
See baseline comparison for complete denominators,
reopen/supersession relations with accepted_for_build, privacy and admission limits.
Review explicitly paired native plans together:
forge poam portfolio --manifest ./assessment-bundle/authored.json \
--native native-poam.json --as-of 2026-02-06 --due-soon-days 7 \
--output-root ./portfolio-reports --report portfolio.json --html portfolio.htmlThe output directory must already exist and both filenames must be unused. Repeat
--manifest and --native in matching order for up to 32 plans. Complete JSON
and HTML retain summed per-plan counts, null/cancelled/future rows and inert source
hrefs in their original bundle context. Outputs are separate: a later failure does
not roll back an earlier file. See portfolio reports for the
supported companion profile, stdout, dates, bounds and exit statuses.
Prepare explicitly selected local outbound intent from one current native plan:
forge poam outbound --manifest ./assessment-bundle/authored.json \
--native native-poam.json --selection outbound-selection.json \
--as-of 2026-02-06 --due-soon-days 7 --output-root ./outbound-reports \
--report change-set.jsonThe closed selection chooses each item and create, update, or close-request
intent explicitly. Native and selection inputs are single JSON filenames beside
the manifest. The output directory must exist and the report filename must be new.
Omit --report for stdout. Valid local handoff exits 0 regardless of schedule;
invalid input/output exits 2. Eight actual originals are rechecked before output,
and remote apply authority remains false. See local outbound change sets
for the selection format, complete native matching, minimized fields and bounds.
Inspect local evidence with forge poam evidence --manifest ./assessment-bundle/authored.json --links review/evidence-links.json --as-of 2026-10-04. Add --report inspection.json to publish a new report beside the plan on Linux or macOS. See local evidence inspection for explicit assertion bindings, complete counts and unchanged closure gates.
Portable review commands are an unreleased F12 implementation candidate and are not included in the published v1.1.0 binary.
Use forge review init for selected Mapping assertions or explicit applicability
decisions in complete recorded Approved/current native closures. respond binds
to the exact recorded queue; merge and status check the complete current source
closure. Reviewer keys, roles, authors and times are asserted. A satisfied quorum
does not approve or modify the domain artifact.
export-html renders a recorded disposition bundle; export-notifications
exports recorded queue assignments without sending them or checking current
native sources. supersede creates a separate immutable old/new lineage companion
from explicit links and a complete native Impact comparison. The old queue stays
historical, and responses and quorum do not transfer to the new queue.
See the portable review queue guide for the private source, policy, Impact and link formats, exact commands, source requirements, sharing limits and remaining acceptance gates. Inputs and outputs are explicit paths under an absolute project root; output files must be new. Publication uses the no-replace publisher on Linux, macOS and Windows (Windows file publication). Identifiers and hashes can still contain sensitive project metadata.
Lifecycle re-review uses a separate closed /2 exchange candidate.
Its implementation candidate registers forge review lifecycle init/respond/merge/status; the linked guide gives exact flags for use after
candidate integration. This section's seven commands retain their existing
Mapping/applicability scope; no review disposition changes native Lifecycle state.
Authoring re-review uses a separate closed /3 candidate
for one complete current saved forge.authoring-plan/1. Its routes are
forge review authoring init/respond/merge/status; the linked guide records exact
flags, private declarations and completed TEMP test/lint/Rustdoc/LLVM/compiled-CLI
qualification scopes. Apply these instructions after candidate integration;
final integrated checks and hosted/platform/human acceptance remain open. The
adapter does not select individual clauses or consume component
forge.authoring-plan/2 output. Published v1.1.0 has no /3 exchange.
# Verbose: show each pipeline stage on stderr
forge -v convert policy.md --strategy catalog --format json
# Quiet: suppress all non-essential output (OSCAL artifact only on stdout)
forge -q convert policy.md --strategy catalog --format jsonThe common conversion preparation and output sequence is:
- Prepare the source — Ingest and reconstruct content, extract sections and clauses, then assemble the internal
PolicyDocument. - Enrich requirements — Atomize compound requirements, assign stable IDs, then extract citations, annotate modalities and extract parameters.
- Build and emit the model — Map to the requested supported OSCAL model, embed applicable trace links, validate the JSON-compatible model structurally and semantically, then serialize in the requested format.
The exact model-specific path is described in the architecture guide. Stable IDs do not imply byte-identical runtime metadata.
Use -v to watch each stage execute.
Here is a complete workflow from a policy document to validated, cross-format OSCAL artifacts with diff and trace.
cat > my-policy.md << 'EOF'
---
title: "My Security Policy"
version: "1.0.0"
author: "Engineering"
date: "2026-05-01"
---
# Access Control
## Authentication
- All users must authenticate with multi-factor authentication
- Service accounts must use certificate-based authentication
- Failed login attempts must be limited to 5 before account lockout
## Authorization
- Access must be granted on a least-privilege basis
- Privileged access must require explicit approval
# Data Protection
## Encryption Standards
- Data at rest must be encrypted using AES-256 or stronger
- Data in transit must be protected with TLS 1.3
- Encryption keys must be rotated every 180 days
EOFforge convert my-policy.md --strategy catalog --format json --output my-catalog.jsonOutput: my-catalog.json — an OSCAL v1.2.3 Catalog with groups for "Access Control" and "Data Protection", each containing atomized controls with stable UUIDs.
forge validate my-catalog.jsonExpected output: Valid: catalog artifact passes all validation.
forge export my-catalog.json --format xml --output my-catalog.xml
forge export my-catalog.json --format yaml --output my-catalog.yamlforge validate my-catalog.json --round-tripforge profile --catalog my-catalog.json \
--include "POL-AC-001,POL-AC-002,POL-DP-001" \
--output my-profile.jsonforge trace my-catalog.json --source my-policy.md# Edit the policy, bump the version
cp my-policy.md my-policy-v2.md
# ... make changes to my-policy-v2.md ...
forge convert my-policy-v2.md --strategy catalog --format json --output my-catalog-v2.json
forge diff my-catalog.json my-catalog-v2.jsonmkdir -p output
forge convert example_data/POL-0[1-3]*.md --strategy catalog --format json --output output/ --jobs 4| Code | Maintained error family or completed action |
|---|---|
| 0 | Success under the selected command/gate |
| 1 | Input/I/O, serialization or external execution failure; also completed diff, drift or review-action states |
| 2 | Parse/structure, required-argument or domain build/analysis failure |
| 3 | Schema validation or configuration failure |
| 4 | External dependency unavailable or nonfunctional |
CLI argument parsing also exits 2 for rejected usage. Use each command's
documented gate/action semantics before treating a nonzero code as a failed
analysis. The maintained error mapping defines these families;
there is no generic exit 5.
Run the same checks as CI locally:
./scripts/ci-local.shInstall the pre-commit hook:
./scripts/install-hooks.shFor an explicit forge.workspace.json, the unreleased Trace & Reports
browser panel and maintained Python client's bundle_preview() and
verify_bundle(bundle) inspect complete registrations and compare supplied
fingerprints in either session mode. Preview metadata and acknowledge its
sensitivity before requesting the browser's local metadata JSON download. This
writes no project file or server receipt, includes no source content and
establishes no approval.
Choose a metadata JSON file, then explicitly compare registered fingerprints. Its original bytes plus the 11-byte wrapper must fit 1 MiB, so the selected file may be at most 1,048,565 bytes. The server rejects malformed/unsupported input without opening supplied unregistered paths. Missing/empty index, subset agreement/current-only entries, whole-index equality and observed validation state remain separate. Queries keep the complete expected denominator up to 1,000 within byte limits and prepare no 100-input effect.
See Workspace index bundles for the Python example,
normalized index hash versus original resource hashes and safe errors.
Negotiated API2.2, 2.3 or 2.4 sessions offer confirmed metadata receipts and index
replacement; API2.3 and 2.4 admit opt-in exact-source
export and complete source restore. The current captured API2.4 source adds
bounded staged part transfer. Exact-tree
hosted API and Chrome staged-source development workflows at the historical
F12 c2fa4cd checkpoint have scoped successful receipts; that same run
retains its headless and dependency-audit failures. This does not
establish full S-6, network-denial, platform or human acceptance. These writes require
preparation and a separate confirmation, with distinct known-ID recovery for
source restore. Full S-6 capacity, larger transfer and platform/crash/batch
qualification, human acceptance and the final integrated documentation review
remain open.
- README.md — project overview and quick start
- Container packaging — Docker/Compose build, CLI conversion and loopback workspace in containers
- Portable review queues — asserted review policy, immutable responses, recorded exports and explicit queue supersession
- Lifecycle review exchange candidate — separate
/2formats, candidate CLI commands and qualification limits - Authoring review exchange candidate — whole saved-plan
/3review, private inputs and qualification limits - Evidence and Implementation Linking — exact subject/evidence metadata linkage, freshness, privacy, and baseline contracts
- Evidence overlays — new Catalog/Component JSON documents, complete source preservation and generated metadata boundaries
- Contributing Guide — development setup and PR process
- Architecture Guide — pipeline details and crate structure
example_data/— 25 sample policiestests/fixtures/— test fixtures for all subcommands