Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
397 changes: 62 additions & 335 deletions .github/hooks/validate-k9.sh

Large diffs are not rendered by default.

15 changes: 5 additions & 10 deletions .github/workflows/actions.lock
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ workflows:
- 'actions/checkout@v7.0.1'
'.github/workflows/static-analysis-gate.yml':
- 'actions/checkout@v7.0.1'
- 'actions/download-artifact@v8.0.1'
- 'actions/upload-artifact@v7.0.1'
- 'actions/download-artifact@v8.0.2'
- 'actions/upload-artifact@v7.0.2'
- 'erlef/setup-beam@v1.24.1'
'.github/workflows/wellknown-enforcement.yml':
- 'actions/checkout@v7.0.1'
Expand All @@ -66,21 +66,16 @@ dependencies:
commit: 'sha1-368f82528645a54fb793d4d04e342629a3f51346'
owner_id: 44036562
repo_id: 438112499
'actions/download-artifact@v8.0.1':
ref: 'v8.0.1'
commit: 'sha1-3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c'
'actions/download-artifact@v8.0.2':
ref: 'v8.0.2'
commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333'
owner_id: 44036562
repo_id: 192626254
'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f':
ref: 'v7.0.0'
commit: 'sha1-bbbca2ddaa5d8feaa63e36b76fdaad77386f024f'
owner_id: 44036562
repo_id: 192625955
'actions/upload-artifact@v7.0.1':
ref: 'v7.0.1'
commit: 'sha1-043fb46d1a93c77aae656e7c1c64a875d1fc6a0a'
owner_id: 44036562
repo_id: 192625955
'actions/upload-artifact@v7.0.2':
ref: 'v7.0.2'
commit: 'sha1-cf430e030ddbb5b0abf93d22962f4752f3646cd9'
Expand Down
80 changes: 52 additions & 28 deletions .github/workflows/dogfood-gate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,44 +68,68 @@ jobs:
name: Validate K9 contracts
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
# One validator per family (hyperpolymath/standards,
# docs/CONTRACTILE-DESCRIPTILE-VALIDATION.adoc): the canonical
# 1-formats/k9/tools/k9-validate.sh, strict, through layer L2, at the same
# standards commit rsr-template-repo pins. Ported from rsr-template-repo#247;
# the grep checks this hook used to run were a second validator.
env:
STANDARDS_REF: 'f0b3cd4c464d33e1584f8528c17bce104555e256'
NICKEL_VERSION: '1.18.0'
NICKEL_SHA256: '9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb'

steps:
- name: Checkout repository
uses: actions/checkout@v7.0.1
with:
persist-credentials: false

- name: Check for K9 files
id: detect
- name: Checkout canonical K9 validator
uses: actions/checkout@v7.0.1
with:
repository: metadatastician/standards
ref: ${{ env.STANDARDS_REF }}
path: .standards-k9
sparse-checkout: 1-formats/k9
sparse-checkout-cone-mode: true
persist-credentials: false

- name: Install sha256-verified Nickel CLI
run: |
COUNT=$(find . \( -name '*.k9' -o -name '*.k9.ncl' \) -not -path './.git/*' | wc -l)
CONFIG_COUNT=$(find . \( -name '*.toml' -o -name '*.yaml' -o -name '*.yml' -o -name '*.json' \) \
-not -path './.git/*' -not -path './node_modules/*' -not -path './.deno/*' \
-not -name 'package-lock.json' -not -name 'Cargo.lock' -not -name 'deno.lock' | wc -l)
echo "k9_count=$COUNT" >> "$GITHUB_OUTPUT"
echo "config_count=$CONFIG_COUNT" >> "$GITHUB_OUTPUT"
if [ "$COUNT" -eq 0 ] && [ "$CONFIG_COUNT" -gt 0 ]; then
echo "::warning::Found $CONFIG_COUNT config files but no K9 contracts. Run k9iser to generate contracts."
fi
set -euo pipefail
URL="https://github.com/tweag/nickel/releases/download/${NICKEL_VERSION}/nickel-x86_64-linux"
curl -sSfL --proto '=https' --proto-redir '=https' --tlsv1.2 --retry 3 -o "$RUNNER_TEMP/nickel" "$URL"
echo "${NICKEL_SHA256} ${RUNNER_TEMP}/nickel" | sha256sum -c -
chmod +x "$RUNNER_TEMP/nickel"
echo "$RUNNER_TEMP" >> "$GITHUB_PATH"

- name: Validate K9 contracts
if: steps.detect.outputs.k9_count > 0
run: bash .github/hooks/validate-k9.sh
- name: Write summary
run: |
K9_COUNT="${{ steps.detect.outputs.k9_count }}"
CFG_COUNT="${{ steps.detect.outputs.config_count }}"
if [ "$K9_COUNT" -eq 0 ]; then
cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
## K9 Contract Validation

:warning: **No K9 contracts found.** Run `k9iser generate .` to generate contracts.

Generate contracts with: `k9iser generate .`
EOF
else
echo "## K9 Contract Validation" >> "$GITHUB_STEP_SUMMARY"
echo "" >> "$GITHUB_STEP_SUMMARY"
echo "Validated **${K9_COUNT}** K9 contract(s) against **${CFG_COUNT}** config file(s)." >> "$GITHUB_STEP_SUMMARY"
set -euo pipefail
rm -rf "$RUNNER_TEMP/standards-k9"
mv "$PWD/.standards-k9" "$RUNNER_TEMP/standards-k9"
if [ ! -f "$RUNNER_TEMP/standards-k9/1-formats/k9/tools/k9-validate.sh" ]; then
echo "::error::K9 validator is missing from the standards checkout"
exit 1
fi
if ! command -v nickel >/dev/null 2>&1; then
echo "::error::nickel is required for K9 layer L2 validation"
exit 1
fi
STANDARDS_DIR="$RUNNER_TEMP/standards-k9" bash .github/hooks/validate-k9.sh | tee "$RUNNER_TEMP/k9.log"

- name: Write summary
if: always()
run: |
{
echo "## K9 Contract Validation"
echo ""
echo "Canonical validator (standards \`${STANDARDS_REF:0:7}\`), strict, layer L2:"
echo ""
grep -E '^K9: ' "$RUNNER_TEMP/k9.log" 2>/dev/null || echo "No result line: see the step log."
} >> "$GITHUB_STEP_SUMMARY"

# ---------------------------------------------------------------------------
# Job 3: Empty-linter — invisible character detection
Expand Down
6 changes: 4 additions & 2 deletions .github/workflows/workflow-linter.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,15 @@
failed=0
for file in .github/workflows/*.yml .github/workflows/*.yaml; do
[ -f "$file" ] || continue
if ! head -1 "$file" | grep -q "^# SPDX-License-Identifier:"; then
# actions-lock may prepend its own comment. Require the licence
# in the leading comment block, before the workflow body.
if ! awk '/^# SPDX-License-Identifier:/ { found=1 } /^[[:space:]]*[^#[:space:]]/ { exit } END { exit !found }' "$file"; then
echo "ERROR: $file missing SPDX header"
failed=1
fi
done
if [ $failed -eq 1 ]; then
echo "Add '# SPDX-License-Identifier: MPL-2.0' as first line"
echo "Add '# SPDX-License-Identifier: MPL-2.0' to the leading comment block"
exit 1
fi
echo "All workflows have SPDX headers"
Expand All @@ -64,7 +66,7 @@
fi
echo "All workflows have permissions declared"

- name: Check SHA-Pinned Actions

Check warning on line 69 in .github/workflows/workflow-linter.yml

View workflow job for this annotation

GitHub Actions / Hypatia neurosymbolic scan

[hypatia] workflow .github/workflows/workflow-linter.yml:69 step `Check SHA-Pinned Actions` swallows non-zero exit via `|| true` — failures will be masked
env:
GH_TOKEN: ${{ github.token }}
run: |
Expand All @@ -82,7 +84,7 @@
# No lockfile: every uses: must carry an inline SHA pin.
unpinned=$(grep -rnE "^[[:space:]]+uses:" .github/workflows/ | \
grep -v "@[a-f0-9]\{40\}" | \
grep -v "uses: \./\|uses: docker://\|uses: actions/github-script" || true)

Check warning on line 87 in .github/workflows/workflow-linter.yml

View workflow job for this annotation

GitHub Actions / Hypatia neurosymbolic scan

[hypatia] workflow .github/workflows/workflow-linter.yml:87 pins container `docker://\|uses:` by tag — tag is mutable; pin by sha256 digest instead

if [ -n "$unpinned" ]; then
echo "ERROR: Found unpinned actions:"
Expand Down
4 changes: 2 additions & 2 deletions .machine_readable/root-allow.txt
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ CHANGELOG.adoc # Current changelog after the AsciiDoc migration.

# ─── Build entry points (must live at root for their tooling) ────────────────
Justfile # delegates phases to build/just/*.just
coordination.k9 # repo-local session binding (template-mandated)
coordination.k9.ncl # repo-local session binding (template-mandated)

# ─── Conventional dotfiles (tool-required at root) ───────────────────────────
.editorconfig
Expand All @@ -51,7 +51,7 @@ ci/ # .gitlab-ci.yml, .pre-commit-config.yaml (root shims
docs/ # onboarding/, status/, governance/, ...
docs-template/ # template-only: scaffolding docs copied into new repos
machine-readable-design/ # template-only: design rationale for .machine_readable/ layout
session/ # dispatch.sh, custom-checks.k9, local-hooks.sh
session/ # dispatch.sh, custom-checks.k9.ncl, local-hooks.sh

# Source / test / artifact trees (project-specific but conventional)
src/
Expand Down
10 changes: 5 additions & 5 deletions .machine_readable/self-validating/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Configuration with Nickel contracts for runtime validation. Evaluated safely wit

=== Hunt Level (Full Execution)

**File:** `examples/setup-repo.k9.ncl`
**File:** `examples/setup-repo.k9.ncl.in`

Full execution with Just recipes. Can run shell commands and modify filesystem.

Expand All @@ -78,7 +78,7 @@ cp .machine_readable/contractiles/k9/examples/project-metadata.k9.ncl config/met
cp .machine_readable/contractiles/k9/examples/ci-config.k9.ncl .github/ci.k9.ncl

# Hunt: Full automation
cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl scripts/setup.k9.ncl
cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl.in scripts/setup.k9.ncl
----

=== 2. Validate Components
Expand Down Expand Up @@ -137,9 +137,9 @@ K9 contractiles integrate with other RSR standards:

Use these as starting points for your own K9 components:

- `template-kennel.k9.ncl` - Pure data template
- `template-yard.k9.ncl` - Validated config template
- `template-hunt.k9.ncl` - Full execution template
- `template-kennel.k9.ncl.in` - Pure data template
- `template-yard.k9.ncl.in` - Validated config template
- `template-hunt.k9.ncl.in` - Full execution template

== Dependencies

Expand Down
13 changes: 13 additions & 0 deletions .machine_readable/self-validating/methodology-guard.k9.ncl
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
K9!
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
#
Expand All @@ -8,6 +9,18 @@
# Usage: k9 validate methodology-guard

let methodology_guard = {
pedigree = {
schema_version = "1.0.0",
component_type = "validator:methodology-guard",
metadata = {
name = "methodology-guard",
version = "1.0.0",
},
security = {
leash = 'Yard,
},
},

name = "methodology-guard",
version = "1.0.0",
description = "Validates that agent work respects declared methodology constraints",
Expand Down
4 changes: 2 additions & 2 deletions EXPLAINME.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ How this is implemented:

* The local dispatcher (`session/dispatch.sh`) maps canonical commands to central
protocol paths in `standards/session-management-standards`.
* Local files (`session/custom-checks.k9`, `session/local-hooks.sh`,
`coordination.k9`) are integration-only.
* Local files (`session/custom-checks.k9.ncl`, `session/local-hooks.sh`,
`coordination.k9.ncl`) are integration-only.

Caveat:

Expand Down
37 changes: 30 additions & 7 deletions container/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,12 @@ All files use `{{PLACEHOLDER}}` tokens that are replaced by `just container-init
| **vordr** runtime monitoring configuration. Defines health endpoints,
crash detection, resource thresholds, and log output.

| `deploy.k9.ncl`
| **k9-svc** deployment component at Hunt trust level. Full pedigree
(L1--L5), environment configs (dev/staging/prod), container
configuration, and rolling deployment strategy.
| `deploy.k9.ncl.in`
| **k9-svc** deployment component at Hunt trust level, kept as a template:
environment configs (dev/staging/prod), container configuration and
rolling deployment strategy. Its pedigree predates K9 contract v1.0.0 and
its signature and checksum are placeholders, so it is not yet a component
(see below).

| `0-AI-MANIFEST.a2ml`
| AI-readable manifest describing the container directory, file
Expand Down Expand Up @@ -150,12 +152,33 @@ just container-push
selur-compose up --detach
----

For k9-svc managed deployments:
For k9-svc managed deployments, the deployment component ships as the
template `container/deploy.k9.ncl.in`. It is a `'Hunt` component whose
pedigree predates K9 contract v1.0.0, and its signature
(`PLACEHOLDER-SIGNATURE-REQUIRED-FOR-HUNT`) and checksum are placeholders.
Templates are not components, so the K9 lane does not validate it (as
rsr-template-repo#247 did for the template's own deployment component).
Before it can be used, upgrade its pedigree to contract v1.0.0 (capability
grant, side effects, signature block), sign it, and render it to
`container/deploy.k9.ncl`, which the K9 lane then validates.

The validator is `1-formats/k9/tools/k9-validate.sh` in a checkout of
https://github.com/metadatastician/standards[standards]; layer L2 also needs
https://nickel-lang.org[Nickel]. The repository's hook runs it over every
tracked K9 file, and looks for the checkout at `../standards` unless
`STANDARDS_DIR` names another:

[source,bash]
----
# Validate the deployment component
nickel typecheck container/deploy.k9.ncl
# Get the validator: a standards checkout beside this repository
git clone https://github.com/metadatastician/standards ../standards

# Validate every tracked K9 file, the rendered deployment component included
STANDARDS_DIR=../standards bash .github/hooks/validate-k9.sh

# Or validate the one file directly
bash ../standards/1-formats/k9/tools/k9-validate.sh --strict --layer L2 \
container/deploy.k9.ncl

# Deploy (requires Hunt-level authorisation)
k9-svc deploy container/deploy.k9.ncl --env production
Expand Down
File renamed without changes.
43 changes: 0 additions & 43 deletions coordination.k9

This file was deleted.

50 changes: 50 additions & 0 deletions coordination.k9.ncl
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
K9!
# SPDX-License-Identifier: MPL-2.0
# Thin coordination bindings for central session-management standards

{
pedigree = {
schema_version = "1.0.0",
component_type = "session:coordination-binding",
metadata = {
name = "session-coordination",
version = "0.1.0",
},
security = {
leash = 'Kennel,
},
},

session_management = {
source_of_truth = "standards/3-practice/session-management-standards",
canonical_commands = [
"intake repo <path>",
"checkpoint change <path>",
"verify maintenance <path>",
"verify substantial <path>",
"verify release <path>",
"close planned <path>",
"close urgent <path>",
"recover repo <path>",
"handover full <path>",
"handover split <path>",
"handover model <path>",
"handover human <path>",
],
},

signals = [
{ name = "session.intake", command = "intake repo <path>" },
{ name = "session.checkpoint", command = "checkpoint change <path>" },
{ name = "session.verify.maintenance", command = "verify maintenance <path>" },
{ name = "session.verify.substantial", command = "verify substantial <path>" },
{ name = "session.verify.release", command = "verify release <path>" },
{ name = "session.close.planned", command = "close planned <path>" },
{ name = "session.close.urgent", command = "close urgent <path>" },
{ name = "session.recover", command = "recover repo <path>" },
{ name = "session.handover.full", command = "handover full <path>" },
{ name = "session.handover.split", command = "handover split <path>" },
{ name = "session.handover.model", command = "handover model <path>" },
{ name = "session.handover.human", command = "handover human <path>" },
],
}
2 changes: 1 addition & 1 deletion docs/STATE-VISUALIZER.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
│ │ │ OCI │ │ cerro-torre │ │ │
│ │ │ Build │ │ svalinn/vordr │ │ │
│ │ └──────────┘ └───────────────┘ │ │
│ │ ct-build.sh deploy.k9.ncl │ │
│ │ ct-build.sh deploy.k9.ncl.in │ │
│ └──────────────────────────────────┘ │
└────────│─────────────────│──────────────┘
│ │
Expand Down
Loading
Loading