From c8a476b26b6ee76dff809358ecea2e54d406fe31 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:34:39 +0300 Subject: [PATCH 01/14] docs(assurance): define commandF assurance program --- .../COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md | 203 ++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md diff --git a/docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md b/docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md new file mode 100644 index 00000000..383d1ee8 --- /dev/null +++ b/docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md @@ -0,0 +1,203 @@ +# commandF Assurance Program — 2026-08-26 + +Status: PLANNING_CANDIDATE + +## Purpose + +commandF has now shipped a substantial deterministic interoperability-analysis spine through canonical CF-13. The next risk is no longer "does the repository have tests?" The repository already has strong exact-head CI, deterministic proof workflows, fail-closed tests, real FHIR smoke, and independent review. The gap is that the quality of the development system itself is not yet uniformly measured or enforced. + +This program makes commandF's development and release evidence as explicit as its product evidence. + +It does **not** renumber or replace CF-14, CF-15, or CF-16. Those product identities remain governed by `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`. + +## Live baseline at program creation + +```text +canonical main: 8a45857bf31c4acae57fdfb1e3cdde3d0f7d0361 +canonical tree: ffaa14fdc7a738a771ac872e566ad1609eedf2cc +CF-13: CLOSED_CANONICAL +open product blocker: CF-10 remains separately blocked by the CF-06 production-oracle contract +``` + +The live repository audit established the following concrete gaps. + +### P0 — source and CI trust + +1. `main` has no branch protection and no active repository ruleset. Required status checks are therefore policy-by-convention rather than repository-enforced source-control policy. +2. The general `.github/workflows/ci.yml` still uses mutable `actions/checkout@v4`, mutable `dtolnay/rust-toolchain@1.97.1`, and `ubuntu-latest`. +3. Some later proof workflows already use stronger immutable action SHAs, credentialless checkout, fixed runner labels, and digest-pinned containers. The repository therefore has two assurance levels rather than one uniform baseline. +4. There is no repository-wide machine gate proving that every external GitHub Action reference is a full commit SHA and every checkout disables credential persistence unless an explicit reviewed exception exists. +5. There is no GitHub Actions static-analysis gate such as `zizmor` and no OpenSSF Scorecard evidence retained by commandF. +6. Dependency policy is implicit. There is no checked-in `cargo-deny` policy for licenses, sources, advisories, duplicate/banned crates, or explicit reviewed exceptions. +7. There is no dedicated RustSec audit gate against `Cargo.lock`. + +### P1 — test adequacy, not merely test count + +1. No fuzz workspace or fuzz targets exist. This is material because commandF processes untrusted package archives, JSON, lockfiles, reports, source maps, and graph evidence. +2. There is no structure-aware or differential fuzzing against parser/validator invariants. +3. There is no mutation-testing program to measure whether tests actually kill plausible logic defects. +4. There is no coverage evidence or per-change coverage floor. Coverage will be treated as a diagnostic and floor, not as a correctness score. +5. There is no explicit flaky-test detector. A test that only passes after retry must be visible as a defect, because reproducibility is a commandF contract. +6. There is no property-test layer for algebraic invariants such as canonicalization idempotence, serialization round trips, set/order semantics, graph-path determinism, and baseline/suppression equivalence. + +### P1 — portability and compatibility + +1. Canonical CI executes on Linux only. There is no Windows/macOS workspace gate despite filesystem, path, process, shell, and atomic-file behavior being platform-sensitive. +2. The workspace declares Rust `1.97.1`, but there is no explicit MSRV job that proves the declared toolchain remains sufficient separately from the primary CI image. +3. There is no automated Rust public-API/SemVer compatibility guard for `commandf-pkg`. +4. There is no release artifact verification pipeline, SBOM, build provenance attestation, or signature bundle. + +### P2 — performance and reliability evidence + +1. There are no checked-in micro/macro benchmark baselines or regression budgets for package scanning, graph construction, impact traversal, fingerprinting, and gate validation. +2. Live registry smoke is valuable external-contract evidence but is mixed into the general CI critical path. Deterministic core qualification and external availability sentinels should have distinct semantics and failure reporting. +3. There is no retained resource-envelope evidence for CPU time, peak memory, archive traversal, large graph size, or pathological input families beyond existing local bounds tests. + +### P2 — standards/version readiness and developer experience + +1. The current product core is strongly R4-proven. The repository does not yet expose a release-awareness matrix for R4, R4B, R5, and draft R6 surfaces. +2. HL7's publication directory records R5 `5.0.0` as the current published release and R6 `6.0.0-ballot5` as a draft ballot published 2026-07-17. Draft R6 evidence must never be presented as equivalent to a published release. +3. `README.md` still describes CF-01 as the first slice and omits canonical capabilities such as `context`, `impact`, and `gate`. + +## Program architecture + +The assurance program uses `AF-*` identities. `AF` means **Assurance Foundation** and is not a product-slice renumbering. + +### AF-01 — Trusted Development Baseline + +Goal: make source-control, workflow, dependency, and exact-head evidence policy mechanically enforceable. + +Ships independently executable verification results: + +- repository workflow-trust audit; +- dependency/license/source/advisory audit; +- GitHub Actions static-analysis result; +- retained exact-head assurance evidence; +- repository ruleset/branch-policy evidence. + +AF-01 is the immediate unit authorized by this program once its planning package is reviewed and merged. + +### AF-02 — Adversarial Test Strength + +Goal: measure whether commandF fails safely under generated, mutated, malformed, and adversarial inputs. + +Planned surfaces: + +- `cargo-fuzz` structure-aware targets for archive/JSON/report/lock/graph boundaries; +- differential fuzzing where an independent oracle or equivalent reference model exists; +- property tests for deterministic/canonical invariants; +- `cargo-mutants` targeted mutation score with reviewed exclusions; +- `cargo-llvm-cov` coverage diagnostics/floors; +- `cargo-nextest` CI profile with flaky retries reported as failure; +- minimized regression corpus promoted from every discovered crash or invariant violation. + +AF-02 must not weaken current `cargo test` authority. It adds evidence; it does not replace existing canonical gates. + +### AF-03 — Portability and Release Evidence + +Goal: prove that the shipped CLI/library and release artifacts are portable, versioned, and traceable. + +Planned surfaces: + +- Linux + Windows + macOS workspace qualification for platform-relevant code; +- explicit MSRV job for Rust `1.97.1` until deliberately changed; +- public-API/SemVer compatibility checks for the library surface; +- deterministic release artifact inventory; +- SBOM; +- SLSA-compatible build provenance; +- GitHub artifact attestation and/or Sigstore bundle verification where appropriate; +- release verification instructions that work without trusting a mutable tag alone. + +### AF-04 — Performance and Reliability Evidence + +Goal: prevent correctness-preserving changes from causing unbounded performance/resource regressions and separate deterministic qualification from external-service availability. + +Planned surfaces: + +- benchmark corpus and stable scenario IDs; +- wall-time/CPU/memory/size metrics with environment identity; +- regression budgets based on measured baselines, not guessed percentages; +- large-package and large-graph stress scenarios; +- external registry/oracle sentinel classification distinct from deterministic local gates; +- trend artifacts suitable for later commandF Bench reuse. + +AF-04 is internal assurance evidence. It is not the full future `commandF Bench` product. + +## Ordering and product-roadmap relationship + +```text +CF-13 CLOSED_CANONICAL + | + +--> AF-01 Trusted Development Baseline + | | + | +--> AF-02 Adversarial Test Strength + | +--> AF-03 Portability / Release Evidence + | +--> AF-04 Performance / Reliability Evidence + | + +--> CF-14 planning may proceed from canonical roadmap authority +``` + +Execution rule: + +- AF-01 must close before any new product implementation is merged after CF-13. +- CF-14 planning may proceed in parallel because planning does not create runtime authority. +- Any CF-14 parser/instance-data boundary introduced later must enter AF-02 fuzz/property coverage before that boundary can close canonically. +- AF-03 must close before commandF makes a stable public release claim. +- AF-04 must close before commandF makes quantitative performance/scalability claims. + +## Assurance principles + +1. **No vanity metric.** Line coverage, mutation score, fuzz time, Scorecard score, and benchmark speed are evidence dimensions, not a single trust score. +2. **Exact-head evidence.** Assurance results bind to exact source/tree/tool identities just as CF proof workflows do. +3. **Fail closed.** A missing required assurance result is not silently treated as pass. +4. **No hidden retries.** Flaky tests remain defects; retry may diagnose but must not convert a flaky result into canonical green. +5. **Reproduce before widening.** Fuzz crashes and mutation gaps become minimized deterministic regressions before a fix is considered closed. +6. **Pinned external tooling.** Tool versions, actions, containers, advisory databases, and benchmark corpora are recorded explicitly where they affect proof. +7. **Separation of external availability.** Network service outages are reported distinctly from deterministic product failure. +8. **No PHI.** Assurance corpora remain synthetic/public and license-governed. +9. **No oracle laundering.** Independent tools inform commandF; they do not become hidden semantic authority. +10. **Small stacks.** Each assurance implementation PR must be independently reviewable and preserve existing product semantics. + +## Current external evidence that constrains the program + +- GitHub Secure Use: full-length commit SHA is the immutable way to pin an Action; repository/organization policies can require this. +- SLSA v1.2 is the current approved SLSA specification and includes Build and Source tracks plus provenance/verification guidance. +- Sigstore bundles carry verification material and signature content required for offline-capable verification. +- Rust Fuzz Book recommends `cargo-fuzz`; structure-aware fuzzing is appropriate for structured domains and supports differential fuzzing. +- `cargo-mutants` measures whether plausible source mutations are caught by the existing test suite. +- `cargo-nextest` can detect retries as flaky and can be configured so a flaky result still fails CI. +- `cargo-deny` checks licenses, bans, advisories, and crate sources. +- RustSec `cargo-audit` audits `Cargo.lock` for known Rust ecosystem vulnerabilities. +- `cargo-llvm-cov` provides source-based coverage with enforceable line/function/region floors. +- `zizmor` statically analyzes GitHub Actions for injection, credential, permission, and reference risks. +- OpenSSF Scorecard provides an additional repository security posture view; it remains supplemental evidence, not a substitute for commandF-owned gates. +- HL7 FHIR publication history currently distinguishes R5 `5.0.0` (published) from R6 `6.0.0-ballot5` (draft ballot). + +## Primary references + +- https://docs.github.com/en/actions/reference/security/secure-use +- https://slsa.dev/spec/v1.2/ +- https://docs.sigstore.dev/about/bundle/ +- https://rust-fuzz.github.io/book/cargo-fuzz.html +- https://rust-fuzz.github.io/book/cargo-fuzz/structure-aware-fuzzing.html +- https://mutants.rs/ +- https://nexte.st/docs/features/retries/ +- https://embarkstudios.github.io/cargo-deny/checks/ +- https://rustsec.org/ +- https://github.com/taiki-e/cargo-llvm-cov +- https://docs.zizmor.sh/ +- https://github.com/ossf/scorecard-action +- https://hl7.org/fhir/directory.html + +## Explicitly not authorized by this document + +This program document alone does not authorize: + +- production code changes outside an approved AF/CF Spec Kit unit; +- a CF-06 production oracle pin change; +- mutation of the frozen CF-10 corpus; +- PHI or real patient-instance fixtures; +- AI/model authority; +- a stable release claim; +- a universal trust score; +- implementation of CF-14, CF-15, or CF-16 ahead of their own Spec Kit packages. From 2f255c53cf3a7d24e01d52e1454efe72cebbc444 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:35:25 +0300 Subject: [PATCH 02/14] docs(af01): specify trusted development baseline --- .../spec.md | 212 ++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 specs/015-af-01-trusted-development-baseline/spec.md diff --git a/specs/015-af-01-trusted-development-baseline/spec.md b/specs/015-af-01-trusted-development-baseline/spec.md new file mode 100644 index 00000000..6e783a37 --- /dev/null +++ b/specs/015-af-01-trusted-development-baseline/spec.md @@ -0,0 +1,212 @@ +# AF-01 Specification — Trusted Development Baseline + +Status: PLANNING_CANDIDATE + +## Identity + +`AF-01` is the first commandF Assurance Foundation unit. It is cross-cutting development/release assurance, not a replacement or renumbering of product slice CF-14. + +Canonical planning base: + +```text +main: 8a45857bf31c4acae57fdfb1e3cdde3d0f7d0361 +tree: ffaa14fdc7a738a771ac872e566ad1609eedf2cc +CF-13: CLOSED_CANONICAL +``` + +## User problem + +commandF's product evidence is increasingly rigorous, but the repository does not yet enforce the same trust level uniformly across source control, workflows, third-party Actions, dependency policy, and security checks. + +Today a maintainer can observe green exact-head workflows, but GitHub does not itself prevent a direct or insufficiently qualified update to `main`. The general CI workflow also still contains mutable Action/tool references that are weaker than commandF's newer proof workflows. + +The result is a mismatch: commandF can prove interoperability evidence more strongly than it proves the integrity of the development path that produced that evidence. + +## Outcome + +After AF-01 closes, commandF has an independently executable and reviewable trusted-development baseline that: + +1. detects mutable or unsafe GitHub Actions references; +2. minimizes workflow token/checkout authority; +3. audits Rust dependency vulnerabilities, licenses, sources, and banned/duplicate dependency policy; +4. statically audits workflow definitions for known CI/CD security hazards; +5. records exact-head assurance evidence; +6. requires repository-level source-control policy for canonical `main` so green checks are enforced rather than advisory. + +## Functional requirements + +### FR-001 — repository workflow trust audit + +Provide a repository-owned deterministic audit that scans tracked GitHub workflows and composite Actions and fails if an external `uses:` reference is not pinned to a full 40-hex Git commit SHA unless an explicit bounded exception is recorded in the AF-01 policy. + +The audit must also detect at least: + +- checkout steps that persist credentials without an explicit reviewed exception; +- workflow/job permissions broader than their documented need where mechanically detectable; +- use of `ubuntu-latest`, `windows-latest`, or `macos-latest` in proof-critical jobs where AF-01 requires a fixed runner label; +- new workflow files that are outside the audit scope. + +The audit result must be deterministic for the same repository tree. + +### FR-002 — workflow hardening + +All existing commandF workflows must be reconciled to a documented minimum baseline: + +- external Actions use full commit SHAs; +- checkout uses `persist-credentials: false` unless a documented write operation requires otherwise; +- top-level/job `permissions` are explicit and least-privilege for the workflow purpose; +- proof-critical workflows use fixed runner labels and retain or improve digest-pinned execution containers where already present; +- `cargo` commands that consume the lockfile use `--locked`; +- no product semantic gate is removed or weakened to make hardening pass. + +Fixed GitHub-hosted runner labels are not claimed to make the underlying runner image byte-immutable. Proof workflows that require stronger execution identity must use an explicit container/toolchain identity and record it. + +### FR-003 — dependency policy + +Add checked-in `cargo-deny` policy covering: + +- advisories; +- accepted licenses; +- crate source policy; +- duplicate/banned crate policy; +- explicit exceptions with rationale. + +Policy must default to fail closed for unknown git/registry sources not intentionally authorized. + +License policy must be derived from the actual dependency graph and commandF donor/provenance policy rather than copied blindly from another repository. + +### FR-004 — RustSec vulnerability audit + +Add an independently executable `cargo audit` gate against the exact `Cargo.lock` used by the candidate tree. + +A vulnerability/advisory waiver must include: + +- advisory or crate identity; +- reason; +- affected scope; +- compensating evidence where applicable; +- revisit/removal condition. + +Absence of a vulnerability finding is not a claim that the dependency graph is generally secure. + +### FR-005 — GitHub Actions static analysis + +Add a pinned `zizmor` audit over repository workflow/composite-action definitions. + +The commandF-owned workflow-trust audit remains authoritative for commandF's explicit pinning/credential rules. `zizmor` is an independent static-analysis signal and does not replace repository-owned policy. + +### FR-006 — OpenSSF Scorecard evidence + +Add or document an OpenSSF Scorecard run for the public repository, retaining exact tool/action identity and result provenance where the integration permits it. + +Scorecard is supplemental posture evidence. No minimum aggregate Scorecard number is a commandF correctness gate in AF-01. + +### FR-007 — main source-control enforcement + +Canonical `main` must have repository-level branch/ruleset enforcement that, at minimum: + +- blocks non-PR direct changes except a narrowly defined administrator/break-glass path; +- requires the current canonical CI/assurance checks selected by AF-01; +- requires review according to repository governance; +- rejects unresolved required review conversations where supported; +- prevents force-push and branch deletion for `main`; +- does not allow a stale prior-head PASS to satisfy a moved PR head. + +The exact GitHub ruleset configuration is operational repository metadata, not a substitute for checked-in workflow policy. + +If the active automation connector cannot mutate rulesets, AF-01 must record that limitation and remains open until an authorized administrator applies the exact configuration and live GitHub evidence verifies it. + +### FR-008 — exact-head assurance evidence + +Add a dedicated AF-01 proof workflow or equivalent retained artifact that records at least: + +- exact head SHA and tree SHA; +- hashes/identities for the AF-01 spec/plan/tasks/consistency files; +- exact workflow-trust audit result; +- exact dependency-policy result; +- exact RustSec audit result; +- exact workflow static-analysis result; +- tool/action/container versions or immutable refs used; +- repository ruleset/branch-protection observation when queryable; +- a final deterministic assurance summary digest. + +No timestamp is used as evidence identity. + +### FR-009 — no regression in product authority + +AF-01 must not change: + +- CF-03 structural semantics; +- CF-04 compatibility rules; +- CF-05 policy semantics; +- CF-06 production oracle identity; +- CF-07 terminology semantics; +- CF-09 source-mapping semantics; +- CF-10 frozen corpus; +- CF-11/11G graph identities; +- CF-12 impact semantics; +- CF-13 baseline/suppression/gate semantics. + +### FR-010 — reviewer truth + +AF-01 planning and implementation must request CodeRabbit and Qodo when available. Returned findings must be dispositioned against the exact candidate head. Reviewer absence, timeout, rate limit, or summary-only output is not a PASS. + +Codex Review is not required for AF-01. + +## Non-functional requirements + +### NFR-001 Determinism + +Repository-owned audits and proof summaries must be byte-stable for identical pinned inputs wherever external advisory-database content is not itself part of the input. + +When an advisory database or external security service is used, its identity/update state must be recorded so a later result can explain drift. + +### NFR-002 Least authority + +Security workflows must not receive write permissions merely to report read-only findings unless the reporting mechanism itself requires a narrowly scoped write permission. + +### NFR-003 Bounded execution + +Every new CI job must define a bounded timeout appropriate to its function. External network checks must have bounded retry/timeout policy and must not retry indefinitely. + +### NFR-004 No PHI + +No patient data or PHI is introduced. + +### NFR-005 Stackability + +Implementation is split into independently reviewable stacks; a single monolithic workflow rewrite is not acceptable if it obscures which security property changed. + +## Acceptance scenarios + +1. A workflow changes `actions/checkout@` to `actions/checkout@v5` -> repository workflow-trust audit fails. +2. A new workflow uses credential-persisting checkout without an allowed exception -> fails. +3. A dependency is added from an unapproved git source -> `cargo-deny` fails. +4. A dependency introduces a RustSec advisory -> vulnerability gate fails unless an explicit reviewed waiver exists. +5. A workflow contains a security issue detected by the configured `zizmor` severity policy -> audit fails or is explicitly dispositioned according to the frozen policy. +6. The same tree is audited twice with the same pinned tool/advisory inputs -> commandF-owned assurance summary bytes are identical. +7. Product test suites and all path-applicable existing proof workflows remain green. +8. Live GitHub query confirms the intended `main` source-control policy before AF-01 claims canonical closure. + +## Edge cases + +- GitHub Actions referenced through local `./` paths are local source, not external mutable tags. +- Docker images referenced by digest are acceptable immutable identities; mutable image tags alone are not proof identity. +- Reusable workflows require the same immutable-reference discipline as third-party Actions where GitHub supports commit-SHA references. +- Scorecard or advisory-service unavailability must be distinguished from a clean security result. +- A security tool finding that is not applicable may be dispositioned, but the disposition and rationale become retained evidence. +- `cargo-deny` duplicate-version policy must not blindly reject legitimate unavoidable transitive duplication without review; exceptions are explicit and narrow. + +## Explicit non-goals + +AF-01 does not implement: + +- fuzzing, mutation score, property testing, or coverage floors — AF-02; +- Windows/macOS portability matrices or release signing — AF-03; +- benchmark/performance budgets — AF-04; +- CF-14 profiler behavior; +- CF-15 AutoFix recipes; +- CF-16 mapping IR; +- CF-06 production-pin changes; +- CF-10 corpus changes; +- AI/model/agent authority. From 6dd4367c712a32878c4ceffad1510c8c9060095e Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:36:27 +0300 Subject: [PATCH 03/14] docs(af01): plan trusted development baseline --- .../plan.md | 343 ++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 specs/015-af-01-trusted-development-baseline/plan.md diff --git a/specs/015-af-01-trusted-development-baseline/plan.md b/specs/015-af-01-trusted-development-baseline/plan.md new file mode 100644 index 00000000..e8cfbe56 --- /dev/null +++ b/specs/015-af-01-trusted-development-baseline/plan.md @@ -0,0 +1,343 @@ +# AF-01 Plan — Trusted Development Baseline + +Status: PLANNING_CANDIDATE + +## Entry condition + +AF-01 planning begins from canonical `main` after CF-13 closeout merged: + +```text +main: 8a45857bf31c4acae57fdfb1e3cdde3d0f7d0361 +tree: ffaa14fdc7a738a771ac872e566ad1609eedf2cc +CF-13: CLOSED_CANONICAL +``` + +AF-01 does not depend on the externally blocked CF-10/CF-06 production-oracle path. + +Implementation starts only after this planning package and the assurance-program/index/architecture reconciliation are reviewed, exact-head green, and merged to canonical `main`. + +## Design summary + +AF-01 introduces no product semantic engine. It adds an independently executable development-assurance layer around the repository that makes workflow immutability, dependency policy, security analysis, and canonical-branch enforcement explicit. + +The design deliberately has two classes of evidence: + +1. **checked-in deterministic policy evidence** — repository scripts/configuration/workflows that can be reviewed and repeated from the source tree; +2. **live source-control evidence** — GitHub ruleset/branch state that must be queried from the hosting platform and cannot be inferred from files alone. + +AF-01 cannot be `CLOSED_CANONICAL` unless both classes are satisfied. + +## Baseline findings to remediate + +### General CI + +Current `.github/workflows/ci.yml` uses: + +```text +runs-on: ubuntu-latest +actions/checkout@v4 +dtolnay/rust-toolchain@1.97.1 +``` + +These are less reproducible than later commandF proof workflows, which already use full action SHAs, fixed runner labels, credentialless checkout, and in some cases digest-pinned containers. + +### Repository settings + +Live GitHub state at planning creation: + +```text +main protected: false +branch protection enabled: false +required status check enforcement: off +repository rulesets: none observed +``` + +### Missing assurance surfaces + +No checked-in configuration/workflow currently exists for: + +- cargo-deny; +- cargo-audit; +- zizmor; +- OpenSSF Scorecard; +- repository-owned verification that all workflow references stay immutable/credential-minimal. + +## Implementation architecture + +### Stack A — repository-owned workflow trust audit + baseline hardening + +Add a small repository-owned audit script, preferably under `.github/scripts/`, with no new runtime dependency in the product crates. + +Expected responsibilities: + +1. enumerate tracked `.github/workflows/*.yml|*.yaml` and repository composite `action.yml` files; +2. parse or conservatively inspect all external `uses:` references; +3. permit local `./` references; +4. require external action refs to end in a full 40-hex commit SHA; +5. inspect checkout steps and require `persist-credentials: false` unless the policy file names a specific bounded exception; +6. flag proof-critical `*-latest` runner labels according to the AF-01 policy; +7. ensure newly added workflow files cannot escape the audit by using a complete tracked-file enumeration rather than a hard-coded subset; +8. emit deterministic machine-readable result plus a concise human-readable failure report. + +Implementation language should minimize new dependencies. A small Python standard-library or shell+Python verifier is acceptable because it is repository CI tooling, not commandF trusted product runtime. The product core remains Rust-owned. + +Workflow updates in the same stack must: + +- replace mutable external action tags with verified full SHAs; +- set `persist-credentials: false` on read-only checkout; +- change proof-critical runner labels from `*-latest` to explicit supported labels such as `ubuntu-24.04` where the job semantics allow it; +- preserve all existing steps/assertions/path filters; +- add timeouts if a touched job lacks one and an appropriate bound can be established; +- keep `cargo --locked` semantics. + +Do not bulk-reformat unrelated YAML. + +### Stack B — Rust dependency and workflow security gates + +#### cargo-deny + +Add `deny.toml` with policy derived from the actual current graph. + +Required checks: + +```text +licenses +bans +advisories +sources +``` + +Policy rules: + +- unknown registry/git sources denied by default; +- accepted licenses explicitly enumerated after inspecting current dependency metadata; +- duplicate versions are reported and reviewed rather than globally denied until the current graph is understood; +- wildcards disallowed for direct dependencies where supported by policy; +- advisory ignores require structured rationale and revisit condition; +- exceptions should be narrow package/version identities, not broad families. + +Run `cargo deny check` from an AF-01 workflow with an exact pinned cargo-deny version or immutable execution image identity. + +#### cargo-audit + +Run a pinned `cargo audit` against exact `Cargo.lock`. + +Keep cargo-audit separately visible even though cargo-deny can consume RustSec advisories because: + +- RustSec audit is a recognizable independent vulnerability surface; +- results can be compared against cargo-deny advisory policy; +- disagreement itself becomes useful evidence. + +No duplicate PASS is claimed if both tools depend on the same advisory database state; evidence records their relationship. + +#### zizmor + +Run a pinned zizmor version over repository workflows/actions. + +AF-01 freezes a severity policy in the plan implementation commit. Initial target: + +- fail on high/medium findings unless explicitly dispositioned; +- report lower severities as retained evidence until enough baseline data exists to justify stricter policy. + +If the first real run shows a different severity calibration is appropriate, update the AF-01 plan/tasks before merging implementation rather than silently weakening the command. + +### Stack C — posture evidence, proof artifact, and source-control enforcement + +#### OpenSSF Scorecard + +Add Scorecard in the least-authority supported mode for this public repository. Pin the action to a verified full commit SHA. If publishing results requires `id-token: write` or `security-events: write`, scope those permissions only to the Scorecard job. + +Do not gate on a single aggregate score. Retain per-check evidence and specifically inspect at least: + +- Branch-Protection; +- Dangerous-Workflow; +- Pinned-Dependencies; +- Token-Permissions; +- Security-Policy where applicable; +- Vulnerabilities. + +#### AF-01 proof workflow + +Add `.github/workflows/af01-assurance-proof.yml` with complete path coverage for: + +- AF-01 spec package; +- assurance program/index/architecture documents; +- workflow files; +- action.yml and repository CI scripts; +- Cargo manifests/lockfile; +- `deny.toml` and any AF-01 policy/config files; +- AGENTS/constitution when they affect authority. + +Proof should run in a pinned environment consistent with the best existing commandF proof workflows. + +Expected retained artifact contents: + +```text +assurance-summary.json +workflow-trust.json +cargo-deny.txt/json if supported +cargo-audit.json or machine-readable equivalent +zizmor.sarif/json +tool-identities.txt +source-identities.txt +``` + +The final summary has a stable schema and records a deterministic digest, for example: + +```text +AF01_ASSURANCE_SHA256=<64 lowercase hex> +``` + +Live GitHub ruleset state is kept separately because hosting-platform metadata can change without changing the repository tree. The convergence record binds the exact live observation used for closure. + +#### Main ruleset + +Target source-control policy: + +- applies to `refs/heads/main`; +- branch deletion prohibited; +- force-push prohibited; +- pull request required; +- required review count at least 1 unless governance specifies stronger; +- required conversations resolved; +- stale approvals dismissed or latest-push approval semantics configured so moved heads cannot inherit stale approval; +- required status checks include the AF-01-selected canonical checks; +- administrator/bypass actors minimized and documented; +- no broad bypass based solely on actor type. + +Exact check names must be derived from the final implementation workflows after they are canonical; do not guess names before jobs exist. + +The current connector exposes ruleset/branch-protection reads but not writes. Therefore this configuration is an explicit external operational task. AF-01 cannot mark it complete until a live read proves it. + +## Security and trust boundary + +AF-01 security tooling runs against repository source/dependency metadata only. + +- no PHI; +- no patient instances; +- no model/provider credentials; +- no CF-06 production identity mutation; +- no code execution from untrusted PR-supplied arbitrary scripts beyond the repository's existing CI model; +- third-party actions/tools are pinned and least-authority; +- network access used for advisory databases/Scorecard is explicit and bounded. + +Fork PR security must be considered before any workflow is granted write permissions or secrets. `pull_request_target` is not introduced by AF-01 unless a separate threat-model amendment proves it necessary. + +## Determinism model + +### Fully deterministic inputs + +- repository workflow trust audit; +- exact `Cargo.lock` graph inspection when dependency/advisory external state is excluded; +- source/config hashes; +- proof summary construction over retained normalized inputs. + +### Externally versioned inputs + +- RustSec advisory database; +- OpenSSF Scorecard service/action behavior; +- live GitHub ruleset state. + +These must record version/commit/update identity where available. Their results are reproducible only relative to that external input identity and must not be described as timeless. + +## Test plan + +### Workflow-trust audit positive + +- all existing hardened workflows pass; +- local `uses: ./` accepted; +- full 40-hex refs accepted; +- credentialless checkout accepted; +- fixed proof runner accepted. + +### Workflow-trust audit negative + +- `actions/checkout@v5` rejected; +- shortened SHA rejected; +- branch ref rejected; +- tag ref rejected; +- checkout without explicit `persist-credentials: false` rejected; +- new unscanned workflow path causes coverage test failure; +- proof-critical `ubuntu-latest` rejected according to policy; +- malformed workflow input fails closed rather than being skipped. + +### Dependency policy + +- current graph passes only after every accepted license/source is explicitly represented; +- synthetic/config fixture for unknown git source rejected where practical; +- waiver schema rejects missing rationale/revisit metadata if commandF wraps waiver validation; +- direct wildcard dependency policy is checked; +- cargo-audit output is retained even when clean. + +### zizmor + +- all workflows collected; +- baseline findings either fixed or explicitly documented; +- high/medium new finding makes AF-01 gate fail according to final frozen policy. + +### Proof + +- repeated exact-tree repository-owned audit outputs equal; +- summary digest recomputes exactly; +- source SHA/tree recorded correctly; +- proof fails if one required evidence file is missing; +- dirty repository or source mismatch fails where the proof environment supports the check. + +### Regression + +All existing mandatory repository gates remain: + +```text +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace --all-features +``` + +and every path-applicable existing proof/oracle workflow must remain green on each implementation head. + +## Migration impact + +Developer-visible changes: + +- CI will reject mutable Action references and new unreviewed workflow authority; +- dependency additions may require license/source/advisory policy updates; +- canonical main will require PR/check/review policy once the ruleset is applied; +- emergency/break-glass changes become explicit governance events rather than ordinary direct pushes. + +No commandF CLI or report schema changes are planned. + +## Performance impact + +AF-01 adds CI work. Keep it bounded: + +- workflow-trust audit should complete in seconds; +- cargo-deny/audit may use caching but cache identity must not make the result authoritative; +- Scorecard/zizmor should be separate jobs so they can be diagnosed independently; +- do not put long-running AF-02 fuzz/mutation work into AF-01. + +## Stack ordering + +```text +Planning package + -> Stack A workflow trust audit + workflow baseline hardening + -> Stack B dependency/security static gates + -> Stack C assurance proof + Scorecard + live main ruleset evidence + -> convergence +``` + +Stack B may branch from canonical Stack A. Stack C may branch only after Stack B is canonical unless the PR stack explicitly preserves exact dependencies and the repository governance supports that stack. + +## Closure criteria + +AF-01 is `CLOSED_CANONICAL` only when: + +1. planning package canonical; +2. every implementation stack merged from an exact green/reviewed head; +3. all AF-01 functional requirements proven or explicitly deferred by an amended canonical plan with rationale; +4. live `main` ruleset/branch-policy query proves required enforcement; +5. final AF-01 proof artifact retained with exact identities; +6. zero unresolved substantive review findings; +7. convergence document merged without semantic substitution; +8. canonical post-merge main/tree recorded. + +Implementation merge alone is insufficient for closure. From 3aada2cb3031f8791d53904ca2774126ab2a330b Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:37:11 +0300 Subject: [PATCH 04/14] docs(af01): define assurance task graph --- .../tasks.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 specs/015-af-01-trusted-development-baseline/tasks.md diff --git a/specs/015-af-01-trusted-development-baseline/tasks.md b/specs/015-af-01-trusted-development-baseline/tasks.md new file mode 100644 index 00000000..d8ec72fe --- /dev/null +++ b/specs/015-af-01-trusted-development-baseline/tasks.md @@ -0,0 +1,108 @@ +# AF-01 Tasks — Trusted Development Baseline + +Status: PLANNING_CANDIDATE + +## Task-state rules + +- A checkbox is completed only by exact repository/GitHub evidence, not by intent. +- Any head mutation invalidates prior exact-head implementation/review qualification unless the affected gate explicitly proves it is content-independent. +- Product semantics remain frozen throughout AF-01. +- No implementation task begins until T005 is canonical. +- AF-01 cannot close while the live `main` ruleset/branch-policy requirement remains unproven. + +## Phase 0 — planning and authority + +- [x] **T001** Record canonical entry identity: `main=8a45857bf31c4acae57fdfb1e3cdde3d0f7d0361`, tree `ffaa14fdc7a738a771ac872e566ad1609eedf2cc`, CF-13 `CLOSED_CANONICAL`. +- [x] **T002** Audit current repository assurance gaps: unprotected `main`; mixed mutable/immutable workflow references; missing cargo-deny/cargo-audit/zizmor/Scorecard; no fuzz/mutation/coverage/portability/release assurance program; stale README capability surface. +- [x] **T003** Research current primary guidance for GitHub Actions full-SHA pinning, SLSA v1.2, Sigstore bundles, Rust fuzzing/mutation/coverage/security tooling, and HL7 FHIR release status. +- [x] **T004** Add `docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md` and AF-01 Spec Kit planning package; preserve CF-14/15/16 identities. +- [ ] **T005** Planning gate: exact final planning head passes all path-applicable CI, independent CodeRabbit/Qodo review truth is recorded without invented PASS, zero unresolved substantive planning findings remain, and planning PR is merged to canonical `main`. + +## Phase 1 / Stack A — workflow trust audit and baseline hardening + +Depends on T005. + +- [ ] **T010** Inventory every tracked `.github/workflows/*.yml|*.yaml`, repository composite Action, external `uses:` reference, runner label, job permission, checkout credential setting, and cargo lockfile-consuming command on canonical planning main. +- [ ] **T011** Define a minimal checked-in AF-01 workflow-trust policy format, including any narrowly scoped exception schema with reason/revisit condition. +- [ ] **T012** Implement repository-owned deterministic workflow-trust audit with complete tracked-workflow discovery, local-action allowance, full-40-hex external action requirement, checkout credential check, and proof-runner policy. +- [ ] **T013** Add positive and counterexample tests for T012, including tag/branch/short-SHA rejection, missing `persist-credentials: false`, new-workflow coverage, malformed input fail-closed behavior, and deterministic repeat output. +- [ ] **T014** Harden `.github/workflows/ci.yml` to full-SHA external Actions, credentialless checkout, explicit least permissions, fixed supported runner label, bounded timeout, and preserved existing semantic/test steps. +- [ ] **T015** Reconcile every other existing workflow to the AF-01 baseline without changing its product/oracle/proof semantics or path-filter authority. +- [ ] **T016** Add a regression that scans all tracked workflow/action files and fails if a future workflow escapes AF-01 trust auditing. +- [ ] **T017** Run mandatory workspace gates and every path-applicable existing proof/oracle workflow on the exact Stack A head. +- [ ] **T018** Request CodeRabbit and Qodo on exact Stack A head; disposition every substantive returned finding and require zero unresolved material review threads. +- [ ] **T019** Merge Stack A only from its exact qualified head and record canonical merge/main/tree. + +## Phase 2 / Stack B — dependency and CI security gates + +Depends on canonical T019. + +- [ ] **T020** Inspect the exact current Cargo dependency graph and license/source metadata; document intended direct/transitive source and license policy before generating `deny.toml`. +- [ ] **T021** Add checked-in `deny.toml` covering licenses, bans/duplicates, advisories, and sources with narrow reviewed exceptions only. +- [ ] **T022** Add pinned `cargo-deny` execution in an independently diagnosable CI job; retain machine-readable or complete textual evidence. +- [ ] **T023** Add pinned RustSec `cargo-audit` execution against exact `Cargo.lock`; retain advisory database/tool identity where available. +- [ ] **T024** Define waiver documentation requirements for any advisory/security exception: identity, rationale, scope, compensating evidence, and revisit/removal condition. +- [ ] **T025** Add pinned `zizmor` audit over all repository workflows/actions; freeze initial severity policy from observed baseline rather than guessing around findings. +- [ ] **T026** Fix valid high/medium workflow findings or amend the plan/tasks with explicit reviewed disposition; do not lower the gate silently. +- [ ] **T027** Add regressions proving dependency/workflow security configurations are included in relevant workflow path filters so policy mutations cannot bypass gates. +- [ ] **T028** Run mandatory workspace gates plus all path-applicable existing proof/oracle workflows on exact Stack B head. +- [ ] **T029** Obtain and disposition CodeRabbit/Qodo review on exact Stack B head, merge only from exact qualified head, and record canonical merge/main/tree. + +## Phase 3 / Stack C — posture evidence, AF-01 proof, and main enforcement + +Depends on canonical T029. + +- [ ] **T030** Add pinned OpenSSF Scorecard integration in least-authority mode appropriate for this public repository; retain per-check evidence and do not use aggregate score as commandF correctness authority. +- [ ] **T031** Inspect Scorecard results for at least Branch-Protection, Dangerous-Workflow, Pinned-Dependencies, Token-Permissions, Security-Policy where applicable, and Vulnerabilities; disposition material findings. +- [ ] **T032** Implement `.github/workflows/af01-assurance-proof.yml` with complete AF-01 path coverage and immutable/pinned execution inputs consistent with commandF proof policy. +- [ ] **T033** Define stable `assurance-summary.json` schema and deterministic `AF01_ASSURANCE_SHA256`, binding exact source/tree, policy/config blobs, workflow audit, dependency audit, RustSec audit, zizmor evidence, and tool identities. +- [ ] **T034** Add proof tests for repeated summary equality, source/tree mismatch, missing required evidence, malformed evidence, and dirty/unexpected source where applicable. +- [ ] **T035** Determine final required status-check names from canonical implementation workflows; do not guess names before they exist. +- [ ] **T036** Prepare exact `main` ruleset configuration: PR required, at least one review, required conversations resolved, stale/latest-push review protection, selected status checks required, branch deletion/force-push blocked, and narrowly documented bypass actors only. +- [ ] **T037** Apply T036 through an authorized GitHub administrator path. Current connector read capability does not count as mutation authority. +- [ ] **T038** Query live GitHub after T037 and retain evidence proving the active ruleset/branch policy actually applies to `refs/heads/main` with intended enforcement. +- [ ] **T039** Negative governance proof: demonstrate or otherwise verify from authoritative GitHub configuration that direct/force/deletion/stale-head bypasses are blocked according to T036 without destructively rewriting repository history. +- [ ] **T040** Run exact-head AF-01 proof, mandatory workspace gates, and every path-applicable existing product proof/oracle workflow; retain artifact IDs/digests and tool/source identities. +- [ ] **T041** Obtain exact-head CodeRabbit/Qodo review; require zero unresolved substantive findings. +- [ ] **T042** Merge Stack C only from exact qualified head and verify post-merge `main`, tree, proof applicability, and live ruleset state. + +## Phase 4 — convergence + +Depends on T042. + +- [ ] **T050** Re-read `spec.md`, `plan.md`, `tasks.md`, assurance-program document, constitution, AGENTS, live GitHub policy, and implementation tree; reconcile any drift. +- [ ] **T051** Create `convergence.md` recording planning/Stack A/B/C identities, workflow run/job/artifact/digest evidence, dependency/security tool identities, reviewer dispositions, live ruleset evidence, limits, and deferrals. +- [ ] **T052** Confirm product-semantic diff from pre-AF-01 canonical base contains no unauthorized CF semantic change; any incidental product source mutation requires separate task/justification and full semantic qualification. +- [ ] **T053** Record remaining assurance work under AF-02/AF-03/AF-04 rather than falsely claiming fuzz/mutation/portability/release/performance completion. +- [ ] **T054** Exact convergence head receives path-applicable CI/review truth with zero unresolved substantive findings. +- [ ] **T055** Merge convergence PR and verify canonical post-merge main/tree plus live source-control policy. +- [ ] **T056** Mark `AF-01=CLOSED_CANONICAL` only after T055 evidence is complete. + +## AF-02 handoff retained, not authorized by AF-01 implementation + +After AF-01 closes, create a separate Spec Kit unit for adversarial test strength covering: + +- structure-aware/differential `cargo-fuzz`; +- property tests; +- `cargo-mutants` mutation adequacy; +- `cargo-llvm-cov` diagnostic floors; +- `cargo-nextest` flaky-as-failure policy; +- minimized regression corpus promotion. + +## AF-03 handoff retained + +- Linux/Windows/macOS qualification; +- explicit MSRV proof; +- Rust public API/SemVer guard; +- SBOM; +- SLSA/GitHub artifact provenance; +- Sigstore/offline verification where adopted; +- stable release verification. + +## AF-04 handoff retained + +- performance/resource benchmark corpus; +- measured regression budgets; +- large package/graph stress; +- external-service sentinel separation; +- trend evidence reusable by future commandF Bench. From abfeb288881ef37968ccea505a4c1b0111b540df Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:37:44 +0300 Subject: [PATCH 05/14] docs(af01): analyze planning consistency --- .../consistency.md | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 specs/015-af-01-trusted-development-baseline/consistency.md diff --git a/specs/015-af-01-trusted-development-baseline/consistency.md b/specs/015-af-01-trusted-development-baseline/consistency.md new file mode 100644 index 00000000..9ef99245 --- /dev/null +++ b/specs/015-af-01-trusted-development-baseline/consistency.md @@ -0,0 +1,164 @@ +# AF-01 Consistency Analysis + +Status: PLANNING_CANDIDATE + +## Scope + +This analysis reconciles: + +- `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`; +- `docs/COMMAND_F_PLAN_INDEX.md`; +- `docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md`; +- `.specify/memory/constitution.md`; +- `AGENTS.md`; +- AF-01 `spec.md`; +- AF-01 `plan.md`; +- AF-01 `tasks.md`; +- live GitHub repository/ruleset state observed at the canonical planning base. + +## Resolved consistency questions + +### 1. Does AF-01 renumber CF-14/15/16? + +No. + +`AF` is a cross-cutting Assurance Foundation identity. CF product identities remain: + +```text +CF-14 on-prem aggregate-only source profiler +CF-15 verified dry-run recipes +CF-16 mapping analysis IR, parse-only +``` + +Spec directory sequence `015` is only the next available Spec Kit package sequence after `014-cf-13-*`; it does not imply `CF-15`. + +### 2. Does AF-01 violate the constitution's vertical-capability rule? + +No. + +The constitution permits a user-visible command, report, annotation, **or independently executable verification result**. AF-01 ships independently executable repository assurance results and retained proof artifacts. It is not an empty infrastructure scaffold. + +### 3. Does AF-01 make future semantic layers dependencies of shipped commands? + +No. + +No commandF product command changes behavior. AF-01 wraps repository development assurance only. + +### 4. Does AF-01 replace deterministic product gates with third-party security tools? + +No. + +The commandF-owned workflow-trust audit is explicit repository policy. cargo-deny, cargo-audit, zizmor, and Scorecard are independent evidence inputs. No third-party aggregate score becomes semantic or correctness authority. + +### 5. Does cargo-deny conflict with the no-new-crate rule? + +No product crate is added merely for cargo-deny. It is an external development/CI tool used immediately by an executable assurance gate. If implementation proposes a Rust helper crate solely for assurance configuration, it requires separate justification and should be avoided unless directly necessary. + +### 6. Is using Python/shell for repository audit inconsistent with Rust ownership? + +No. + +AGENTS/constitution constrain commandF product/trusted interoperability core. Repository CI tooling may use bounded standard tooling. AF-01 explicitly keeps product runtime Rust-owned and avoids adding product dependencies for a CI-only parser. + +### 7. Does requiring full-SHA Actions contradict GitHub's release guidance that tags are convenient? + +No. + +GitHub's secure-use guidance states full-length commit SHA is the immutable Action reference. AF-01 deliberately chooses the stronger reproducibility/security posture because commandF proof policy already rejects mutable aliases as sufficient evidence. + +### 8. Is `ubuntu-24.04` itself immutable? + +No, and the plan does not claim it is. + +A fixed runner label narrows platform drift versus `ubuntu-latest`, but GitHub-hosted images still evolve. Proof-critical workflows that require stronger execution identity use digest-pinned containers/toolchain identities and retain them in evidence. + +### 9. Are cargo-deny and cargo-audit redundant? + +They overlap on RustSec advisory data, but serve different assurance roles. + +- cargo-deny: repository-owned policy across licenses, sources, bans/duplicates, and advisories. +- cargo-audit: focused independent RustSec vulnerability audit of `Cargo.lock`. + +AF-01 records that overlap and does not claim two independent vulnerability databases merely because two tools run. + +### 10. Is Scorecard an acceptance score? + +No. + +AF-01 uses per-check posture evidence. Aggregate score is not a commandF correctness gate. + +### 11. Can AF-01 close while `main` remains unprotected because the current connector cannot mutate rulesets? + +No. + +Connector capability is an execution limitation, not a waiver of the requirement. T037 is an external authorized administrator action and T038 requires a live read proving the resulting policy before AF-01 can close. + +### 12. Does AF-01 authorize CF-14 implementation? + +No. + +AF-01's program-level ordering allows CF-14 **planning** to proceed in parallel, but CF-14 implementation requires its own Spec Kit authority. No profiler source/data behavior is authorized here. + +### 13. Does AF-01 unblock CF-10 or change CF-06? + +No. + +CF-10 remains separately governed by the current CF-06 production-oracle contract. AF-01 must not mutate the HL7 production pin, frozen corpus, or semantic interpretation. + +### 14. Does AF-01 solve test adequacy comprehensively? + +No. + +It establishes the trusted development baseline. Fuzzing, property tests, mutation testing, coverage, and flaky-as-failure execution are explicitly retained for AF-02 rather than being implied complete. + +### 15. Does AF-01 make stable-release claims? + +No. + +SBOM, provenance/signing, public API compatibility, MSRV, and cross-platform release qualification are AF-03. + +### 16. Does the current FHIR release status require a product behavior change in AF-01? + +No. + +The research correction (R5 published current; R6 `6.0.0-ballot5` draft as of 2026-07-17) informs future version-readiness assurance. AF-01 does not expand FHIR semantic support. + +## Requirement-to-task trace + +| Requirement | Tasks | +|---|---| +| FR-001 workflow trust audit | T010-T013, T016 | +| FR-002 workflow hardening | T014-T019 | +| FR-003 cargo-deny policy | T020-T022, T027-T029 | +| FR-004 cargo-audit | T023-T024, T028-T029 | +| FR-005 zizmor | T025-T029 | +| FR-006 Scorecard | T030-T031 | +| FR-007 main source-control enforcement | T035-T039, T042 | +| FR-008 exact-head assurance proof | T032-T034, T040-T042 | +| FR-009 product authority unchanged | T014-T019, T028-T029, T040, T052 | +| FR-010 reviewer truth | T005, T018, T029, T041, T054 | +| NFR-001 determinism | T012-T013, T033-T034, T040 | +| NFR-002 least authority | T014-T015, T030-T032 | +| NFR-003 bounded execution | T014-T015, T022-T025, T030-T032 | +| NFR-004 no PHI | all implementation tasks | +| NFR-005 stackability | phase ordering T010-T056 | + +## Known planning risks retained explicitly + +1. **Ruleset mutation is external to the current connector.** Closure remains blocked until live policy is applied and observed. +2. **Security-tool version pinning requires exact implementation-time selection.** Planning names tools, not mutable `latest` versions. +3. **Initial cargo-deny policy cannot be safely guessed from generic examples.** T020 requires actual current dependency/license inspection first. +4. **Initial zizmor severity threshold may need calibration from real findings.** Any change is an explicit plan/task amendment, not silent weakening. +5. **Scorecard external availability/authentication can fail independently of repository correctness.** Operational failure is reported separately from clean posture. +6. **Fixed GitHub runner labels still drift internally.** Strong proof continues to prefer digest-pinned environments. + +## Final planning consistency result + +No unresolved architecture contradiction is known in the authored package. + +```text +AF-01 PLANNING CONSISTENCY: CANDIDATE / REQUIRES EXACT-HEAD CI + INDEPENDENT REVIEW +PRODUCT IDENTITIES CF-14/15/16: PRESERVED +CF-06/CF-10 AUTHORITY: UNCHANGED +IMPLEMENTATION AUTHORITY: NOT YET GRANTED +``` From e1dca4324832137ac7d03b53503e8d66909d43ee Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:38:15 +0300 Subject: [PATCH 06/14] docs(plan): add assurance program authority --- docs/COMMAND_F_PLAN_INDEX.md | 46 ++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/docs/COMMAND_F_PLAN_INDEX.md b/docs/COMMAND_F_PLAN_INDEX.md index 50aeb018..6b27b3b4 100644 --- a/docs/COMMAND_F_PLAN_INDEX.md +++ b/docs/COMMAND_F_PLAN_INDEX.md @@ -10,7 +10,7 @@ The commandF plan therefore consists of the following layers. `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md` -Defines product boundary, architecture planes, first execution stack, trust boundaries, and mandatory gates. When it conflicts with older bootstrap planning, V2 controls execution order. +Defines product boundary, architecture planes, first execution stack, trust boundaries, mandatory gates, and the relationship between cross-cutting Assurance Foundation work and CF product slices. When it conflicts with older bootstrap planning, V2 controls execution order. ## B. Discovery coverage authority @@ -92,17 +92,51 @@ Master's priority remains R1–R4. Research hypotheses never become product guar ## G. Feature execution units -Every `CF-*` slice is a Spec Kit-style feature unit: +Every `CF-*` product slice is a Spec Kit-style feature unit: ```text spec.md -> plan.md -> tasks.md -> implementation -> deterministic validation -> convergence.md ``` -CF-01 is the current feature unit under `specs/001-cf-01-package-resolution/`. +The same process is used for an `AF-*` Assurance Foundation unit when it creates independently executable verification authority around the repository rather than product semantics. + +Current canonical execution truth at the creation of the Assurance Program: + +```text +CF-13: CLOSED_CANONICAL +main: 8a45857bf31c4acae57fdfb1e3cdde3d0f7d0361 +next product identity: CF-14 +current cross-cutting planning unit: AF-01 +``` + +## H. Assurance-program authority + +`docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md` + +Preserves and sequences the cross-cutting work required to make commandF's own development/release evidence as rigorous as its interoperability evidence. + +Assurance units use `AF-*` identities and **do not renumber product CF slices**. + +Program units retained: + +1. **AF-01 Trusted Development Baseline** — source-control enforcement, immutable workflow references, least authority, dependency/license/source/advisory policy, CI/CD static analysis, exact-head assurance proof. +2. **AF-02 Adversarial Test Strength** — structure-aware/differential fuzzing, property tests, mutation adequacy, coverage diagnostics/floors, flaky-as-failure execution, minimized regression corpus. +3. **AF-03 Portability and Release Evidence** — Linux/Windows/macOS, MSRV, public API/SemVer guard, SBOM, SLSA-compatible provenance, artifact/signature verification. +4. **AF-04 Performance and Reliability Evidence** — measured benchmark/resource budgets, large-input stress, external-sentinel separation, retained trends reusable by future commandF Bench. + +Immediate authorized planning package once this index update is canonical: + +`specs/015-af-01-trusted-development-baseline/` + +Ordering rule: + +- AF-01 must close before a new post-CF-13 product implementation is merged. +- CF-14 planning may proceed in parallel under its own Spec Kit authority. +- AF-02/03/04 remain retained program units and require their own planning packages before implementation. ## Coverage rule -Before a future architecture supersedes V2, its review must reconcile this entire plan set. A candidate, product capability, gap, or research track may be: +Before a future architecture supersedes V2, its review must reconcile this entire plan set. A candidate, product capability, gap, assurance unit, or research track may be: - adopted - retained for later @@ -113,4 +147,6 @@ It may **not** disappear silently. ## Build-order rule -Preserving a candidate in the plan does not allow it to bypass the V2 execution sequence. A donor/tool/capability is activated only when a concrete slice requires it and its provenance/adoption gate is satisfied. +Preserving a candidate in the plan does not allow it to bypass the V2 execution sequence. A donor/tool/capability is activated only when a concrete CF or AF unit requires it and its provenance/adoption gate is satisfied. + +Assurance tooling is not exempt from this rule: naming cargo-fuzz, SLSA, Sigstore, Scorecard, cargo-deny, cargo-audit, zizmor, or any other tool in discovery/program documents is not adoption until the relevant AF plan pins the exact implementation identity and acceptance boundary. From 639ca68cbbd601e30c1174f437fda0c5598ed24a Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:38:50 +0300 Subject: [PATCH 07/14] docs(architecture): add assurance foundation sequence --- docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md | 38 +++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md b/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md index fbd153cf..528ff93f 100644 --- a/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md +++ b/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md @@ -119,6 +119,8 @@ Any future source profiler that touches instances must be a separate on-premises Each CF slice is a Spec Kit-style feature unit with `spec.md`, `plan.md`, and `tasks.md`, followed by consistency analysis, implementation, deterministic evidence, and a convergence pass. The specification states **what/why**; the plan states **how**; tasks are independently verifiable work items. Feature architecture must not be smuggled into the constitution or treated as completed merely because documentation exists. +Cross-cutting Assurance Foundation units use the same workflow when they create independently executable verification authority around commandF's source, CI, dependencies, testing, release, or performance evidence. They use `AF-*` identities and do not renumber product CF slices. + ## Roadmap identity reconciliation Canonical execution used `CF-11` for the multi-version package-graph foundation correction required to represent real transitive FHIR package closures. That completed history is retained exactly and is not renamed. @@ -133,6 +135,32 @@ CF-11G = ecosystem Context Graph + `commandf context` The graph slice consumes exact multi-version package identity from canonical CF-11 and canonical artifact inspection from CF-02. It does not depend on the external CF-06/CF-10 HL7-maintainer gate. +## Assurance Foundation reconciliation + +After CF-13 became canonical, a repository-wide review found that commandF's product proof was stronger than its uniformly enforced development/release baseline. In particular, canonical `main` was not protected by a ruleset, the general CI workflow retained mutable action/tool references, and the repository had no uniform dependency/license/source/advisory policy, workflow static analysis, fuzz/mutation adequacy program, cross-platform release matrix, or signed build-provenance path. + +These are cross-cutting assurance gaps rather than new interoperability product commands. They therefore use a separate identity family: + +```text +AF-01 = Trusted Development Baseline +AF-02 = Adversarial Test Strength +AF-03 = Portability and Release Evidence +AF-04 = Performance and Reliability Evidence +``` + +Detailed authority and sequencing live in: + +`docs/COMMAND_F_ASSURANCE_PROGRAM_2026-08-26.md` + +Rules: + +1. AF identities do not consume or rename CF-14/15/16. +2. AF-01 is the immediate post-CF-13 cross-cutting prerequisite and must close before a new post-CF-13 product implementation is merged. +3. CF-14 planning may proceed in parallel because planning creates no runtime authority. +4. AF-02/03/04 require their own Spec Kit packages before implementation. +5. Third-party assurance tools remain evidence inputs; no external score silently becomes commandF correctness authority. +6. The CF-06/CF-10 production-oracle governance path remains separate and unchanged. + ## First execution stack | Slice | User-visible result | Depends on | @@ -151,10 +179,13 @@ The graph slice consumes exact multi-version package identity from canonical CF- | CF-11G | ecosystem Context Graph + `commandf context` | CF-02, CF-11 | | CF-12 | `commandf impact` | CF-11G | | CF-13 | baselines/suppression/quality gates | CF-05 | -| CF-14 | on-prem aggregate-only source profiler | CF-02 | +| AF-01 | trusted-development verification evidence | post-CF-13 cross-cutting prerequisite | +| CF-14 | on-prem aggregate-only source profiler | CF-02, AF-01 before implementation merge | | CF-15 | verified dry-run recipes | CF-04, CF-09 | | CF-16 | mapping analysis IR, parse-only | CF-11G | +AF-02/03/04 are assurance-program units rather than product-stack identifiers and are sequenced in the Assurance Program document. Their completion rules are tied to the claims/features they protect rather than used to renumber the product roadmap. + ## Mandatory acceptance gates Every PR must satisfy: @@ -171,6 +202,8 @@ Every PR must satisfy: - Qodo review when connected/available - no merge of a stack whose exact candidate state is not green +AF-01 strengthens these repository gates rather than replacing them. Once an AF gate becomes canonical, future PRs must also satisfy the applicable canonical AF policy. + ## CF-01 authority CF-01 owns only FHIR package acquisition, dependency resolution, content-addressed caching, and deterministic locking. @@ -185,5 +218,8 @@ It does not validate FHIR resources, build snapshots, index canonicals, diff art - SQL-on-FHIR v2: https://sql-on-fhir.org/ig/2.0.0/ - GitHub Spec Kit: https://github.com/github/spec-kit - DeepSeek Harness: https://github.com/deepseek-ai/deepseek-harness +- GitHub Actions secure use: https://docs.github.com/en/actions/reference/security/secure-use +- SLSA v1.2: https://slsa.dev/spec/v1.2/ +- Rust Fuzz Book: https://rust-fuzz.github.io/book/ Research hypotheses remain separate from product guarantees. From 285fba4192d89ae5b3b2af6e65031236556b415b Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:43:50 +0300 Subject: [PATCH 08/14] docs(af01): close workflow trust review gaps --- .../spec.md | 34 +++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/spec.md b/specs/015-af-01-trusted-development-baseline/spec.md index 6e783a37..ec4503e7 100644 --- a/specs/015-af-01-trusted-development-baseline/spec.md +++ b/specs/015-af-01-trusted-development-baseline/spec.md @@ -26,8 +26,8 @@ The result is a mismatch: commandF can prove interoperability evidence more stro After AF-01 closes, commandF has an independently executable and reviewable trusted-development baseline that: -1. detects mutable or unsafe GitHub Actions references; -2. minimizes workflow token/checkout authority; +1. detects mutable or unsafe GitHub Actions references and mutable proof execution-container identities; +2. minimizes workflow token/checkout authority and rejects permissions broader than a checked-in documented need; 3. audits Rust dependency vulnerabilities, licenses, sources, and banned/duplicate dependency policy; 4. statically audits workflow definitions for known CI/CD security hazards; 5. records exact-head assurance evidence; @@ -42,11 +42,12 @@ Provide a repository-owned deterministic audit that scans tracked GitHub workflo The audit must also detect at least: - checkout steps that persist credentials without an explicit reviewed exception; -- workflow/job permissions broader than their documented need where mechanically detectable; +- workflow/job permissions broader than their documented need, using checked-in AF-01 policy metadata that makes the allowed permission set machine-checkable rather than relying on prose-only review; +- proof-critical job or service container images that use a mutable tag/reference instead of an accepted digest identity, unless an explicit bounded exception is recorded; - use of `ubuntu-latest`, `windows-latest`, or `macos-latest` in proof-critical jobs where AF-01 requires a fixed runner label; - new workflow files that are outside the audit scope. -The audit result must be deterministic for the same repository tree. +The audit result must be deterministic for the same repository tree and the same checked-in AF-01 policy. ### FR-002 — workflow hardening @@ -54,8 +55,9 @@ All existing commandF workflows must be reconciled to a documented minimum basel - external Actions use full commit SHAs; - checkout uses `persist-credentials: false` unless a documented write operation requires otherwise; -- top-level/job `permissions` are explicit and least-privilege for the workflow purpose; +- top-level/job `permissions` are explicit and no broader than the machine-checkable documented need for the workflow/job; - proof-critical workflows use fixed runner labels and retain or improve digest-pinned execution containers where already present; +- proof-critical job/service containers use digest identities when a container is part of proof identity; mutable tags alone are insufficient; - `cargo` commands that consume the lockfile use `--locked`; - no product semantic gate is removed or weakened to make hardening pass. @@ -93,7 +95,7 @@ Absence of a vulnerability finding is not a claim that the dependency graph is g Add a pinned `zizmor` audit over repository workflow/composite-action definitions. -The commandF-owned workflow-trust audit remains authoritative for commandF's explicit pinning/credential rules. `zizmor` is an independent static-analysis signal and does not replace repository-owned policy. +The commandF-owned workflow-trust audit remains authoritative for commandF's explicit pinning/credential/permission/container-identity rules. `zizmor` is an independent static-analysis signal and does not replace repository-owned policy. ### FR-006 — OpenSSF Scorecard evidence @@ -163,7 +165,7 @@ When an advisory database or external security service is used, its identity/upd ### NFR-002 Least authority -Security workflows must not receive write permissions merely to report read-only findings unless the reporting mechanism itself requires a narrowly scoped write permission. +Security workflows must not receive write permissions merely to report read-only findings unless the reporting mechanism itself requires a narrowly scoped write permission. Checked-in AF-01 policy must make intended workflow/job permissions reviewable and machine-checkable so later permission expansion cannot pass merely because the YAML remains syntactically valid. ### NFR-003 Bounded execution @@ -181,18 +183,22 @@ Implementation is split into independently reviewable stacks; a single monolithi 1. A workflow changes `actions/checkout@` to `actions/checkout@v5` -> repository workflow-trust audit fails. 2. A new workflow uses credential-persisting checkout without an allowed exception -> fails. -3. A dependency is added from an unapproved git source -> `cargo-deny` fails. -4. A dependency introduces a RustSec advisory -> vulnerability gate fails unless an explicit reviewed waiver exists. -5. A workflow contains a security issue detected by the configured `zizmor` severity policy -> audit fails or is explicitly dispositioned according to the frozen policy. -6. The same tree is audited twice with the same pinned tool/advisory inputs -> commandF-owned assurance summary bytes are identical. -7. Product test suites and all path-applicable existing proof workflows remain green. -8. Live GitHub query confirms the intended `main` source-control policy before AF-01 claims canonical closure. +3. A workflow/job requests `contents: write` when checked-in AF-01 policy permits only `contents: read` -> fails. +4. A proof-critical job/service changes a digest-pinned container image to `image:vendor/tool:latest` or another mutable tag -> fails. +5. A dependency is added from an unapproved git source -> `cargo-deny` fails. +6. A dependency introduces a RustSec advisory -> vulnerability gate fails unless an explicit reviewed waiver exists. +7. A workflow contains a security issue detected by the configured `zizmor` severity policy -> audit fails or is explicitly dispositioned according to the frozen policy. +8. The same tree is audited twice with the same pinned tool/advisory inputs -> commandF-owned assurance summary bytes are identical. +9. Product test suites and all path-applicable existing proof workflows remain green. +10. Live GitHub query confirms the intended `main` source-control policy before AF-01 claims canonical closure. ## Edge cases - GitHub Actions referenced through local `./` paths are local source, not external mutable tags. -- Docker images referenced by digest are acceptable immutable identities; mutable image tags alone are not proof identity. +- Docker/OCI job or service images referenced by digest are acceptable immutable identities; mutable image tags alone are not proof identity. +- A non-proof workflow may use a container only under the explicit AF-01 container policy; omission from proof identity must be deliberate and machine-checkable rather than accidental. - Reusable workflows require the same immutable-reference discipline as third-party Actions where GitHub supports commit-SHA references. +- Workflow/job permission inheritance and omission must be normalized by the audit so an absent local `permissions` block cannot silently gain broader authority from an unexamined parent/default. - Scorecard or advisory-service unavailability must be distinguished from a clean security result. - A security tool finding that is not applicable may be dispositioned, but the disposition and rationale become retained evidence. - `cargo-deny` duplicate-version policy must not blindly reject legitimate unavoidable transitive duplication without review; exceptions are explicit and narrow. From 498e1f72bea45531eff15a1ac14062892ce6f96c Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:44:30 +0300 Subject: [PATCH 09/14] docs(af01): make trust audit permissions and containers explicit --- .../plan.md | 30 ++++++++++++++----- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/plan.md b/specs/015-af-01-trusted-development-baseline/plan.md index e8cfbe56..ebe292cb 100644 --- a/specs/015-af-01-trusted-development-baseline/plan.md +++ b/specs/015-af-01-trusted-development-baseline/plan.md @@ -60,7 +60,7 @@ No checked-in configuration/workflow currently exists for: - cargo-audit; - zizmor; - OpenSSF Scorecard; -- repository-owned verification that all workflow references stay immutable/credential-minimal. +- repository-owned verification that all workflow references, permission grants, checkout credentials, and proof-container identities remain within explicit policy. ## Implementation architecture @@ -75,9 +75,13 @@ Expected responsibilities: 3. permit local `./` references; 4. require external action refs to end in a full 40-hex commit SHA; 5. inspect checkout steps and require `persist-credentials: false` unless the policy file names a specific bounded exception; -6. flag proof-critical `*-latest` runner labels according to the AF-01 policy; -7. ensure newly added workflow files cannot escape the audit by using a complete tracked-file enumeration rather than a hard-coded subset; -8. emit deterministic machine-readable result plus a concise human-readable failure report. +6. normalize effective workflow/job permissions and compare them against a checked-in machine-readable allowlist/need declaration; fail when a workflow or job requests broader authority than declared, including inherited/default authority that is not explicitly accounted for; +7. inspect proof-critical job and service `container.image` references and require an accepted digest identity rather than a mutable tag/reference; any non-proof exception must be explicit and bounded in policy; +8. flag proof-critical `*-latest` runner labels according to the AF-01 policy; +9. ensure newly added workflow files cannot escape the audit by using a complete tracked-file enumeration rather than a hard-coded subset; +10. emit deterministic machine-readable result plus a concise human-readable failure report. + +The checked-in policy must be sufficient for a reviewer and the audit to answer, for every workflow/job, which permissions and container-identity modes are allowed. Prose-only intent is not enough because future permission/container escalation must be mechanically rejected. Implementation language should minimize new dependencies. A small Python standard-library or shell+Python verifier is acceptable because it is repository CI tooling, not commandF trusted product runtime. The product core remains Rust-owned. @@ -85,7 +89,9 @@ Workflow updates in the same stack must: - replace mutable external action tags with verified full SHAs; - set `persist-credentials: false` on read-only checkout; +- make top-level/job permissions explicit and no broader than the checked-in need declaration; - change proof-critical runner labels from `*-latest` to explicit supported labels such as `ubuntu-24.04` where the job semantics allow it; +- require digest-pinned proof-critical job/service containers when a container is part of the execution proof; - preserve all existing steps/assertions/path filters; - add timeouts if a touched job lacks one and an appropriate bound can be established; - keep `cargo --locked` semantics. @@ -145,7 +151,7 @@ If the first real run shows a different severity calibration is appropriate, upd #### OpenSSF Scorecard -Add Scorecard in the least-authority supported mode for this public repository. Pin the action to a verified full commit SHA. If publishing results requires `id-token: write` or `security-events: write`, scope those permissions only to the Scorecard job. +Add Scorecard in the least-authority supported mode for this public repository. Pin the action to a verified full commit SHA. If publishing results requires `id-token: write` or `security-events: write`, scope those permissions only to the Scorecard job and add the exact need to the AF-01 machine-checkable permission policy. Do not gate on a single aggregate score. Retain per-check evidence and specifically inspect at least: @@ -168,7 +174,7 @@ Add `.github/workflows/af01-assurance-proof.yml` with complete path coverage for - `deny.toml` and any AF-01 policy/config files; - AGENTS/constitution when they affect authority. -Proof should run in a pinned environment consistent with the best existing commandF proof workflows. +Proof should run in a pinned environment consistent with the best existing commandF proof workflows. Any proof-critical job/service container must be digest-pinned and its digest retained in proof evidence; a mutable image tag is never sufficient proof identity. Expected retained artifact contents: @@ -219,6 +225,8 @@ AF-01 security tooling runs against repository source/dependency metadata only. - no CF-06 production identity mutation; - no code execution from untrusted PR-supplied arbitrary scripts beyond the repository's existing CI model; - third-party actions/tools are pinned and least-authority; +- workflow/job permissions are checked against explicit machine-readable need; +- proof-critical container identities are digest-bound; - network access used for advisory databases/Scorecard is explicit and bounded. Fork PR security must be considered before any workflow is granted write permissions or secrets. `pull_request_target` is not introduced by AF-01 unless a separate threat-model amendment proves it necessary. @@ -228,6 +236,7 @@ Fork PR security must be considered before any workflow is granted write permiss ### Fully deterministic inputs - repository workflow trust audit; +- checked-in permission/container policy; - exact `Cargo.lock` graph inspection when dependency/advisory external state is excluded; - source/config hashes; - proof summary construction over retained normalized inputs. @@ -248,6 +257,8 @@ These must record version/commit/update identity where available. Their results - local `uses: ./` accepted; - full 40-hex refs accepted; - credentialless checkout accepted; +- exact declared read-only permission set accepted; +- digest-pinned proof-critical job/service container accepted; - fixed proof runner accepted. ### Workflow-trust audit negative @@ -257,6 +268,10 @@ These must record version/commit/update identity where available. Their results - branch ref rejected; - tag ref rejected; - checkout without explicit `persist-credentials: false` rejected; +- workflow/job permission broader than the checked-in need declaration rejected; +- omitted/inherited permission state that cannot be reconciled to declared need fails closed rather than being assumed safe; +- proof-critical mutable `container.image` tag rejected; +- proof-critical mutable service-container image tag rejected; - new unscanned workflow path causes coverage test failure; - proof-critical `ubuntu-latest` rejected according to policy; - malformed workflow input fails closed rather than being skipped. @@ -299,7 +314,8 @@ and every path-applicable existing proof/oracle workflow must remain green on ea Developer-visible changes: -- CI will reject mutable Action references and new unreviewed workflow authority; +- CI will reject mutable Action/container references and new unreviewed workflow authority; +- permission expansion requires a reviewed checked-in need/policy update and corresponding audit evidence; - dependency additions may require license/source/advisory policy updates; - canonical main will require PR/check/review policy once the ruleset is applied; - emergency/break-glass changes become explicit governance events rather than ordinary direct pushes. From 9db486b7f78f9d688d15745ccabdc10adcfafd6c Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:44:57 +0300 Subject: [PATCH 10/14] docs(af01): cover permission and container counterexamples --- .../tasks.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/tasks.md b/specs/015-af-01-trusted-development-baseline/tasks.md index d8ec72fe..de582052 100644 --- a/specs/015-af-01-trusted-development-baseline/tasks.md +++ b/specs/015-af-01-trusted-development-baseline/tasks.md @@ -22,13 +22,13 @@ Status: PLANNING_CANDIDATE Depends on T005. -- [ ] **T010** Inventory every tracked `.github/workflows/*.yml|*.yaml`, repository composite Action, external `uses:` reference, runner label, job permission, checkout credential setting, and cargo lockfile-consuming command on canonical planning main. -- [ ] **T011** Define a minimal checked-in AF-01 workflow-trust policy format, including any narrowly scoped exception schema with reason/revisit condition. -- [ ] **T012** Implement repository-owned deterministic workflow-trust audit with complete tracked-workflow discovery, local-action allowance, full-40-hex external action requirement, checkout credential check, and proof-runner policy. -- [ ] **T013** Add positive and counterexample tests for T012, including tag/branch/short-SHA rejection, missing `persist-credentials: false`, new-workflow coverage, malformed input fail-closed behavior, and deterministic repeat output. -- [ ] **T014** Harden `.github/workflows/ci.yml` to full-SHA external Actions, credentialless checkout, explicit least permissions, fixed supported runner label, bounded timeout, and preserved existing semantic/test steps. -- [ ] **T015** Reconcile every other existing workflow to the AF-01 baseline without changing its product/oracle/proof semantics or path-filter authority. -- [ ] **T016** Add a regression that scans all tracked workflow/action files and fails if a future workflow escapes AF-01 trust auditing. +- [ ] **T010** Inventory every tracked `.github/workflows/*.yml|*.yaml`, repository composite Action, external `uses:` reference, runner label, workflow/job permission, checkout credential setting, job/service container image identity, and cargo lockfile-consuming command on canonical planning main. +- [ ] **T011** Define a minimal checked-in AF-01 workflow-trust policy format that makes allowed workflow/job permissions and proof-container identity modes machine-checkable, including any narrowly scoped exception schema with reason/revisit condition. +- [ ] **T012** Implement repository-owned deterministic workflow-trust audit with complete tracked-workflow discovery, local-action allowance, full-40-hex external action requirement, checkout credential check, effective workflow/job permission normalization plus allowlist enforcement, proof-critical job/service container digest enforcement, and proof-runner policy. +- [ ] **T013** Add positive and counterexample tests for T012, including tag/branch/short-SHA rejection, missing `persist-credentials: false`, overbroad permission rejection, unresolved inherited/default permission rejection, proof-critical mutable job/service container rejection, new-workflow coverage, malformed input fail-closed behavior, and deterministic repeat output. +- [ ] **T014** Harden `.github/workflows/ci.yml` to full-SHA external Actions, credentialless checkout, explicit machine-checkable least permissions, fixed supported runner label, bounded timeout, and preserved existing semantic/test steps. +- [ ] **T015** Reconcile every other existing workflow to the AF-01 baseline, including permission declarations and proof-critical container digest identity, without changing its product/oracle/proof semantics or path-filter authority. +- [ ] **T016** Add a regression that scans all tracked workflow/action files and fails if a future workflow, permission grant, external Action ref, checkout credential setting, or proof-critical container identity escapes AF-01 trust auditing. - [ ] **T017** Run mandatory workspace gates and every path-applicable existing proof/oracle workflow on the exact Stack A head. - [ ] **T018** Request CodeRabbit and Qodo on exact Stack A head; disposition every substantive returned finding and require zero unresolved material review threads. - [ ] **T019** Merge Stack A only from its exact qualified head and record canonical merge/main/tree. @@ -52,11 +52,11 @@ Depends on canonical T019. Depends on canonical T029. -- [ ] **T030** Add pinned OpenSSF Scorecard integration in least-authority mode appropriate for this public repository; retain per-check evidence and do not use aggregate score as commandF correctness authority. +- [ ] **T030** Add pinned OpenSSF Scorecard integration in least-authority mode appropriate for this public repository; retain per-check evidence and do not use aggregate score as commandF correctness authority. Any required write/id-token permission must be scoped to the exact Scorecard job and added to the checked-in permission policy. - [ ] **T031** Inspect Scorecard results for at least Branch-Protection, Dangerous-Workflow, Pinned-Dependencies, Token-Permissions, Security-Policy where applicable, and Vulnerabilities; disposition material findings. -- [ ] **T032** Implement `.github/workflows/af01-assurance-proof.yml` with complete AF-01 path coverage and immutable/pinned execution inputs consistent with commandF proof policy. -- [ ] **T033** Define stable `assurance-summary.json` schema and deterministic `AF01_ASSURANCE_SHA256`, binding exact source/tree, policy/config blobs, workflow audit, dependency audit, RustSec audit, zizmor evidence, and tool identities. -- [ ] **T034** Add proof tests for repeated summary equality, source/tree mismatch, missing required evidence, malformed evidence, and dirty/unexpected source where applicable. +- [ ] **T032** Implement `.github/workflows/af01-assurance-proof.yml` with complete AF-01 path coverage and immutable/pinned execution inputs consistent with commandF proof policy, including digest-pinned proof-critical job/service containers where containers are used. +- [ ] **T033** Define stable `assurance-summary.json` schema and deterministic `AF01_ASSURANCE_SHA256`, binding exact source/tree, policy/config blobs, workflow audit, dependency audit, RustSec audit, zizmor evidence, and tool/action/container identities. +- [ ] **T034** Add proof tests for repeated summary equality, source/tree mismatch, missing required evidence, malformed evidence, permission-policy mismatch, mutable proof-container identity, and dirty/unexpected source where applicable. - [ ] **T035** Determine final required status-check names from canonical implementation workflows; do not guess names before they exist. - [ ] **T036** Prepare exact `main` ruleset configuration: PR required, at least one review, required conversations resolved, stale/latest-push review protection, selected status checks required, branch deletion/force-push blocked, and narrowly documented bypass actors only. - [ ] **T037** Apply T036 through an authorized GitHub administrator path. Current connector read capability does not count as mutation authority. From 2d5b3653085dad40ae20a56ba37dca65c083ebbe Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:49:43 +0300 Subject: [PATCH 11/14] docs(af01): close action metadata and required-check gaps --- .../spec.md | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/spec.md b/specs/015-af-01-trusted-development-baseline/spec.md index ec4503e7..29d46fc5 100644 --- a/specs/015-af-01-trusted-development-baseline/spec.md +++ b/specs/015-af-01-trusted-development-baseline/spec.md @@ -37,7 +37,7 @@ After AF-01 closes, commandF has an independently executable and reviewable trus ### FR-001 — repository workflow trust audit -Provide a repository-owned deterministic audit that scans tracked GitHub workflows and composite Actions and fails if an external `uses:` reference is not pinned to a full 40-hex Git commit SHA unless an explicit bounded exception is recorded in the AF-01 policy. +Provide a repository-owned deterministic audit that scans every tracked GitHub workflow and every tracked Action metadata file, including both supported metadata names `action.yml` and `action.yaml`, and fails if an external `uses:` reference is not pinned to a full 40-hex Git commit SHA unless an explicit bounded exception is recorded in the AF-01 policy. The audit must also detect at least: @@ -45,7 +45,7 @@ The audit must also detect at least: - workflow/job permissions broader than their documented need, using checked-in AF-01 policy metadata that makes the allowed permission set machine-checkable rather than relying on prose-only review; - proof-critical job or service container images that use a mutable tag/reference instead of an accepted digest identity, unless an explicit bounded exception is recorded; - use of `ubuntu-latest`, `windows-latest`, or `macos-latest` in proof-critical jobs where AF-01 requires a fixed runner label; -- new workflow files that are outside the audit scope. +- new workflow files or Action metadata files, regardless of whether they are named `action.yml` or `action.yaml`, that are outside the audit scope. The audit result must be deterministic for the same repository tree and the same checked-in AF-01 policy. @@ -109,6 +109,8 @@ Canonical `main` must have repository-level branch/ruleset enforcement that, at - blocks non-PR direct changes except a narrowly defined administrator/break-glass path; - requires the current canonical CI/assurance checks selected by AF-01; +- selects as required only checks that produce a terminal result for **every** protected-branch pull request at the latest candidate SHA; a workflow-level `paths`, `branches`, or commit-message skip that leaves the required check pending is prohibited for a selected required check; +- if expensive validation is path-conditional, uses an always-triggered lightweight required gate/job whose terminal conclusion reflects the applicable conditional jobs, or keeps the path-filtered check non-required; - requires review according to repository governance; - rejects unresolved required review conversations where supported; - prevents force-push and branch deletion for `main`; @@ -182,23 +184,27 @@ Implementation is split into independently reviewable stacks; a single monolithi ## Acceptance scenarios 1. A workflow changes `actions/checkout@` to `actions/checkout@v5` -> repository workflow-trust audit fails. -2. A new workflow uses credential-persisting checkout without an allowed exception -> fails. -3. A workflow/job requests `contents: write` when checked-in AF-01 policy permits only `contents: read` -> fails. -4. A proof-critical job/service changes a digest-pinned container image to `image:vendor/tool:latest` or another mutable tag -> fails. -5. A dependency is added from an unapproved git source -> `cargo-deny` fails. -6. A dependency introduces a RustSec advisory -> vulnerability gate fails unless an explicit reviewed waiver exists. -7. A workflow contains a security issue detected by the configured `zizmor` severity policy -> audit fails or is explicitly dispositioned according to the frozen policy. -8. The same tree is audited twice with the same pinned tool/advisory inputs -> commandF-owned assurance summary bytes are identical. -9. Product test suites and all path-applicable existing proof workflows remain green. -10. Live GitHub query confirms the intended `main` source-control policy before AF-01 claims canonical closure. +2. A new Action metadata file named `action.yaml` contains a mutable external `uses:` ref -> the audit discovers it and fails; `action.yaml` cannot evade a scanner written only for `action.yml`. +3. A new workflow uses credential-persisting checkout without an allowed exception -> fails. +4. A workflow/job requests `contents: write` when checked-in AF-01 policy permits only `contents: read` -> fails. +5. A proof-critical job/service changes a digest-pinned container image to `image:vendor/tool:latest` or another mutable tag -> fails. +6. A dependency is added from an unapproved git source -> `cargo-deny` fails. +7. A dependency introduces a RustSec advisory -> vulnerability gate fails unless an explicit reviewed waiver exists. +8. A workflow contains a security issue detected by the configured `zizmor` severity policy -> audit fails or is explicitly dispositioned according to the frozen policy. +9. The same tree is audited twice with the same pinned tool/advisory inputs -> commandF-owned assurance summary bytes are identical. +10. A documentation-only PR that does not match a heavy proof workflow's `paths` still receives a terminal result for every check selected as required by the `main` ruleset; no required check remains indefinitely pending because its entire workflow was skipped. +11. Product test suites and all path-applicable existing proof workflows remain green. +12. Live GitHub query confirms the intended `main` source-control policy before AF-01 claims canonical closure. ## Edge cases - GitHub Actions referenced through local `./` paths are local source, not external mutable tags. +- Action metadata discovery covers both GitHub-supported names: `action.yml` and `action.yaml`, including metadata below repository subdirectories rather than only a root file. - Docker/OCI job or service images referenced by digest are acceptable immutable identities; mutable image tags alone are not proof identity. - A non-proof workflow may use a container only under the explicit AF-01 container policy; omission from proof identity must be deliberate and machine-checkable rather than accidental. - Reusable workflows require the same immutable-reference discipline as third-party Actions where GitHub supports commit-SHA references. - Workflow/job permission inheritance and omission must be normalized by the audit so an absent local `permissions` block cannot silently gain broader authority from an unexamined parent/default. +- GitHub distinguishes a skipped **job**, which can report a terminal successful/skipped conclusion, from a skipped **workflow** caused by path/branch/commit-message filtering, whose required check can remain pending. Required-check design must account for that distinction. - Scorecard or advisory-service unavailability must be distinguished from a clean security result. - A security tool finding that is not applicable may be dispositioned, but the disposition and rationale become retained evidence. - `cargo-deny` duplicate-version policy must not blindly reject legitimate unavoidable transitive duplication without review; exceptions are explicit and narrow. From f23a084ce9c5f9c926ef6474bb4ba31f347d350e Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:50:30 +0300 Subject: [PATCH 12/14] docs(af01): make metadata and required-check coverage complete --- .../plan.md | 50 ++++++++++++++----- 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/plan.md b/specs/015-af-01-trusted-development-baseline/plan.md index ebe292cb..b025787f 100644 --- a/specs/015-af-01-trusted-development-baseline/plan.md +++ b/specs/015-af-01-trusted-development-baseline/plan.md @@ -60,7 +60,7 @@ No checked-in configuration/workflow currently exists for: - cargo-audit; - zizmor; - OpenSSF Scorecard; -- repository-owned verification that all workflow references, permission grants, checkout credentials, and proof-container identities remain within explicit policy. +- repository-owned verification that all workflow references, permission grants, checkout credentials, Action metadata files, and proof-container identities remain within explicit policy. ## Implementation architecture @@ -70,15 +70,15 @@ Add a small repository-owned audit script, preferably under `.github/scripts/`, Expected responsibilities: -1. enumerate tracked `.github/workflows/*.yml|*.yaml` and repository composite `action.yml` files; -2. parse or conservatively inspect all external `uses:` references; +1. enumerate tracked `.github/workflows/*.yml|*.yaml` and **all** tracked Action metadata files named either `action.yml` or `action.yaml`, including subdirectory Actions; +2. parse or conservatively inspect all external `uses:` references in workflows and Action metadata; 3. permit local `./` references; -4. require external action refs to end in a full 40-hex commit SHA; +4. require external action/reusable-workflow refs to end in a full 40-hex commit SHA; 5. inspect checkout steps and require `persist-credentials: false` unless the policy file names a specific bounded exception; 6. normalize effective workflow/job permissions and compare them against a checked-in machine-readable allowlist/need declaration; fail when a workflow or job requests broader authority than declared, including inherited/default authority that is not explicitly accounted for; 7. inspect proof-critical job and service `container.image` references and require an accepted digest identity rather than a mutable tag/reference; any non-proof exception must be explicit and bounded in policy; 8. flag proof-critical `*-latest` runner labels according to the AF-01 policy; -9. ensure newly added workflow files cannot escape the audit by using a complete tracked-file enumeration rather than a hard-coded subset; +9. ensure newly added workflows or either supported Action metadata filename cannot escape the audit by using complete tracked-file discovery rather than a hard-coded subset; 10. emit deterministic machine-readable result plus a concise human-readable failure report. The checked-in policy must be sufficient for a reviewer and the audit to answer, for every workflow/job, which permissions and container-identity modes are allowed. Prose-only intent is not enough because future permission/container escalation must be mechanically rejected. @@ -92,7 +92,7 @@ Workflow updates in the same stack must: - make top-level/job permissions explicit and no broader than the checked-in need declaration; - change proof-critical runner labels from `*-latest` to explicit supported labels such as `ubuntu-24.04` where the job semantics allow it; - require digest-pinned proof-critical job/service containers when a container is part of the execution proof; -- preserve all existing steps/assertions/path filters; +- preserve all existing steps/assertions/path filters unless a later required-check design deliberately wraps a path-filtered heavy workflow behind an always-triggered gate; - add timeouts if a touched job lacks one and an appropriate bound can be established; - keep `cargo --locked` semantics. @@ -169,7 +169,8 @@ Add `.github/workflows/af01-assurance-proof.yml` with complete path coverage for - AF-01 spec package; - assurance program/index/architecture documents; - workflow files; -- action.yml and repository CI scripts; +- both `action.yml` and `action.yaml` Action metadata anywhere in the repository; +- repository CI scripts; - Cargo manifests/lockfile; - `deny.toml` and any AF-01 policy/config files; - AGENTS/constitution when they affect authority. @@ -196,6 +197,19 @@ AF01_ASSURANCE_SHA256=<64 lowercase hex> Live GitHub ruleset state is kept separately because hosting-platform metadata can change without changing the repository tree. The convergence record binds the exact live observation used for closure. +#### Required-check topology + +A GitHub ruleset required check must have a terminal result on every protected-branch pull request at the latest candidate SHA. A workflow skipped entirely by `paths`, `branches`, or commit-message filtering can leave its associated required check pending and block merging. + +Therefore T035 must classify each candidate check as one of: + +1. **always-triggered required check** — its workflow runs for every protected-branch PR; heavy jobs may be conditionally skipped, but a lightweight `always()`/aggregation gate reaches a terminal conclusion; or +2. **path-filtered/non-universal check** — remains informative/path-applicable and is not selected directly as a repository required check. + +If an existing path-filtered proof must contribute to universal merge policy, introduce an always-triggered lightweight gate that reports a terminal result and correctly reflects whether applicable heavy jobs succeeded. Never select a path-filtered whole workflow as required merely because it is important when it runs. + +Add a negative fixture/governance test proving a docs-only or otherwise nonmatching PR still receives terminal results for every check selected in the planned ruleset. + #### Main ruleset Target source-control policy: @@ -207,11 +221,11 @@ Target source-control policy: - required review count at least 1 unless governance specifies stronger; - required conversations resolved; - stale approvals dismissed or latest-push approval semantics configured so moved heads cannot inherit stale approval; -- required status checks include the AF-01-selected canonical checks; +- required status checks include only AF-01-selected checks proven to report a terminal result for every protected-branch PR; - administrator/bypass actors minimized and documented; - no broad bypass based solely on actor type. -Exact check names must be derived from the final implementation workflows after they are canonical; do not guess names before jobs exist. +Exact check names and trigger topology must be derived from the final implementation workflows after they are canonical; do not guess names before jobs exist. The current connector exposes ruleset/branch-protection reads but not writes. Therefore this configuration is an explicit external operational task. AF-01 cannot mark it complete until a live read proves it. @@ -256,6 +270,7 @@ These must record version/commit/update identity where available. Their results - all existing hardened workflows pass; - local `uses: ./` accepted; - full 40-hex refs accepted; +- both `action.yml` and `action.yaml` discovered and inspected; - credentialless checkout accepted; - exact declared read-only permission set accepted; - digest-pinned proof-critical job/service container accepted; @@ -267,14 +282,22 @@ These must record version/commit/update identity where available. Their results - shortened SHA rejected; - branch ref rejected; - tag ref rejected; +- mutable external `uses:` inside a newly added `action.yaml` rejected; - checkout without explicit `persist-credentials: false` rejected; - workflow/job permission broader than the checked-in need declaration rejected; - omitted/inherited permission state that cannot be reconciled to declared need fails closed rather than being assumed safe; - proof-critical mutable `container.image` tag rejected; - proof-critical mutable service-container image tag rejected; -- new unscanned workflow path causes coverage test failure; +- new unscanned workflow or Action metadata path causes coverage test failure; - proof-critical `ubuntu-latest` rejected according to policy; -- malformed workflow input fails closed rather than being skipped. +- malformed workflow/action metadata input fails closed rather than being skipped. + +### Required-check topology + +- every check proposed by T035 as required is shown to produce a terminal result on a PR whose changed paths do not match the heavy proof workflows; +- a fixture/configuration representing a whole workflow skipped by `paths` is rejected as a direct required-check candidate; +- conditionally skipped heavy jobs are acceptable only when the always-triggered required aggregation job reaches the correct terminal conclusion; +- moved PR heads cannot reuse a terminal result from an older SHA. ### Dependency policy @@ -315,9 +338,11 @@ and every path-applicable existing proof/oracle workflow must remain green on ea Developer-visible changes: - CI will reject mutable Action/container references and new unreviewed workflow authority; +- both supported Action metadata filenames are governed; - permission expansion requires a reviewed checked-in need/policy update and corresponding audit evidence; - dependency additions may require license/source/advisory policy updates; - canonical main will require PR/check/review policy once the ruleset is applied; +- required-check design will use only universal terminal checks, with path-applicable heavy validation represented through safe aggregation rather than a pending skipped workflow; - emergency/break-glass changes become explicit governance events rather than ordinary direct pushes. No commandF CLI or report schema changes are planned. @@ -329,6 +354,7 @@ AF-01 adds CI work. Keep it bounded: - workflow-trust audit should complete in seconds; - cargo-deny/audit may use caching but cache identity must not make the result authoritative; - Scorecard/zizmor should be separate jobs so they can be diagnosed independently; +- always-triggered required gates should remain lightweight and should not force irrelevant heavy path-specific work to execute; - do not put long-running AF-02 fuzz/mutation work into AF-01. ## Stack ordering @@ -350,7 +376,7 @@ AF-01 is `CLOSED_CANONICAL` only when: 1. planning package canonical; 2. every implementation stack merged from an exact green/reviewed head; 3. all AF-01 functional requirements proven or explicitly deferred by an amended canonical plan with rationale; -4. live `main` ruleset/branch-policy query proves required enforcement; +4. live `main` ruleset/branch-policy query proves required enforcement and every selected required check is universally terminal at the latest PR head; 5. final AF-01 proof artifact retained with exact identities; 6. zero unresolved substantive review findings; 7. convergence document merged without semantic substitution; From ae6310e1de00c8ad9d802fdc693c275e57aa4ac3 Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:51:04 +0300 Subject: [PATCH 13/14] docs(af01): prove complete action and required-check coverage --- .../tasks.md | 39 ++++++++++--------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/tasks.md b/specs/015-af-01-trusted-development-baseline/tasks.md index de582052..5f1de8af 100644 --- a/specs/015-af-01-trusted-development-baseline/tasks.md +++ b/specs/015-af-01-trusted-development-baseline/tasks.md @@ -22,13 +22,13 @@ Status: PLANNING_CANDIDATE Depends on T005. -- [ ] **T010** Inventory every tracked `.github/workflows/*.yml|*.yaml`, repository composite Action, external `uses:` reference, runner label, workflow/job permission, checkout credential setting, job/service container image identity, and cargo lockfile-consuming command on canonical planning main. +- [ ] **T010** Inventory every tracked `.github/workflows/*.yml|*.yaml`, every tracked Action metadata file named `action.yml` or `action.yaml` at any repository depth, every external `uses:` reference, runner label, workflow/job permission, checkout credential setting, job/service container image identity, and cargo lockfile-consuming command on canonical planning main. - [ ] **T011** Define a minimal checked-in AF-01 workflow-trust policy format that makes allowed workflow/job permissions and proof-container identity modes machine-checkable, including any narrowly scoped exception schema with reason/revisit condition. -- [ ] **T012** Implement repository-owned deterministic workflow-trust audit with complete tracked-workflow discovery, local-action allowance, full-40-hex external action requirement, checkout credential check, effective workflow/job permission normalization plus allowlist enforcement, proof-critical job/service container digest enforcement, and proof-runner policy. -- [ ] **T013** Add positive and counterexample tests for T012, including tag/branch/short-SHA rejection, missing `persist-credentials: false`, overbroad permission rejection, unresolved inherited/default permission rejection, proof-critical mutable job/service container rejection, new-workflow coverage, malformed input fail-closed behavior, and deterministic repeat output. +- [ ] **T012** Implement repository-owned deterministic workflow-trust audit with complete workflow plus `action.yml`/`action.yaml` discovery, local-action allowance, full-40-hex external action/reusable-workflow requirement, checkout credential check, effective workflow/job permission normalization plus allowlist enforcement, proof-critical job/service container digest enforcement, and proof-runner policy. +- [ ] **T013** Add positive and counterexample tests for T012, including mutable external `uses:` in `action.yaml`, tag/branch/short-SHA rejection, missing `persist-credentials: false`, overbroad permission rejection, unresolved inherited/default permission rejection, proof-critical mutable job/service container rejection, new-workflow/action-metadata coverage, malformed input fail-closed behavior, and deterministic repeat output. - [ ] **T014** Harden `.github/workflows/ci.yml` to full-SHA external Actions, credentialless checkout, explicit machine-checkable least permissions, fixed supported runner label, bounded timeout, and preserved existing semantic/test steps. -- [ ] **T015** Reconcile every other existing workflow to the AF-01 baseline, including permission declarations and proof-critical container digest identity, without changing its product/oracle/proof semantics or path-filter authority. -- [ ] **T016** Add a regression that scans all tracked workflow/action files and fails if a future workflow, permission grant, external Action ref, checkout credential setting, or proof-critical container identity escapes AF-01 trust auditing. +- [ ] **T015** Reconcile every other existing workflow and repository Action metadata file to the AF-01 baseline, including permission declarations and proof-critical container digest identity, without changing its product/oracle/proof semantics or path-filter authority except where later universal required-check aggregation is explicitly introduced. +- [ ] **T016** Add a regression that discovers both `action.yml` and `action.yaml` anywhere in the tracked tree and fails if a future workflow, Action metadata file, permission grant, external Action ref, checkout credential setting, or proof-critical container identity escapes AF-01 trust auditing. - [ ] **T017** Run mandatory workspace gates and every path-applicable existing proof/oracle workflow on the exact Stack A head. - [ ] **T018** Request CodeRabbit and Qodo on exact Stack A head; disposition every substantive returned finding and require zero unresolved material review threads. - [ ] **T019** Merge Stack A only from its exact qualified head and record canonical merge/main/tree. @@ -44,7 +44,7 @@ Depends on canonical T019. - [ ] **T024** Define waiver documentation requirements for any advisory/security exception: identity, rationale, scope, compensating evidence, and revisit/removal condition. - [ ] **T025** Add pinned `zizmor` audit over all repository workflows/actions; freeze initial severity policy from observed baseline rather than guessing around findings. - [ ] **T026** Fix valid high/medium workflow findings or amend the plan/tasks with explicit reviewed disposition; do not lower the gate silently. -- [ ] **T027** Add regressions proving dependency/workflow security configurations are included in relevant workflow path filters so policy mutations cannot bypass gates. +- [ ] **T027** Add regressions proving dependency/workflow security configurations and both Action metadata filename forms are included in relevant workflow path/coverage logic so policy mutations cannot bypass gates. - [ ] **T028** Run mandatory workspace gates plus all path-applicable existing proof/oracle workflows on exact Stack B head. - [ ] **T029** Obtain and disposition CodeRabbit/Qodo review on exact Stack B head, merge only from exact qualified head, and record canonical merge/main/tree. @@ -54,28 +54,29 @@ Depends on canonical T029. - [ ] **T030** Add pinned OpenSSF Scorecard integration in least-authority mode appropriate for this public repository; retain per-check evidence and do not use aggregate score as commandF correctness authority. Any required write/id-token permission must be scoped to the exact Scorecard job and added to the checked-in permission policy. - [ ] **T031** Inspect Scorecard results for at least Branch-Protection, Dangerous-Workflow, Pinned-Dependencies, Token-Permissions, Security-Policy where applicable, and Vulnerabilities; disposition material findings. -- [ ] **T032** Implement `.github/workflows/af01-assurance-proof.yml` with complete AF-01 path coverage and immutable/pinned execution inputs consistent with commandF proof policy, including digest-pinned proof-critical job/service containers where containers are used. +- [ ] **T032** Implement `.github/workflows/af01-assurance-proof.yml` with complete AF-01 policy coverage, including workflows and both `action.yml`/`action.yaml`, and immutable/pinned execution inputs consistent with commandF proof policy, including digest-pinned proof-critical job/service containers where containers are used. - [ ] **T033** Define stable `assurance-summary.json` schema and deterministic `AF01_ASSURANCE_SHA256`, binding exact source/tree, policy/config blobs, workflow audit, dependency audit, RustSec audit, zizmor evidence, and tool/action/container identities. -- [ ] **T034** Add proof tests for repeated summary equality, source/tree mismatch, missing required evidence, malformed evidence, permission-policy mismatch, mutable proof-container identity, and dirty/unexpected source where applicable. -- [ ] **T035** Determine final required status-check names from canonical implementation workflows; do not guess names before they exist. -- [ ] **T036** Prepare exact `main` ruleset configuration: PR required, at least one review, required conversations resolved, stale/latest-push review protection, selected status checks required, branch deletion/force-push blocked, and narrowly documented bypass actors only. -- [ ] **T037** Apply T036 through an authorized GitHub administrator path. Current connector read capability does not count as mutation authority. -- [ ] **T038** Query live GitHub after T037 and retain evidence proving the active ruleset/branch policy actually applies to `refs/heads/main` with intended enforcement. -- [ ] **T039** Negative governance proof: demonstrate or otherwise verify from authoritative GitHub configuration that direct/force/deletion/stale-head bypasses are blocked according to T036 without destructively rewriting repository history. -- [ ] **T040** Run exact-head AF-01 proof, mandatory workspace gates, and every path-applicable existing product proof/oracle workflow; retain artifact IDs/digests and tool/source identities. -- [ ] **T041** Obtain exact-head CodeRabbit/Qodo review; require zero unresolved substantive findings. -- [ ] **T042** Merge Stack C only from exact qualified head and verify post-merge `main`, tree, proof applicability, and live ruleset state. +- [ ] **T034** Add proof tests for repeated summary equality, source/tree mismatch, missing required evidence, malformed evidence, permission-policy mismatch, mutable proof-container identity, missing `action.yaml` coverage, and dirty/unexpected source where applicable. +- [ ] **T035** Determine final required status-check names **and trigger topology** from canonical implementation workflows. Prove every selected required check produces a terminal result on every protected-branch PR at the latest head; path-filtered whole workflows that can remain pending are not eligible as direct required checks. +- [ ] **T036** Add a required-check topology regression/counterexample: a docs-only or otherwise path-nonmatching PR must still receive a terminal result for every check selected by T035. Where heavy validation is conditional, add/identify an always-triggered lightweight aggregation gate that reports the applicable heavy-job result without forcing irrelevant heavy work. +- [ ] **T037** Prepare exact `main` ruleset configuration: PR required, at least one review, required conversations resolved, stale/latest-push review protection, only universally terminal selected status checks required, branch deletion/force-push blocked, and narrowly documented bypass actors only. +- [ ] **T038** Apply T037 through an authorized GitHub administrator path. Current connector read capability does not count as mutation authority. +- [ ] **T039** Query live GitHub after T038 and retain evidence proving the active ruleset/branch policy actually applies to `refs/heads/main` with intended enforcement and exact required-check names. +- [ ] **T040** Negative governance proof: demonstrate or otherwise verify from authoritative GitHub configuration/check topology that direct/force/deletion/stale-head bypasses are blocked and no selected required check can remain pending solely because an entire workflow was path/branch/commit-message skipped, without destructively rewriting repository history. +- [ ] **T041** Run exact-head AF-01 proof, mandatory workspace gates, and every path-applicable existing product proof/oracle workflow; retain artifact IDs/digests and tool/source identities. +- [ ] **T042** Obtain exact-head CodeRabbit/Qodo review; require zero unresolved substantive findings. +- [ ] **T043** Merge Stack C only from exact qualified head and verify post-merge `main`, tree, proof applicability, universal required-check topology, and live ruleset state. ## Phase 4 — convergence -Depends on T042. +Depends on T043. - [ ] **T050** Re-read `spec.md`, `plan.md`, `tasks.md`, assurance-program document, constitution, AGENTS, live GitHub policy, and implementation tree; reconcile any drift. -- [ ] **T051** Create `convergence.md` recording planning/Stack A/B/C identities, workflow run/job/artifact/digest evidence, dependency/security tool identities, reviewer dispositions, live ruleset evidence, limits, and deferrals. +- [ ] **T051** Create `convergence.md` recording planning/Stack A/B/C identities, workflow run/job/artifact/digest evidence, dependency/security tool identities, reviewer dispositions, live ruleset evidence, required-check topology, limits, and deferrals. - [ ] **T052** Confirm product-semantic diff from pre-AF-01 canonical base contains no unauthorized CF semantic change; any incidental product source mutation requires separate task/justification and full semantic qualification. - [ ] **T053** Record remaining assurance work under AF-02/AF-03/AF-04 rather than falsely claiming fuzz/mutation/portability/release/performance completion. - [ ] **T054** Exact convergence head receives path-applicable CI/review truth with zero unresolved substantive findings. -- [ ] **T055** Merge convergence PR and verify canonical post-merge main/tree plus live source-control policy. +- [ ] **T055** Merge convergence PR and verify canonical post-merge main/tree plus live source-control policy and universally terminal required checks. - [ ] **T056** Mark `AF-01=CLOSED_CANONICAL` only after T055 evidence is complete. ## AF-02 handoff retained, not authorized by AF-01 implementation From e2d6a26188e9c375aac8006d672e131c9859bbef Mon Sep 17 00:00:00 2001 From: "Abdulaziz M. Shehri" Date: Wed, 26 Aug 2026 17:51:35 +0300 Subject: [PATCH 14/14] docs(af01): reconcile metadata and required-check review findings --- .../consistency.md | 39 +++++++++++++++---- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/specs/015-af-01-trusted-development-baseline/consistency.md b/specs/015-af-01-trusted-development-baseline/consistency.md index 9ef99245..a0684cd1 100644 --- a/specs/015-af-01-trusted-development-baseline/consistency.md +++ b/specs/015-af-01-trusted-development-baseline/consistency.md @@ -91,7 +91,7 @@ AF-01 uses per-check posture evidence. Aggregate score is not a commandF correct No. -Connector capability is an execution limitation, not a waiver of the requirement. T037 is an external authorized administrator action and T038 requires a live read proving the resulting policy before AF-01 can close. +Connector capability is an execution limitation, not a waiver of the requirement. T038 is an external authorized administrator action and T039 requires a live read proving the resulting policy before AF-01 can close. ### 12. Does AF-01 authorize CF-14 implementation? @@ -123,6 +123,28 @@ No. The research correction (R5 published current; R6 `6.0.0-ballot5` draft as of 2026-07-17) informs future version-readiness assurance. AF-01 does not expand FHIR semantic support. +### 17. Is scanning only `action.yml` complete GitHub Action metadata coverage? + +No. + +GitHub supports both `action.yml` and `action.yaml`. AF-01 therefore requires recursive tracked-tree discovery of both names in T010/T012/T016 and AF-01 proof coverage. A future composite/JavaScript/Docker Action must not evade trust auditing merely by using the other supported filename. + +### 18. Can a path-filtered workflow be selected directly as a required `main` check? + +Not safely when the whole workflow may be skipped. + +GitHub documents that a workflow skipped by path/branch filtering or commit-message skip can leave the associated required check pending and block merging. A skipped job inside an always-triggered workflow can reach a terminal conclusion, which is a different topology. + +AF-01 therefore requires T035/T036 to prove that every check selected by the ruleset is universally terminal for every protected-branch PR at its latest candidate SHA. Heavy path-specific validation may remain conditional, but an always-triggered lightweight aggregation gate must represent it if it contributes to universal merge policy. Otherwise the path-filtered check remains non-required. + +### 19. Did the first Qodo planning review findings remain unaddressed? + +No. + +The first Qodo review found missing task enforcement for machine-checkable workflow/job permissions and missing audit coverage for proof-critical container identities. Both were accepted and amended into `spec.md`, `plan.md`, and `tasks.md` with positive/negative tests. + +The re-review then found the `action.yaml` metadata-name gap and required-check/path-filter topology gap. Those were also accepted and added to the planning contract. Any CI/review state from heads before these amendments is superseded. + ## Requirement-to-task trace | Requirement | Tasks | @@ -133,12 +155,12 @@ The research correction (R5 published current; R6 `6.0.0-ballot5` draft as of 20 | FR-004 cargo-audit | T023-T024, T028-T029 | | FR-005 zizmor | T025-T029 | | FR-006 Scorecard | T030-T031 | -| FR-007 main source-control enforcement | T035-T039, T042 | -| FR-008 exact-head assurance proof | T032-T034, T040-T042 | -| FR-009 product authority unchanged | T014-T019, T028-T029, T040, T052 | -| FR-010 reviewer truth | T005, T018, T029, T041, T054 | -| NFR-001 determinism | T012-T013, T033-T034, T040 | -| NFR-002 least authority | T014-T015, T030-T032 | +| FR-007 main source-control enforcement + universally terminal required checks | T035-T040, T043 | +| FR-008 exact-head assurance proof | T032-T034, T041-T043 | +| FR-009 product authority unchanged | T014-T019, T028-T029, T041, T052 | +| FR-010 reviewer truth | T005, T018, T029, T042, T054 | +| NFR-001 determinism | T012-T013, T033-T034, T041 | +| NFR-002 least authority | T011-T016, T030-T032 | | NFR-003 bounded execution | T014-T015, T022-T025, T030-T032 | | NFR-004 no PHI | all implementation tasks | | NFR-005 stackability | phase ordering T010-T056 | @@ -151,10 +173,11 @@ The research correction (R5 published current; R6 `6.0.0-ballot5` draft as of 20 4. **Initial zizmor severity threshold may need calibration from real findings.** Any change is an explicit plan/task amendment, not silent weakening. 5. **Scorecard external availability/authentication can fail independently of repository correctness.** Operational failure is reported separately from clean posture. 6. **Fixed GitHub runner labels still drift internally.** Strong proof continues to prefer digest-pinned environments. +7. **Required-check topology can deadlock merges if whole path-filtered workflows are selected directly.** T035/T036 require a universal terminal-result proof before ruleset selection. ## Final planning consistency result -No unresolved architecture contradiction is known in the authored package. +No unresolved architecture contradiction is known in the authored package after the accepted planning-review corrections. ```text AF-01 PLANNING CONSISTENCY: CANDIDATE / REQUIRES EXACT-HEAD CI + INDEPENDENT REVIEW