IF Commons GitHub

Intellectual Frontiers Capabilities Configuration Management

0020Active

0020-ifccm · owner if · domain commons · part of 0003-mizan

Capabilities and their issues

FR-001noneno test run

The unit of change MUST be a capability (ifccm:Capability): one ability of a harness that can be named, specified, built, proved and released; a tracker, a commit message, a specification or a generated view MUST NOT call a unit of change a feature, an epic or a product (what Spec Kit calls a feature is a capability here).

Enforced (none): Not built in M2 of issue #10: no rule reads the words a tracker or a commit message uses for a unit of change; the class ifccm:Capability exists and is audited (ifccm-ontology.test.ts)

Proved by: mizan/suite/mizan-changes-pure.test.ts

FR-002noneno test run

A harness MUST plan each body of work (a capability, a book, a change) as one change request, and MUST NOT open a second change request, a sub-issue or one change request for each task for it unless a person asks; its tasks and subtasks MUST be checkbox items (- [ ]) in the body of that change request, and its notes and results MUST be comments on it.

Enforced (none): Not read by any rule: whether a body of work has one change request, with its tasks as checkbox items, is judged by a person, because the host cannot say which change requests belong to one body of work

Proved by: mizan/suite/mizan-changes-pure.test.ts

FR-003checkpassing

A capability's change request MUST have the sections Why, Today, Scope and Done when, in that order, saying why it is wanted, what is true today, what it changes and what it leaves alone, and how it is decided to be done; Done when MUST name each requirement the capability adds or changes (NNNN-slug FR-nnn) and the check, test or review that decides it.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the four sections in order, the Done when requirements and the checkbox items are read from a body; a missing or misordered section is a problem, and changes/issue-shape finds it on a Closes of a capability

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts a capability's body has its four sections in order, its checkbox items and the requirement; passed: suite/mizan-changes-pure.test.ts Closes is judged against the items and sections of the issue, and Refs against whether it

Cited by: changes/issue-body, changes/rules, Mizan

FR-004checkpassing

A minor task, a step too small to have a proof of its own, MUST be a checkbox item (- [ ]) in the body of its capability's change request and MUST NOT be an issue of its own; the capability MAY be closed only when every item is ticked and each of its Done when is met.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: checkbox items are read with whether each is ticked, outside code blocks; mizan-changes-git.test.ts: --strict finds a Closes on an issue with an item not ticked (changes/early-close)

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts a capability's body has its four sections in order, its checkbox items and the requirement

Cited by: changes/issue-body, Mizan

Every commit names its issue

FR-005checkpassing

Every commit's message MUST name at least one change request on a line of its own, as Refs #N while the capability is in progress or as Closes #N on the commit that finishes it (ifccm:IssueReferenceKind: ifccm:Refs, ifccm:Closes); a change request of another repository is named owner/repo#N.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: Refs and Closes on a line of their own, in this or another repository, two issues on two lines, prose and quoted lines not read; mizan-changes-git.test.ts: the commits of a real range

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the commits of a real range are read with their parents, and the rules find the one with n; passed: suite/mizan-changes-git.test.ts with --strict the command asks the host for each change request a commit names, and withou; passed: suite/mizan-changes-pure.test.ts a commit names a change request on a line of its own, as Refs or Closes, in this or anothe

Cited by: changes/commit-message, changes/git-log, changes/rules, Mizan, ifccm/ifccm

FR-006checkpassing

Closes #N MUST be on the commit that finishes N, where every checkbox item of N is ticked and each of its Done when checks passes, and MUST NOT be on any other commit.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: changes/early-close on a Closes whose items are not all ticked, none where all are; mizan-changes-git.test.ts: the command with --strict

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts Closes is judged against the items and sections of the issue, and Refs against whether it

Cited by: changes/issue-body, changes/rules, Mizan

FR-007checkpassing

WHEN a commit names no change request, the changes check MUST report it as changes/no-issue with its revision; a merge commit (two or more parents) MUST NOT be reported for want of a reference of its own, because a merge is judged by its parents: each parent in the range is judged by this rule on its own, so that a parent that names none is reported once, as itself and not again as the merge, and a parent outside the range was judged where it was made.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: changes/no-issue with the revision, a merge never reported itself, its parent that names none reported once, a revert reported; mizan-changes-git.test.ts: a real range with a merge and a revert, and default merge commits with no body judged by their parents

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the commits of a real range are read with their parents, and the rules find the one with n; passed: suite/mizan-changes-git.test.ts a default merge commit with no body is judged by its parents: exempt where its parents nam; passed: suite/mizan-changes-pure.test.ts a commit that names no change request is reported with its revision, a merge is judged by

Cited by: changes/git-log, Mizan

FR-008checkpassing

IF a commit names a change request by a keyword the Git host reads as closing it other than Closes (such as Fixes or Resolves), THEN the check MUST report changes/closing-keyword, so that only the commit that finishes a capability closes it.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the closing words other than Closes are read wherever they stand and changes/closing-keyword reports them; mizan-changes-git.test.ts: a real commit that says Fixes

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the commits of a real range are read with their parents, and the rules find the one with n; passed: suite/mizan-changes-pure.test.ts the words a host reads as closing other than Closes are found wherever they stand

Cited by: changes/commit-message, Mizan

FR-009checkpassing

WHEN the check runs with --strict, it MUST ask the Git host (FR-028) for each change request a commit names and report changes/unknown-issue where it does not exist and changes/closed-issue where a Refs names one that is already closed; without --strict it MUST use no network, so that the network never fails the offline check (0018-standards-first FR-017).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-git.test.ts: --strict asks the host for each issue a commit names (this repository and another's) and finds unknown, closed and not-ticked ones; without --strict the host is never asked; mizan-changes-pure.test.ts: the rules over the answers

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts with --strict the command asks the host for each change request a commit names, and withou; passed: suite/mizan-changes-git.test.ts a strict run that cannot ask the host is not_run with its reason and is never reported as ; passed: suite/mizan-changes-pure.test.ts Closes is judged against the items and sections of the issue, and Refs against whether it

Cited by: changes/rules, changes/strict, Mizan

Phased enforcement

FR-010checkpassing

A harness MUST state in typed data its declaration (ifccm:HarnessDeclaration): the regulated domains it claims (ifccm:RegulatedDomain: ifccm:FederalSecurity, ifccm:DeviceQuality, ifccm:ElectronicRecords, ifccm:DeviceSoftware, ifccm:TrustServices) and, as ifccm:productionDeclaredOn, the day (YYYY-MM-DD) it declares production; a harness that claims a regulated domain MUST state that day, and a harness that states neither is read as not regulated and not in production.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the declaration is typed data read and never run, its regulated domains are the code list's, a domain with no production day is refused (changes/declaration), a harness that states nothing is not regulated

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts a declaration is typed data: a regulated domain needs a production day, and the domains ar

Cited by: changes/declaration, changes/rules, Mizan, ifccm/ifccm, host/declaration, pure/ladder, Quality evidence

FR-011checkpassing

WHILE a harness has not declared production (it states no day, or the day is after today), the findings of the changes check MUST be warnings (ifccm:Warn) held by a baseline that only shrinks (0018-standards-first FR-012); from the declared day on, every finding MUST fail whatever the baseline holds (ifccm:Gate).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: warn before the declared day and gate from it, today included, and holdHarness never holds a gate finding by a baseline; mizan-changes-git.test.ts: the command holds warnings by changes.baseline.txt and fails a gate whatever it holds

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command exits 0 clean, 1 on findings, 2 on usage and 3 on environment, holds warnings ; passed: suite/mizan-changes-git.test.ts a declaration whose day moved later is found by the command from Git history, as a gate on; passed: suite/mizan-changes-pure.test.ts a commit that names no change request is reported with its revision, a merge is judged by ; passed: suite/mizan-changes-pure.test.ts holdHarness runs the changes rules as a plugin: a regulated declaration with no day is ref; passed: suite/mizan-changes-pure.test.ts findings warn before the declared day and gate from it, the day itself included

Cited by: changes/declaration, ifccm/ifccm

FR-012checkpassing

IF a declaration's day is moved later after it has passed, or a regulated domain is dropped from it, THEN the check MUST report changes/gate-relaxed, which only a Decision (FR-018) clears.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-git.test.ts: the history of a real declaration file gives changes/gate-relaxed for a day moved later after it passed, a day removed and a domain dropped, cleared only by a Decision that covers the revision; mizan-changes-pure.test.ts: the judgement over versions

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command exits 0 clean, 1 on findings, 2 on usage and 3 on environment, holds warnings ; passed: suite/mizan-changes-git.test.ts a declaration whose day moved later is found by the command from Git history, as a gate on; passed: suite/mizan-changes-git.test.ts a declaration moved later after its day is found in the real history of its file, and only; passed: suite/mizan-changes-pure.test.ts a production day moved later after it passed, a day removed and a domain dropped are relax

Cited by: changes/declaration, changes/git-log, changes/rules, Mizan, pure/ledger

FR-013checkpassing

WHERE a harness claims a regulated domain, its declaration MUST be the one source from which 0016-ladder FR-011 decides which rungs it requires of that harness from the declared day.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: rungsRequired gives rungs 9 and 10 from the declared day for a harness that claims a regulated domain, none otherwise; 0016-ladder FR-011 reads it

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts the declaration decides the rungs 9 and 10 a regulated harness requires from the declared

Cited by: changes/declaration, Mizan

The trace chain

FR-014checkpassing

The chain from a change to its proof MUST run through these stages, in this order (ifccm:TraceStage): the change request (ifccm:StageIssue), the requirement (ifccm:StageRequirement, an mz:Requirement), the ontology term it is defined in (ifccm:StageTerm, an mz:OntologyTerm whose mz:definedBy names the requirement), the code (ifccm:StageCode, a // Spec: line, 0015-trace FR-005), the test (ifccm:StageTest, proves, 0015-trace FR-006) and the quality run (ifccm:StageRun, a run of 0021-ifqs); a stage MUST be linked by the annotation it already has and MUST NOT need a new one.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: the chain is six TraceStage individuals in order, each with the annotation that already links it

Proved by: mizan/suite/mizan-changes-pure.test.ts, ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts the chain of a requirement ends at the first stage with no link; passed: suite/ifccm-ontology.test.ts the chain is six stages in order, from the issue to the quality run, each with the annotat

Cited by: changes/trace, Mizan, spec-terms, ifccm/ifccm, Quality, pure/chain-files, pure/freshness, Quality evidence, Mizan, the IF Spec Profile

FR-015checkpassing

WHEN the check is asked for the chain of a change request, it MUST name, for each requirement its Done when names, the first stage with no link (no term, no code, no test, or no passing run at the revision), so that the report ends where the chain breaks.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the chain of a requirement ends at the first stage with no link (term, code, test, run); mizan-changes-git.test.ts: the command --trace over the Done when of an issue body

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command reports, for each requirement of a Done when, where its chain ends; passed: suite/mizan-changes-pure.test.ts the chain of a requirement ends at the first stage with no link

Cited by: changes/trace, Mizan, pure/freshness, Quality evidence

FR-016checkpassing

A capability MUST state the rungs it touches (ifccm:touchesRung, each an mz:Rung), and commons MUST generate from them the view of the capabilities that touch each rung, between the markers <!-- capabilities:begin --> and <!-- capabilities:end --> of a harness's document, whose --check MUST fail where the document differs; the view is an axis across the ladder and no rung of it.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the view of capabilities by rung is generated between the markers and its check fails where the document differs; mizan-changes-git.test.ts: the command writes it and --check fails where the document differs

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command writes the view of capabilities by rung into a document and --check fails wher; passed: suite/mizan-changes-pure.test.ts the view lists the capabilities that touch each rung, open where the rung's commands have

Cited by: changes/capability-view, Mizan

FR-017checkpassing

WHILE a rung a capability touches has no passing run of that rung's checks (mz:provedBy) at the capability's last revision, the view MUST show the capability as open on that rung (0016-ladder FR-003).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: a capability is open on a rung while a command of the rung has no passing run at its last revision, proved otherwise; mizan-changes-git.test.ts: the command

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command writes the view of capabilities by rung into a document and --check fails wher; passed: suite/mizan-changes-pure.test.ts the view lists the capabilities that touch each rung, open where the rung's commands have

Cited by: changes/capability-view, Mizan

The authority boundary

FR-018checkpassing

Authority MUST be kept in four functions (ifccm:AuthorityFunction): a specification binds (ifccm:Binds), a Decision (mz:Decision) authorizes (ifccm:Authorizes) a departure, a waiver, an exception, a baseline or a release, a check verifies (ifccm:Verifies), and an issue only plans and traces (ifccm:Plans).

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: the four AuthorityFunction individuals and the instrument that carries each

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts authority is four functions, each carried by one instrument: a specification, a Decision,

Cited by: ifccm/ifccm, Quality evidence, Headless governance

FR-019checkpassing

A comment, label, assignment or state of an issue MUST NOT waive, accept or authorize anything; a departure from a specification MUST be a Decision that names the role that approved it, and MAY name the issue as its record (mz:record).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: a departure (Departs:) with no Decision that names it, or naming one the harness does not record, is changes/no-decision; nothing of an issue's comment, label or state is read as authority

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts a departure needs a Decision that names it, and in a regulated harness one approved by a r

Cited by: changes/declaration, changes/rules, Mizan

FR-020checkpassing

WHERE a harness claims a regulated domain, a Decision that authorizes a change MUST be approved by a role other than the author of the change, and a check MUST NOT accept, waive or close its own finding: nothing authorizes itself.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: where a regulated domain is declared, a Decision approved by the role of the commit's author, or with the author's role not recorded, is changes/self-approved

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts a departure needs a Decision that names it, and in a regulated harness one approved by a r

Cited by: changes/declaration, changes/rules, Mizan, pure/ledger, Quality evidence

Change records

FR-021checkpassing

A change request (ifccm:ChangeRequest) MUST have a kind (ifccm:ChangeRequestKind), ifccm:CapabilityRequest (a request to add or change a capability) or ifccm:Problem (a report that something departs from what is specified or required, opened by a person or by the system from a nonconformance of 0021-ifqs), a state (ifccm:ChangeRequestState: ifccm:Open or ifccm:Closed) and the kind of Git host that holds it (ifccm:hostedOn, one of ifccm:GitManagerKind: FR-027).

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: the kinds (capability request, problem) and states (open, closed) are the words the specification names, and a change request has exactly one kind, state and host

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts a change request has exactly one kind, one state and one host, and the kinds and states ar

Cited by: ifccm/ifccm, Quality evidence

FR-022checkpassing

A change (ifccm:Change) MUST be the work done under one or more change requests, with the revisions it made and the change request it implements (ifccm:implementsRequest); a configuration item (ifccm:ConfigurationItem) MUST be anything a change may alter that is under control (a specification, an ontology file, a source file, a test, a generated file, a pin); and a baseline (ifccm:Baseline) MUST be the configuration items at one revision, established by a Decision.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: a change names its change requests and revisions, a baseline its items and the Decision that establishes it

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts a change names the change requests it implements and its revisions, a baseline its items a

FR-023checkpassing

The terms of FR-021 and FR-022 MUST rest on standards (0018-standards-first FR-003): a change request specializes OSLC Change Management's ChangeRequest, whose Problem kind corresponds to OSLC's Defect (a mapping stated here, not a term), a change is a prov:Activity that used its change request, a configuration item a prov:Entity and a baseline a prov:Collection, each with its mz:OntologyTerm record.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: ChangeRequest specializes oslc_cm:ChangeRequest, Change prov:Activity, ConfigurationItem prov:Entity and Baseline prov:Collection, each with its audit record

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts a change request specializes OSLC's ChangeRequest, a change is a prov:Activity, a configur

Controls and the crosswalk

FR-024checkpassing

The capability MUST satisfy these NIST SP 800-53 Rev. 5 controls, cited by their OSCAL identifiers: cm-2 (baseline configuration: the baseline of FR-022), cm-3 (configuration change control: FR-005 to FR-009 and FR-018 to FR-020), cm-4 (impact analysis: the capability's rungs and chain, FR-014 to FR-017), cm-5 (access restrictions for change: the authority boundary, FR-018 to FR-020) and cm-9 (configuration management plan: this specification). Controls: cm-2, cm-3, cm-4, cm-5, cm-9.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: the requirement names cm-2, cm-3, cm-4, cm-5 and cm-9 and the crosswalk row repeats them; the typed code list of the OSCAL controls is imported by the lead (0019-mizan-integrations FR-015)

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts the capability names the five Configuration Management controls of NIST SP 800-53 Rev. 5 b

FR-025checkpassing

The crosswalk of this specification to the standards below MUST be stated as mapping statements, each a standard, a clause cited by its identifier and never copied (0018-standards-first FR-007), one of the relations closeMatch, broadMatch or narrowMatch (SSSOM's words), and the requirements that serve the clause, and MUST NOT define a term for a clause; every requirement it names MUST exist.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: each crosswalk row has a relation SSSOM has and requirements that exist, the standards are there, and no clause is a term

Proved by: ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/ifccm-ontology.test.ts the crosswalk is mapping statements, not terms: each row names a standard, a clause, a rel

FR-026noneno test run

WHERE a harness claims ifccm:DeviceQuality, its change records (FR-021 to FR-023) MUST be kept so that they serve as the control of design and development changes that the Quality Management System Regulation, 21 CFR Part 820, which incorporates ISO 13485:2016 by reference, asks of the manufacturer. Authority: mzid:authority-21-cfr-820.

Enforced (none): Not built in M2 of issue #10: that a DeviceQuality harness keeps its change records so that they can be handed over is a practice no check reads yet; the records of FR-021 to FR-023 are terms (ifccm-ontology.test.ts) and the Authority citation is held by mizan/authority-citation

The crosswalk

StandardClauseRelationRequirements
ISO 13485:20167.3.9, control of design and development changescloseMatchFR-005, FR-019, FR-021, FR-022
ISO 9001:20158.5.6, control of changescloseMatchFR-005, FR-019, FR-021
IEC 62304:2006+A1:2015clause 8, software configuration management processcloseMatchFR-014, FR-021, FR-022
FDA QMSR (21 CFR Part 820)design and development changes, through ISO 13485:2016narrowMatchFR-026
SOC 2 Trust Services CriteriaCC8.1, change managementcloseMatchFR-018, FR-019, FR-020
NIST SP 800-53 Rev. 5cm-2, cm-3, cm-4, cm-5, cm-9closeMatchFR-024

Git hosts

FR-027checkpassing

Where a harness is hosted on a Git host, the host MUST be one of ifccm:Github, ifccm:Gitlab or ifccm:Git (ifccm:GitManagerKind, the one list of Git host kinds, which ifccm:hostedOn ranges over); a typed term of this specification MUST NOT carry a host's own word, and a GitHub issue and a GitLab issue are the same change request.

Enforced (check): .github: cd commons/ontology && bun test suite/ — ifccm-ontology.test.ts: the host kinds are the three of ifccm:GitManagerKind (Github, Gitlab, Git), and ifccm:hostedOn ranges over them

Proved by: ontology/suite/githost-ontology.test.ts, ontology/suite/ifccm-ontology.test.ts

Tests: passed: suite/githost-ontology.test.ts the table of what each kind of Git host offers, in the library githost, is the ontology's; passed: suite/ifccm-ontology.test.ts the host is one of GitHub, GitLab or plain Git, and no typed term carries a host's own wor

Cited by: ifccm/ifccm

FR-028checkpassing

The check MUST reach a Git host through one typed interface that answers, for a reference, whether the change request exists, its state, its kind, and its body (for its sections and checkbox items); no other code of the check MUST name a host's API, URL or term.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the files of the changes check reach a host only through GitHostClient and name no host API or URL; the adapters are M4's (the githost folder)

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts the check reaches a host only through the interface: no file of it names a host's API, URL

Cited by: changes/strict, Mizan

FR-029noneno test run

A pull request (GitHub) and a merge request (GitLab) MUST each be read as the part of a change that carries its commits, never as a change request; the reference #N MUST mean the issue on both hosts.

Enforced (none): Planned, M4 of issue #10 (the adapters): the adapters read a pull request and a merge request as part of a change and #N as the issue

FR-030checkpassing

WHERE a harness's host is ifccm:Git (plain Git), there is no tracker to ask: references MUST be checked by their form alone, and --strict MUST report the check as not_run with the reason that there is no host API, and MUST NOT report it as passed.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-git.test.ts: --strict on plain Git is not_run with the reason that there is no host API, and so are no client given and an unreachable host; never passed

Proved by: mizan/suite/mizan-changes-git.test.ts

Tests: passed: suite/mizan-changes-git.test.ts a strict run that cannot ask the host is not_run with its reason and is never reported as

Cited by: changes, changes/strict, Mizan, ifccm/ifccm

Evidence of the check

FR-031checkpassing

Each run of the changes check MUST leave a result in the record shape of 0021-ifqs, with each rule's result as a case and each --strict case that could not ask the host as not_run with its reason.

Enforced (check): .github: cd commons/quality && bun test suite/ — quality-changes-record.test.ts (commons/quality/suite): each run of libraries/tools/changes.ts leaves a quality record with each rule as a case, each finding a failed case with rule, file and line, and each rule that could not run (strict on plain Git, no client, no --strict, no --range) not_run with its reason

Proved by: quality/suite/quality-changes-record.test.ts

Tests: passed: suite/quality-changes-record.test.ts a run of the changes check leaves each rule as a case and each finding as a failed case wi; passed: suite/quality-changes-record.test.ts with --keep-record the run's record is kept as evidence on the quality branch, in a chain

Cited by: changes, changes/rules

FR-032checkpassing

The findings of the changes check MUST be Mizan findings (changes/no-issue, changes/closing-keyword, changes/unknown-issue, changes/closed-issue, changes/gate-relaxed), held by a baseline as 0003-mizan FR-015 holds the rest, and the check MUST be run by holdHarness for every harness.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: the findings are Mizan findings (MizanRule, held by a baseline) and holdHarness runs the declaration rule as a plugin; mizan-changes-git.test.ts: the command runs as a program with its exit statuses; the commit rules need a range and are the command's

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts the command exits 0 clean, 1 on findings, 2 on usage and 3 on environment, holds warnings ; passed: suite/mizan-changes-git.test.ts the command runs as a program on this runtime: 0 for a clean range, 1 for a finding, and i; passed: suite/mizan-changes-pure.test.ts holdHarness runs the changes rules as a plugin: a regulated declaration with no day is ref

Cited by: changes/plugin, changes/rules, Mizan

FR-033checkno test run

A commit that departs from a specification MUST say so on a line of its own as Departs: NNNN-slug FR-nnn and name the Decision that authorizes it on a line of its own as Decision: <id>; a harness MUST state its Decisions (each with its identifier, the role that approved it, and the requirements it authorizes or gate-relaxed <revision>) and the role of each author by email in the typed file that holds its declaration, read as data and never run; and the changes check MUST report, besides the findings of FR-032, changes/early-close (FR-006), changes/issue-shape (FR-003), changes/no-decision (FR-019), changes/self-approved (FR-020) and changes/declaration (FR-010), the last of them as a gate whatever the day, since a declaration wrong by itself is refused.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: Departs and Decision lines are read from a commit and judged (changes/no-decision, changes/self-approved), and the record file's declaration, decisions and roles are read as data

Cited by: changes/commit-message, changes/rules, Mizan

FR-034noneno test run

WHERE a repository has no Git host account, it MAY keep its change requests as a typed file in Git, read as data and never run, so that --strict has change requests to ask; such a file is the plain-Git counterpart of the host adapter of FR-028 and answers the same four questions.

Enforced (none): Planned, owner decision 2026-11-17 (issue #10): a repository with no Git host account may keep its change requests as a typed file in Git; not built

FR-035checkpassing

WHERE a harness has no Git host account, changes.ts --capability-trace --range A..B MUST give, with no network and no host, for each capability the commits of the range serve (a change request that a Refs #N or Closes #N line names, FR-005) the requirements that concern it and the chain of each (FR-014): the requirements a commit's message names, those whose lines in a spec.md a commit added or edited, those of the change request's Done when where its body is given, and those a Spec: line cites or a proves call or Proves: line proves in a file a commit changed; a commit that names no change request of this repository (one that names only another repository's) MUST be listed apart and be in no capability (amended 2026-11-18).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-harness-requests.test.ts: on a real repository with no host, the capabilities of a range are the change requests the commits name, their requirements come from messages, spec diffs, a Done when and the Spec:/Proves: lines of changed files, and a commit naming only another repository is listed apart

Proved by: mizan/suite/mizan-harness-requests.test.ts

Tests: passed: suite/mizan-harness-requests.test.ts the offline trace follows each capability's requirements to terms, code and tests on each ; passed: suite/mizan-harness-requests.test.ts the trace of data in hand: a commit that names no change request of this repository is lis

Cited by: changes/capability-trace, changes/capability-view, changes/git-log, Mizan

FR-036checkpassing

The offline trace MUST read only files the harness keeps and the repository's Git: the change requests as a JSON file (--issues, a list of objects with number and, where kept, title and body), the citations of the ontology's terms (--terms, a JSON file, or a module loaded by the file: URL of its path so that it loads on Windows, that exports terms as objects with term, cites and file or as the records of an audit of terms; commons for commons' own ontologies), the rungs with their homes (--rungs, export const rungs, each with id, label, provedBy and, for the trace, homes), the cases of a quality record (--runs, 0021-ifqs) and the specifications (--specs); --trace MUST read --terms as well, so that the chain of a Done when follows a harness's own terms (amended 2026-11-18).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-harness-requests.test.ts: the change requests as JSON, the terms as JSON or as a module loaded by the file URL of a path with a space (audit records too), the rungs with homes and the specs are read; a missing file, a module with no terms and a bad format are named; --trace reads --terms

Proved by: mizan/suite/mizan-harness-requests.test.ts

Tests: passed: suite/mizan-harness-requests.test.ts the offline trace follows each capability's requirements to terms, code and tests on each ; passed: suite/mizan-harness-requests.test.ts the terms come from a module loaded by its file URL, as audit records, and the usage error

Cited by: changes/terms-file, Mizan

FR-037checkpassing

The offline trace MUST give, for each requirement of each capability, the stages of its chain, the first stage with no link (FR-015) and the specification, the terms, the code and the tests placed on the rung whose home matches each most specifically (0015-trace FR-009, - where none does), as a table of text by default or as JSON with --format json, the same text for the same input (sorted, with no clock, with LF), and written to a file with --output FILE (amended 2026-11-18).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-harness-requests.test.ts: each requirement's stages, the stage where its chain ends and its spec, terms, code and tests on each rung are given as a table and as JSON, the same bytes twice, with LF, and written to --output

Proved by: mizan/suite/mizan-harness-requests.test.ts

Tests: passed: suite/mizan-harness-requests.test.ts the offline trace follows each capability's requirements to terms, code and tests on each ; passed: suite/mizan-harness-requests.test.ts the trace of data in hand: a commit that names no change request of this repository is lis

FR-038checkpassing

WHERE --document FILE is given with --capability-trace, the command MUST derive the capabilities of the view of FR-016 from the commits (the rungs their changed files are on, and the last commit of each) and write the view between the document's markers, or with --check fail where the document differs; and the offline trace MUST exit with 1 where a capability that a commit says Closes has a requirement whose chain ends before its quality run (a capability that is not closed is in progress), 2 for a usage error and 3 where an input cannot be read (amended 2026-11-18).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-harness-requests.test.ts: the view of capabilities by rung is made from the commits between the markers of a document and --check finds no difference after it; the exit status is 1 for a closed capability whose chain stops before its run, 0 for an open one, 2 and 3 for usage and inputs

Proved by: mizan/suite/mizan-harness-requests.test.ts

Tests: passed: suite/mizan-harness-requests.test.ts the view of capabilities by rung is made from the commits and written between the markers

Cited by: changes/capability-trace, Mizan

The Git host interface

FR-039reviewno test run

The change-control check MUST reach Git hosts only through the one GitHostClient interface of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-001), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-001

FR-040reviewno test run

The change-control check MUST take the common capabilities of every kind of Git host, and those of GitHub and GitLab, from of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-002), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-002

FR-041reviewpassing

The change-control check MUST answer a capability a Git host kind does not list with a typed unsupported result, as of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-003), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-003

Proved by: ontology/suite/githost-ontology.test.ts

Tests: passed: suite/githost-ontology.test.ts the table of what each kind of Git host offers, in the library githost, is the ontology's

FR-042reviewno test run

The change-control check MUST authenticate a Git host adapter without writing a credential anywhere, as of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-004), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-004

FR-043reviewno test run

The change-control check MUST choose the kind of host for a remote (a self-hosted GitLab named, never guessed), as of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-005), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-005

FR-044reviewno test run

The change-control check MUST tell the depth a kind of host allows (maxDepth), as of the library githost (@intellectual-frontiers/githost, githost 0001-githost FR-006), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library githost: githost 0001-githost FR-006

FR-045checkpassing

A commit's message MAY state how much it raises the version of the works it changes on a line of its own, Impact: major, Impact: minor or Impact: patch (0026-works-versioning FR-021); the changes check MUST report a line Impact: whose value is none of the three as changes/impact, with its revision and the value, a warning or a gate by the phase like the other findings, and MUST NOT report a commit that states none.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts: an Impact line is read as major, minor or patch in any case, and one that is none of the three is changes/impact with its value, a warning or a gate by the phase

Proved by: mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-pure.test.ts an Impact line is read as major, minor or patch in any case and a line that is none of the

FR-046checkpassing

WHERE a commit names no change request and cannot be amended (history is not rewritten), a Decision of the harness record MAY exempt that one commit as covers: ["no-issue <revision>"], the revision in full or by a prefix of at least 7 lowercase hexadecimal characters, the same entry syntax as gate-relaxed <revision> (FR-012, FR-033). Such a Decision MUST name a person as approvedBy (not empty and not a role of roles), the day it was made as decidedOn (YYYY-MM-DD) and its reason; it exempts that commit alone, and only where it is sound and the revision names exactly one commit of the range.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-git.test.ts: in a real Git repository a commit with no Refs fails and the same range passes with a Decision that covers its revision (full or by a 7-character prefix), and a different commit is not covered; mizan-changes-pure.test.ts: the entry syntax, the person, day and reason

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts in a real repository a commit with no Refs fails, the same range passes with a Decision th; passed: suite/mizan-changes-pure.test.ts a sound no-issue Decision exempts exactly the commit it names, in full or by a 7-character

Cited by: changes/declaration, changes/rules, Capabilities configuration (IFCCM)

FR-047checkpassing

WHEN a Decision exempts a commit under FR-046, the changes check MUST NOT report changes/no-issue for that commit and MUST say that it is covered, with the Decision, the person, the day and the reason; a commit the Decision does not name MUST still be reported.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-git.test.ts: the command reports the exempted commit as covered with the Decision, the person, the day and the reason, and still reports the commit it does not name

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts in a real repository a commit with no Refs fails, the same range passes with a Decision th; passed: suite/mizan-changes-pure.test.ts a sound no-issue Decision exempts exactly the commit it names, in full or by a 7-character

FR-048checkpassing

IF a Decision that covers no-issue <revision> is not sound (a malformed entry, no person or a role as the person, no day or one that is not a day, no reason), or names a revision that is not in the range, or a prefix that names two commits of it, or a commit that already names a change request or is a merge, THEN the check MUST report it as changes/decision with the Decision's identifier, a warning or a gate by the phase like the other findings, and an unsound Decision MUST exempt nothing.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-changes-pure.test.ts and mizan-changes-git.test.ts: a Decision with no person, a role, no day or reason, a malformed entry, a revision outside the range, an ambiguous prefix or a commit that names an issue is changes/decision, and exempts nothing

Proved by: mizan/suite/mizan-changes-git.test.ts, mizan/suite/mizan-changes-pure.test.ts

Tests: passed: suite/mizan-changes-git.test.ts in a real repository a commit with no Refs fails, the same range passes with a Decision th; passed: suite/mizan-changes-pure.test.ts a no-issue Decision for a revision outside the range, an ambiguous prefix or a commit that; passed: suite/mizan-changes-pure.test.ts a no-issue Decision with no person, a role as the person, no day, no reason or a malformed

Cited by: Capabilities configuration (IFCCM)

Acceptance scenarios

  1. Given a commit whose message ends with Refs #10, When the check runs, Then it reports nothing for the commit, per FR-005 and FR-007.
  2. Given a commit with no reference and a harness that has not declared production, When the check runs, Then it reports changes/no-issue as a warning held by the baseline, per FR-007 and FR-011.
  3. Given the same commit on the day the harness declared production, When the check runs, Then it fails whatever the baseline holds, per FR-011.
  4. Given a commit that says Fixes #10, When the check runs, Then it reports changes/closing-keyword, per FR-008.
  5. Given --strict and a commit that names #999, which the host does not have, When the check runs, Then it reports changes/unknown-issue, per FR-009.
  6. Given a harness on plain Git, When the check runs with --strict, Then the strict cases are not_run with the reason that there is no host API, per FR-030 and FR-031.
  7. Given a declaration whose production day was moved from last month to next month, When the check runs, Then it reports changes/gate-relaxed until a Decision clears it, per FR-012 and FR-019.
  8. Given a requirement named in a Done when that has a term and code but no test, When the chain is asked for, Then it ends at the test stage, per FR-014 and FR-015.
  9. Given an issue labelled approved and no Decision, When a change departs from a specification, Then the departure is not authorized, per FR-019.
  10. Given a repository on plain Git whose commits say Refs #3 and name a requirement, with a terms file, When changes.ts --capability-trace --range A..B --terms FILE runs, Then the chain of the requirement is printed on its rungs and ends at the first stage with no link, with no host asked, per FR-035 to FR-037.
  11. Given the same range and --document ARCH.md, When the command runs and then runs with --check, Then the view is written between the markers and the check finds no difference, per FR-038.

Out of scope

  • Which issue tracker a company uses and how its boards are arranged: the adapter reads change requests and does not manage them.
  • The quality records themselves (test runs, evidence, nonconformance, CAPA): 0021-ifqs.
  • The workspace where changes are made (issue-named branches, worktrees, hooks): a later specification of the workspaces.

Edge cases

  • A commit that names two issues, Refs #10 and Refs #12: it serves both, per FR-005.
  • A commit that names only Refs owner/other#7, in the offline trace: listed with the commits that name no change request, and in no capability, per FR-035.
  • A terms file that does not exist, or a module that exports no terms: exit 3 with the reason, and no table, per FR-036 and FR-038.
  • A --terms module in a folder whose name has a space, on Windows: loaded by its file: URL, per FR-036.
  • A capability that a commit closes and whose requirement has no passing run: the trace exits 1; an open capability with the same chain exits 0, per FR-038.
  • A commit that names Refs intellectual-frontiers/.github#10: read as that repository's change request, and --strict asks that repository's host, per FR-005 and FR-009.
  • A merge commit whose two parents each name an issue, with the default message and no body: exempt, per FR-007.
  • A merge commit one of whose parents names no issue: the parent is reported, the merge is not, per FR-007.
  • A revert commit with no issue: reported, because a revert is a change, per FR-007.
  • A body that says Closes #10 in prose in the middle of a line: it is not a line of its own and is not read, per FR-005.
  • A capability with three tiny steps: three checkbox items and no new issues, per FR-004.
  • A second change request, a sub-issue or one change request for each task opened for a body of work that has one: no rule reads it, and a person's review judges it, per FR-002.
  • A harness that states ifccm:DeviceQuality and no production day: refused, per FR-010.
  • A harness with no declaration: warnings only, per FR-010 and FR-011.
  • A production day of today: the gate applies today, per FR-011.
  • A regulated domain removed from the declaration the day after the gate: changes/gate-relaxed, per FR-012.
  • A comment "approved" on an issue: authorizes nothing, per FR-019.
  • A change authored and approved by the same role in a regulated harness: refused, per FR-020.
  • An agent that runs the check and then waives its finding: refused, per FR-020.
  • A requirement with a term and code but no test: the chain ends at the test, per FR-015.
  • A GitLab merge request that names #12: read as issue 12, not merge request 12, per FR-029.
  • --strict on a host that cannot be reached: the strict cases are not_run with the reason, never passed, per FR-030 and FR-031.
  • A crosswalk row that names a requirement this specification lacks: the test of FR-025 fails, per FR-025.

Assumptions

  • Spec Kit's "feature" is the capability here; a harness that reads Spec Kit keeps its folder names and says capability in its trackers.
  • The NIST SP 800-53 controls are named by their OSCAL identifiers; commons imports the Configuration Management slice (cm-2, cm-3, cm-4, cm-5, cm-9) from the NIST OSCAL catalog (0019-mizan-integrations FR-015), so that the identifiers are a typed code list and a misspelt one does not compile.
  • The relations between a change request and a change are PROV-O's (prov:used, prov:wasGeneratedBy); OSLC Change Management is adopted where its resource fits and is not the model of an issue tracker's workflow.
  • mz:Decision is not widened: it stays the authorization of an ontology term (why a term is unaligned). A departure, waiver or exception is authorized by an entry of the harness record file (FR-033), as built; this is revisited when a second kind of Decision appears (owner decision of 2026-11-17, issue #10).
  • The kind of a change request is read from a host's label (capability or problem), as built; an issue type or a section is not read (owner decision of 2026-11-17, issue #10).
  • This specification is Active from 2026-11-17: the requirements it does not yet prove say so in the enforcement register.
  • Git hosts' own words (issue, pull request, merge request) differ and are mapped once, in the adapter.

Open questions

None.

Key entities

  • Capability - the unit of change, with its rungs and its requirements.
  • Change request - an issue that plans a capability or reports a problem.
  • Change - the commits, and the pull or merge request, that implement a change request.
  • Configuration item and Baseline - what is under control, and the set of it at one revision.
  • Declaration - a harness's regulated domains and the day it declares production.
  • Trace stage - one link of the chain from an issue to a quality run.

Success criteria

SC-001success criterion

Every commit of a harness that has declared production names an issue, and the check fails the day one does not.

SC-002success criterion

A reviewer can follow any requirement from its issue to the run that proved it, and see where the chain breaks.

SC-003success criterion

No departure from a specification is authorized by anything but a Decision.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

commands/catalogue, changes, generate-ontology, Libraries, changes/capability-trace, changes/capability-view, changes/commit-message, changes/declaration, changes/git-log, changes/issue-body, changes/mod, changes/plugin, changes/rules, changes/strict, changes/terms-file, changes/trace, Mizan, rules, spec-terms, versions/gate, versions/notes, versions/record, ifccm/ifccm, ifccm/mod, Ontology, host/declaration, Quality, pure/chain-files, pure/freshness, pure/ladder, pure/ledger, Capabilities configuration (IFCCM), The harness of Mizan, Libraries, Quality evidence, Headless governance, Mizan, the IF Spec Profile, How works are versioned, Conformance levels, Subject profiles

Titles, headings, exports, tables, columns and requirements. Esc closes.