coulomb/kings-guard
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Apply GH-DEC-2026-017 to the layer declaration; close KG-IN-0007.

Browse source 
INTENT.md frontmatter governs and layer.yaml is marked derived from it.
standard_version is removed from both forms (A12). The checker and its
tests change in the same commit: they no longer require the field, they
reject it, they fold case against the four-token vocabulary (A9) instead
of comparing with plain equality, and they still fail a layer disagreement
that survives the fold (A11). Neither layer value is re-spelled.

The ruling answers kings-guard's "validated-against" reading of the field
(§5: version-scoped state belongs in the derived conformance record), so
that version now lives in the checker as VALIDATED_AGAINST and is printed
in every run's output. The standard: path in INTENT.md is unversioned to
match the reference form.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 63291@bnt-lap001
Assistant-Session: 8bd77868-ca68-4f49-bb1e-d539ecc0d703
This commit is contained in:
tegwick 2026-09-21 07:35:40 +02:00
parent 6752e5e570
commit 5120adf55a
6 changed files with 259 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

119
scripts/check_layer_conformance.py
View file

@ -16,10 +16,21 @@ OpenBao or cluster client during an incident because the engine surface still
does not exist (§9.2). That is precisely the "small convenience" §6 warns about,
and it would arrive as a one-line import.
Declaration form (GH-DEC-2026-017, amendments A9, A11, A12): INTENT.md's
frontmatter `layer:` key governs; layer.yaml is a derived artifact that must be
marked derived, name INTENT.md, and agree with it. Layer comparison ASCII-folds
case against §3's closed four-token vocabulary, so `Staff` and `staff` agree and
neither file is re-spelled. A disagreement that survives the fold is reported as
a finding, not resolved by precedence. Neither form may carry a
`standard_version`; the version this check was built and validated against is
the checker's own, VALIDATED_AGAINST below, and is printed in every run's output
— this script's output is the derived conformance record A12 points to.
Review dates are reported, never enforced: a date-triggered failure breaks the
build on a calendar day with no code change.
Exit 0 clean, 1 undeclared contact found, 2 declaration malformed.
Exit 0 clean, 1 undeclared contact found or the two declaration forms disagree,
2 declaration malformed.
"""
from __future__ import annotations
@ -35,6 +46,18 @@ import yaml
ROOT = Path(__file__).resolve().parents[1]
SRC = ROOT / "src" / "kings_guard"
DECL = ROOT / "layer.yaml"
INTENT = ROOT / "INTENT.md"
# The standard text this checker was built and validated against. This is the
# derived conformance record's version (GH-DEC-2026-017 §5 / A12), moved here
# from layer.yaml's former `standard_version: "0.7"`, which recorded the same
# fact in a place the ruling says a declaration must not carry it. Bump it when
# the checker is re-validated against a newer accepted text.
VALIDATED_AGAINST = "net-kingdom/canon/standards/security-layer-model_v0.7.md"
# §3's closed layer vocabulary (A9): four tokens, compared ASCII case-insensitively.
LAYER_VOCABULARY = {"taxonomy", "tooling", "engine", "staff"}
EXPECTED_LAYER = "staff" # kings-guard's own §4 row, folded
# Import roots that would constitute a direct Tooling-layer client under §4.
# Matched against the top-level module of every import in src/.
@ -77,25 +100,86 @@ CREDENTIAL_LITERAL = re.compile(
SKIP_CREDENTIAL_SCAN_DIRS = {".git", ".venv", "__pycache__", ".pytest_cache", ".ruff_cache"}
def fold(value: object) -> str:
"""ASCII case-fold, per §3 as amended (A9): two spellings are one token."""
return str(value).encode("ascii", "replace").decode("ascii").lower()
def _malformed(message: str) -> None:
print(f"FAIL: {message}", file=sys.stderr)
raise SystemExit(2)
def load_governing_layer() -> str:
"""The declaration: INTENT.md frontmatter `layer:` (§11, GH-DEC-2026-017 §1)."""
if not INTENT.exists():
_malformed(f"no {INTENT.name} — §11's governing declaration form")
lines = INTENT.read_text().splitlines()
if not lines or lines[0].strip() != "---":
_malformed(f"{INTENT.name} has no frontmatter to carry the declaration (§11)")
try:
end = lines[1:].index("---") + 1
except ValueError:
_malformed(f"{INTENT.name} frontmatter is not terminated")
try:
front = yaml.safe_load("\n".join(lines[1:end])) or {}
except yaml.YAMLError as exc:
_malformed(f"{INTENT.name} frontmatter is not parseable: {exc}")
if "layer" not in front:
_malformed(f"{INTENT.name} frontmatter has no 'layer' key — §11's declaration")
if "standard_version" in front:
_malformed(
f"{INTENT.name} frontmatter carries 'standard_version' — a layer "
"declaration MUST NOT carry a standard version (§11 as amended by A12)"
)
layer = front["layer"]
if fold(layer) not in LAYER_VOCABULARY:
_malformed(
f"{INTENT.name} declares layer {layer!r}, outside §3's closed vocabulary "
f"{sorted(LAYER_VOCABULARY)} (case-insensitive)"
)
if fold(layer) != EXPECTED_LAYER:
_malformed(f"{INTENT.name} declares layer {layer!r}, expected Staff (§4 row)")
return str(layer)
def load_declaration() -> dict:
"""The derived form, layer.yaml (§11 derived-artifact rule)."""
if not DECL.exists():
print(f"FAIL: no declaration at {DECL.relative_to(ROOT)} (§11)", file=sys.stderr)
raise SystemExit(2)
_malformed(f"no declaration at {DECL.relative_to(ROOT)} (§11)")
try:
data = yaml.safe_load(DECL.read_text())
except yaml.YAMLError as exc:
print(f"FAIL: {DECL.name} is not parseable: {exc}", file=sys.stderr)
raise SystemExit(2) from exc
for key in ("layer", "repository", "tooling_contacts", "standard_version"):
for key in ("layer", "repository", "tooling_contacts", "derived", "derived_from"):
if key not in data:
print(f"FAIL: {DECL.name} missing required key '{key}' (§11)", file=sys.stderr)
raise SystemExit(2)
if data["layer"] != "staff":
print(f"FAIL: declared layer is '{data['layer']}', expected 'staff'", file=sys.stderr)
raise SystemExit(2)
_malformed(f"{DECL.name} missing required key '{key}' (§11)")
if data["derived"] is not True:
_malformed(f"{DECL.name} must be marked 'derived: true' (§11, GH-DEC-2026-017 §1)")
if data["derived_from"] != "INTENT.md":
_malformed(
f"{DECL.name} derives from {data['derived_from']!r}; §11 names INTENT.md "
"as the governing declaration"
)
if "standard_version" in data:
_malformed(
f"{DECL.name} carries 'standard_version' — a layer declaration MUST NOT "
"carry a standard version (§11 as amended by A12)"
)
if fold(data["layer"]) not in LAYER_VOCABULARY:
_malformed(
f"{DECL.name} declares layer {data['layer']!r}, outside §3's closed "
f"vocabulary {sorted(LAYER_VOCABULARY)} (case-insensitive)"
)
return data
def forms_disagree(governing: object, derived: object) -> bool:
"""A11: the derived form must agree with INTENT.md, after the A9 case fold."""
return fold(governing) != fold(derived)
def imported_modules(path: Path) -> set[str]:
"""Top-level module name of every import in one file."""
try:
@ -147,6 +231,7 @@ def main() -> int:
parser.add_argument("--report", action="store_true", help="print the declaration summary")
args = parser.parse_args()
governing = load_governing_layer()
decl = load_declaration()
declared = {c.get("id") for c in decl.get("tooling_contacts") or []}
hits = scan()
@ -157,7 +242,9 @@ def main() -> int:
checks = decl.get("agent_principal_rule_checks") or {}
if args.report:
print(f"kings-guard — layer {decl['layer']}, standard v{decl['standard_version']}")
print(f"kings-guard — layer: {governing} (declared in INTENT.md; §11 governing form)")
print(f" layer.yaml: derived from {decl['derived_from']}, layer: {decl['layer']}")
print(f" checker validated against: {VALIDATED_AGAINST}")
print(f" tooling contacts declared: {len(declared)}")
print(f" unowned capabilities (§11 blocked-clean): "
f"{len(decl.get('unowned_capabilities') or [])}")
@ -173,6 +260,15 @@ def main() -> int:
form = meta.get("form", "unspecified") if isinstance(meta, dict) else "unspecified"
print(f" - {name}: {form} (claimed={rules.get(name)})")
if forms_disagree(governing, decl["layer"]):
print("", file=sys.stderr)
print("FAIL: the two declaration forms disagree (§11, A11)", file=sys.stderr)
print(f" INTENT.md (governs): layer: {governing}", file=sys.stderr)
print(f" layer.yaml (derived): layer: {decl['layer']}", file=sys.stderr)
print(" Case is already folded, so this is a real layer disagreement.", file=sys.stderr)
print(" It is a finding in its own right; precedence does not erase it.", file=sys.stderr)
return 1
if undeclared:
print("", file=sys.stderr)
print("FAIL: undeclared Tooling-layer client (§11 undeclared violation)", file=sys.stderr)
@ -206,7 +302,8 @@ def main() -> int:
if not args.report:
print(
f"OK: no direct Tooling client in {SRC.relative_to(ROOT)}; "
"no standing credential (§5, §11, §3.4 rule 1)"
"no standing credential (§5, §11, §3.4 rule 1); "
f"declaration forms agree; validated against {VALIDATED_AGAINST}"
)
return 0