v0.29.0

github-actions released this 21 Sep 08:15

3537847

Added

A process past its rehearsal cadence is reported. staleness now runs. kac validate warns on a process whose
last-rehearsed is "never", and on a quarterly or annual one more than 92 or 366 days past that date. The rule
was declared and ran on nothing, so a corpus could say every procedure was rehearsed on a cycle and be asked for no
evidence. on-change and per-release state an event, which no window measures, so a process using either is
reported only while last-rehearsed is "never".
days_since('field') measures a date field against the day of the run. An expression could already compare two
dates a record states, and ask whether one had gone by. Neither asks how old a record is. The fact answers zero where
a field is absent, is not a date, or names a day the run has not reached, so a rule comparing it against a threshold
leaves an absent value to required-field.
Every rule in a standard is held to a keyword in bold capitals. part-modal reads the bullets under each rule
heading and reports one that names none of MUST, MUST NOT, SHOULD, SHOULD NOT or MAY, one that leaves a
keyword in plain text, and a heading gathering no bullet at all. BCP 14 gives a keyword its meaning only in capitals,
and this corpus makes bold the thing a reader skims, so a keyword carrying one of the two bound nobody and nothing
said so. A type declares its own set in parts.binding: and parts.advisory:, which a heading source may now carry:
a glossary declares none and is asked nothing.
A standard names the standards it rests on. depends-on takes standard ids, and kac validate checks each one
resolves. ISO/IEC Directives Part 2 makes normative references a clause of every document, and a folder cannot say
that platform/dotnet/testing.md is no use without common/testing.md. The field travels in the export.
A superseded standard names its replacement. superseded-by takes a standard id and is required where status
is superseded, with supersedes the same edge read the other way. Both travel in the export, so a reader arriving
from an old citation is sent to the standard that replaced it.
A policy in force says the day it came into force. active-from takes the day, quoted, and kac validate
requires it where status is active. NIST SP 800-53 Rev. 5's -1 controls and ISO/IEC 27001 clause 5.2 both ask a
policy to record its approval, and owner says who without saying when. review-not-before-active fails a
review-by earlier than it. The date stays out of the export, and policy-lookup lists it among what stayed
behind. kac new sends a _template.md carrying the field, and a corpus already holding an active policy owes
the date at its next kac update.
An integration says how the estate would leave it. Exit is a section, and exit-required warns where a
critical or important integration still in use has none. Article 30(3)(f) of DORA asks an ICT contract for an
exit strategy, and the section travels in the export. kac new sends a _template.md naming it.
A retired integration names what took over. successor takes an integration id, replaces is the same edge
read the other way, and kac validate checks both ends. retired-has-successor warns where a retired integration
names none. Both fields travel in the export.
An integration on trial says what would end the trial. Trial criteria is a section, and
trial-criteria-required warns where a trial integration has none. The section stays out of the export, because
a consumer reads status.
A control that never stops says so. frequency takes continuous. A control whose mechanism is
runtime-alert has to carry a frequency, and none of per-pr through annual is true of an alert rule that
evaluates without stopping.
A manual control says when it last ran. last-verified takes the day, quoted, or "never", and kac validate
requires it where mechanism is manual. An automated check leaves a run in its own logs, and a periodic human
check leaves nothing otherwise. It travels in the export, and kac new sends a _template.md naming it.
A data document says whether it holds personal data. personal-data takes none, personal or
special-category, and kac validate requires it. retention is now required from this field rather than from
classification, so data that is confidential and personal is asked for a retention period.
A data document says who the data is about. data-subjects takes the categories of people, in the corpus's own
words, and kac validate requires it where personal-data is anything but none. GDPR Article 30(1)(c) asks for
the categories of data subjects, and the NIST Privacy Framework asks the same as ID.IM-P3.
A data document says where the data is kept. region takes a cloud region or a place, and kac validate
requires it. The Where it lives table asked for it and nothing read the answer.
A data document says what the data is for. Purpose is a required section. GDPR Article 30(1)(b) asks for the
purposes of the processing, and the NIST Privacy Framework asks the same as ID.IM-P5.
The Flows table says where each recipient processes the data. kac new sends a _template.md with the
column. region covers the owning service, so a transfer out of the country is recorded beside the recipient that
makes it, which is what GDPR Article 30(1)(e) asks about.
A data document says when someone checks it again. review-by takes the day, quoted, and kac validate
requires it. It travels in the export, which moves data's shape to version 2. classification, personal-data,
retention and region are claims about a store that nothing in a corpus checks, and no field asked anybody to
confirm them. The ICO asks you to review retained personal data regularly and to justify how often, and NIST SP
800-53r5 RA-2 asks that a categorisation be revisited. classification-in-date warns once the date has passed.
A deviation rates the risk it leaves. risk takes high, medium or low, and kac validate requires it.
The rating is the risk left once what compensates is working, and high-risk-review-window warns where a high
rating sets review-by more than six months after accepted-on.
A deviation says what can still go wrong. What the risk is is a required section, and it travels in the
export. The sections beside it said what limits the risk and never what remains of it.
A deviation can name who does the work. assigned-to takes a person or a post, and stays out of the export.
owner accepts the risk and this field closes it, which are one person in a small estate and two in a large one.
A rule can measure a gap in days. days('a', 'b') counts whole days between two date fields, where span()
answers in hours between two timestamps. docs/design/expressions.md is the reference.
An explanation says what it covers. What this covers is a required section, and it travels in the export. It
states what the record covers and what it leaves to another record, which is what keeps the residual type bounded.
kac validate reports sections against an explanation without it, and kac new sends a _template.md carrying
it.
A fix says what you were running. Environment is a required section, and it travels in the export. It states
the tool, the operating system and the versions, which is how a reader tells whether the fix is theirs.
applies-to takes service ids alone, and a fix about a laptop or a pinned tool version has no service to name.
kac validate reports sections against a fix without it, and kac new sends a _template.md carrying it.
A rule can ask whether a key is written once. entries_unique('field', 'key') reads one key across the objects
a field holds and answers false where two of them state the same value. True where the field is absent.
docs/design/expressions.md is the reference.
An NFR says which quality it commits to. characteristic is required, and takes accuracy, availability,
capacity, latency, recovery, scalability or throughput. The values sit at ISO/IEC 25010's
subcharacteristic level, so a corpus can list the qualities it has promised nothing about. It travels in the export,
indexes beside the target, and kac new sends a _template.md naming it.
An NFR states the period its figure is read over. window takes the period, such as monthly or
rolling 4 weeks. kac validate requires it where characteristic is availability, capacity, latency or
throughput, because a rate or a percentile only means something over a stated period. A recovery, scalability or
accuracy target binds each event or each value, so it needs none. It travels in the export.
An NFR says why the figure is that one. Why this number is a required section, and it travels in the export.
It states what fixes the figure and what the target leaves out, which the three records in examples/payments were
each stating inside Target. kac validate reports sections against an NFR without it.
An agreed NFR says when it was agreed. agreed-on takes the day, quoted, and kac validate requires it where
status is agreed. An agreed target is a commitment somebody accepted, and nothing recorded when. It travels in
the export.
A process says when it is rehearsed again. rehearsal-frequency is required, and it takes a new on-change
beside per-release, quarterly and annual. ComplianceForge HCGF reviews a procedure when its technology, its
steps or its people change. NIST SP 800-53 Rev. 5's -1 controls ask for a frequency and the events beside it.
Nothing running on a schedule can measure on-change, so process-lookup tells a reader to ask what has moved.
kac new sends a _template.md carrying the field. A corpus already holding a process writes a value into every
one of them, because kac update reaches the schema and never a record.
A process says how to back out. If it goes wrong is a required section, where it was optional. The type page
already promised a rollback, and the section stays out of the export, because a reader who has to back out is
holding the record. kac new sends a _template.md naming it.
A runbook says who is affected. Impact is a required section, and it travels in the export beside Symptoms.
The Google SRE workbook asks a playbook to explain the severity and the impact of the alert it answers, and
severity said only how urgent. kac new sends a _template.md naming it.
A runbook says who to tell. Communication is a required section. AWS Well-Architected OPS07-BP04 puts
stakeholders and a communication plan on a playbook, and PagerDuty asks a responder for status updates throughout.
Escalation says who to wake, and this says who is waiting. The section stays out of the export, because a reader
telling anybody is holding the record. kac new sends a _template.md naming it.
A runbook lists its tools apart from its permissions. requires-tools takes what the reader installs. AWS
Well-Architected OPS07-BP03 gives a runbook a column for each, and two of the three runbooks in examples/dog-fooding
were writing a tool into requires-access. It travels in the export, and kac new sends a _template.md naming it.
A service says what sort of component it is. component-type is required, and takes its range from the corpus as
platform does. Backstage, OpsLevel and Cortex each require this word of a catalogue entry. It travels in the export,
and a corpus adopting services writes enums.component-type in .corpus.yaml before its first record validates.
A tool entry names the packages it approves. packages takes one entry per package, each a
package URL with the version range approved for it. CycloneDX 1.6 and
SPDX 2.3 both identify a component that way, and drift-against-manifests had nothing to match a manifest entry
against. Spectre.Console and Spectre.Console.Cli are one decision at two ranges, which the single versions
string could not state. It travels in the export.
A tool entry links the project it names. homepage is required and takes an https:// address. SPDX gives
every package a home page, and the OpenSSF guide to evaluating open source software opens by asking whether you have
the project you think you have. No entry in examples/dog-fooding linked its own project.
A tool entry carries two dates. decided-on says when the current status was settled, and review-by says when
somebody checks the entry again. Both are required and both travel in the export. Every entry in
examples/dog-fooding was writing the first into the body as prose, and nothing stated the second, so an approval
taken once governed new work for ever. review-in-date warns once review-by has passed.
A deprecated or rejected tool says what went wrong with it. exit-states-a-reason warns where ## Status is
absent, so somebody proposing the same package in two years finds the evaluation rather than repeating it.
A tool entry may record an accessibility assessment. Accessibility is a declared section and travels in the
export. std-A11Y in examples/dog-fooding requires an assessment in the tool record of any component rendering a
governed surface, and two entries were carrying one under a heading the type did not declare, which the export
dropped.
data records travel in the export. .schema/data.yaml declares an export: block at version 1, so
kac export writes one file per data document and kac bundle ships them with the plugin. classification,
personal-data, data-subjects, retention, region and flows-to travel as frontmatter, and Purpose,
Entities, Where it lives, Classification, Retention and Flows travel whole. A service's data-stores
cited records no consumer could read. Every type in the taxonomy now declares a block.

Changed

An NFR says whether anybody is held to its target. status takes a fourth value, aspirational, for a figure
somebody settled that the estate is not measured against. The Google SRE workbook keeps such an objective measured
and tracked, and exempts it from the error budget policy a miss otherwise triggers; What we do about a breach is
where that exemption is written. nfrs publishes at export.version 4, because a reader that took agreed and
draft to be the only live values would now read an aspirational target as binding.
An NFR records what it is achieving now. Current actual was optional and is now required, so the reading sits
beside the target in every record. It stays out of the export, because an export has no way to say how old a
measurement has since become.
An NFR states what a breach costs and what the response to one is, in two sections. If it is breached was one
required section, and a record could answer with either half. What a breach costs and What we do about a breach
are both required, so required-section reports the one a record left out. The Google SRE workbook keeps an error
budget apart from the error budget policy that spends it. nfrs publishes at export.version 3, because a reader
taking the consequence out of If it is breached would now find no section under that name.
An integration id starts itg-, not int-. kac validate rejects int-sendgrid, and ref-resolves reports
each citation still pointing at one. int is a reserved word in C# and in most languages a maintainer reads, and
int- also matches constraint- and print-, so a search for an integration id returns mostly lines that are not
one. integrations publishes at export.version 2, because a reader matching ^int- on an exported id would now
match nothing. Rename the id in every integration record, and in every citation of it. kac generate then rewrites
integrations/_index.md, whose heading reads Integration Index (ITG).
policies states what it takes from current practice. lineage was measured against ComplianceForge HCGF's
policy layer, NIST SP 800-12 Rev. 1 and NIST SP 800-53 Rev. 5. alignment said a policy pushes its mandatory
language down to the standard beneath it, and 206 of the 243 clauses in examples/engineering are MUST or
MUST NOT. alignment, divergence and collision now describe a policy that binds in its own right, and
kac generate writes all three into every adopting corpus's knowledge-as-code/lineage.md.
versions on a tool is gone, and a version range sits on the package instead. packages states the range for
each package it approves, so a family chosen together can be pinned apart. tools publishes at export.version 2,
because a reader that took a range out of versions would now find none there. The tool index lists review-by
where it listed versions.
Status on a tool is optional, and says why the tool sits where it is. It was required, and carried the status
and the date the status was set, which the frontmatter already states. exit-states-a-reason asks for it of a
deprecated or a rejected entry, which are the two stances that owe a reader an explanation.
tools states what it takes from current practice. lineage was measured against the Thoughtworks Technology
Radar, CycloneDX 1.6, SPDX 2.3 and the OpenSSF guide to evaluating open source software. alignment claimed named
technologies sorted by stance, and the index sorts by category. divergence claimed binding version ranges, and the
field was optional, unchecked and empty on three of 13 entries. Both now describe the schema as it stands, and
divergence records the assess ring this register does not have.
target on an NFR no longer carries the measurement window. The window is window, so a consumer reads the
figure and the period apart. nfrs publishes at export.version 2, because a reader that took the period out of
target would now find none there.
requires-access on a runbook takes a permission and no longer a tool. A tool is requires-tools, so a reader
sees what to install apart from what somebody has to grant them. runbooks publishes at export.version 2, because
a reader that took a tool out of requires-access would now find none there.
A runbook says how urgent it is. severity is required, where it was optional. The Google SRE workbook asks a
playbook to explain the severity of the alert it answers, and Impact states the other half.
A runbook says when it is rehearsed again. rehearsal-frequency is required, where it was optional. No runbook
anywhere set it, so the declared staleness-loud rule could only ever fire on a last-rehearsed of "never".
Nothing running on a schedule can measure on-change, which the field accepts. A corpus that already has a runbook
writes a value into every one of them, because kac update copies the schema and never a record.
runbooks states what it takes from current practice. lineage was measured against the Google SRE book, the
Google SRE workbook's On-Call chapter and AWS Well-Architected OPS07-BP03 and BP04. alignment named a statistic
and no field or section, and now names the five it is true of. divergence records that AWS writes a playbook to
find the cause and a runbook to resolve it, where this type is both on one page. collision said the industry uses
runbook and playbook interchangeably, which is true of Google and not of AWS. kac generate writes all three
into every adopting corpus's knowledge-as-code/lineage.md.
nfrs states what it takes from current practice. lineage was measured against ISO/IEC 25010:2023 and the
Google SRE workbook's Implementing SLOs. alignment names the four things the workbook asks an objective for, and
divergence names the error budget it keeps and this type does not take. kac generate writes both into every
adopting corpus's knowledge-as-code/lineage.md.
A glossary term carries the other names it answers to. **Also:** gives a second name for the same thing, an
acronym or an abbreviation, and **Avoid:** gives a name the glossary has dropped. Both travel in the export as
also and avoid, so a search reaches a term by a name its heading does not carry. SKOS calls the first an
altLabel and DITA glossentry calls it a glossAlt, and neither had anywhere to go here before.
parts.asides: replaces parts.aside:, and takes a list. A type declares every bold label its parts may open a
block with, and export.parts.line: addresses one as part.aside.<Label>. part.aside on its own is gone.
Against a schema still naming either, kac validate reports schema-unknown-key for the block key and
schema-dispatch for the line source. It reports schema-shape against a label the type's parts.asides: does not
declare.
glossary states what it takes from current practice. lineage was measured against Evans, Domain-Driven
Design, SKOS and DITA glossentry. prior-art now names all three, and alignment and divergence say what the
type takes from each and where it parts from them. kac generate writes both into every adopting corpus's
knowledge-as-code/lineage.md.
manual-periodic is now manual. The value held a cadence inside a method name, where frequency states the
cadence beside it. kac validate reports enum against a control still carrying the old value, and a corpus
rewrites it by hand.
classification grades confidentiality alone. The field takes public, internal and confidential.
personal and special-category move to personal-data, because a category of data is not a grade of sensitivity.
kac validate reports enum against a data document still carrying either value in classification, and a corpus
rewrites it by hand.
data states what it takes from current practice. lineage was measured against GDPR Article 30, the NIST
Privacy Framework v1.0 and ISO/IEC 27002:2022. alignment claimed transfers and security measures, which the type
asks for nowhere. Both now name what the type takes and where it parts from them. kac generate writes both into
every adopting corpus's knowledge-as-code/lineage.md.
controls states what it takes from current practice. lineage was measured against NIST SP 800-53A Rev. 5,
the OSCAL assessment models and the CIS Controls Assessment Specification. alignment and divergence now name
what the type took from each and where it parts from them. kac generate writes both into every adopting corpus's
knowledge-as-code/lineage.md.
A deviation's owner is a person, never a post. The field takes human:alex.doe alone, where every other type
also admits role:. One individual accepts a risk and a post cannot. kac validate reports field-pattern
against a deviation still naming a role, and assigned-to is where a post belongs.
deviations states what it takes from current practice. lineage was measured against NIST SP 800-37 Rev. 2,
the PCI DSS v4.0 compensating controls worksheet and the FedRAMP POA&M template. alignment claimed a bounded
period and tracked remediation, which the type asks for nowhere. Both now name what the type takes and where it
parts from them. kac generate writes both into every adopting corpus's knowledge-as-code/lineage.md.
An explanation can explain a standard, a process or an ADR. explains took a service or an offering alone, and
a subject is not always a deployable thing. The export's shapeVersion for the type moves from 1 to 2, because a
reader that resolved every id in the services or offerings folder would now be wrong.
explanations states what it takes from current practice. lineage was measured against Diátaxis, the Good
Docs Project's concept template and arc42. alignment claimed discursive prose and weighed alternatives, which the
type asks for nowhere. Both now name what the type takes and where it parts from them. kac generate writes both
into every adopting corpus's knowledge-as-code/lineage.md.
fixes states what it takes from current practice. lineage was measured against the KCS v6 article, the
ServiceNow known error form and ITIL Problem Management. alignment names the four sections KCS asks for, and
divergence names the workaround ITIL expects and this type does not take. kac generate writes both into every
adopting corpus's knowledge-as-code/lineage.md.
verified says who has checked a record, not how often. An actor is written once, and a check they make again
moves the at on the entry they have. The Open Knowledge Format keeps the list for independent checks, a human
sign-off beside a nightly process, and git already keeps when each actor checked before. kac validate reports
one-verification-per-actor against a fix or a report naming one actor twice, and a corpus trims each list by
hand. The trust tier reads the actors and never the count, so no tier moves.
processes states its lineage against EPA QA/G-6. The type declared ComplianceForge HCGF and the Diátaxis
how-to guide. prior-art adds Guidance for Preparing Standard Operating Procedures. alignment and divergence
state what the comparison found: the review frequency and date EPA QA/G-6 asks for, the experience a procedure does
not state, and what git and owner answer for instead of a revision number and a signature. The row no longer
claims the rehearsal date has no precedent. A collision: entry names what ITIL and BPMN mean by process. All
three render into knowledge-as-code/lineage.md.
reports states what it takes from current practice. lineage was measured against the Open Knowledge Format
v0.2, SARIF 2.1.0 and NIST OSCAL Assessment Results 1.1.3. alignment now names the OKF keys and the actor forms
the schema declares. divergence adds the three verification rules OKF has no equivalent for, the status values
active and stale, and the staleness read from each source's content-version instead of OKF's stale_after.
Both render into knowledge-as-code/lineage.md.
repo on a service is now repos, and takes a list. OpsLevel lets one component name several repositories,
and an asset surface is defined in one repository and filled from another. Each entry matches
^[a-z0-9-]+$, where repo was held to no pattern, so a corpus spelling one as org/name or a URL owes a second
edit. services publishes at export.version 2, because a reader that took a string out of repo would now find
nothing there. feature-file-repo reads every entry of the list.
services states what it takes from current practice. lineage was measured against the Backstage software
catalog, OpsLevel and Cortex. alignment said the type states the APIs a component consumes, and no field does.
alignment and divergence now describe the type as it stands, and kac generate writes both into every adopting
corpus's knowledge-as-code/lineage.md.

Fixed

meta/type.schema.json offers part.citations.<Label>. The editor's copy of the line-source vocabulary never
had a pattern for it, so it marked standards.yaml's covers: part.citations.Covers as invalid while the build
stayed green. MetaSchemaTests now holds that enum to the list the exporter fills.

Assets 2