diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..4da9b57 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,52 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* `+LICENSES/+` directory (MPL-2.0, AGPL-3.0-or-later) and a root +`+REUSE.toml+` declaring licensing for owner-authored files. The project +is now fully compliant with version 3.3 of the REUSE Specification +(`+reuse lint+` passes). +* Claude Code project config under `+.claude/+`: a permission allowlist +for the safe git / reuse / shellcheck / estate-rules commands used to +validate this repo, plus a best-effort SessionStart hook that provisions +the lint tooling (reuse, shellcheck, asciidoctor) via package managers — +no piped remote scripts. + +==== Changed + +* Repaired the V-language ban check in the `+estate-rules+` workflow: a +find/replace had corrupted it to match the project’s core language (Zig) +rather than the V language, so the gate had been red since the initial +commit. It is now green. +* Rewrote `+docs/STATE-VISUALIZER.adoc+` to reflect honest design-phase +status (removed the inaccurate "`100% certified`" and PMPL claims). +* Replaced residual `+rsr-template-repo+` identity with `+llm-grace+` +(`+Justfile+`, `+EXPLAINME.adoc+`, `+TEST-NEEDS.adoc+`). +* Allowlisted `+SKELETON.adoc+` at the repo root; converted the +tech-debt audit note from Markdown to AsciiDoc. +* README / docs: withdrew the "`PMPL licensing debt`" framing per +ADR-0005, and wrapped three documentation mentions of SPDX identifiers +so `+reuse+` no longer mis-parses them as headers. + +==== Fixed + +* Corrected a broken `+find -exec+` (missing `+{}+` and terminator) in +the end-to-end template-instantiation test. + +==== Removed + +* Generated Idris2 build artifacts under `+src/interface/build/+` (now +git-ignored). + +==== Closed + +* Issue #3 ("`Licensing debt 2: PMPL-overlay migration`") — withdrawn +per ADR-0005; closed as not planned. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index b6c0cd0..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,48 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] - -### Added -- `LICENSES/` directory (MPL-2.0, AGPL-3.0-or-later) and a root `REUSE.toml` - declaring licensing for owner-authored files. The project is now fully - compliant with version 3.3 of the REUSE Specification (`reuse lint` passes). -- Claude Code project config under `.claude/`: a permission allowlist for the - safe git / reuse / shellcheck / estate-rules commands used to validate this - repo, plus a best-effort SessionStart hook that provisions the lint tooling - (reuse, shellcheck, asciidoctor) via package managers — no piped remote - scripts. - -### Changed -- Repaired the V-language ban check in the `estate-rules` workflow: a - find/replace had corrupted it to match the project's core language (Zig) - rather than the V language, so the gate had been red since the initial - commit. It is now green. -- Rewrote `docs/STATE-VISUALIZER.adoc` to reflect honest design-phase status - (removed the inaccurate "100% certified" and PMPL claims). -- Replaced residual `rsr-template-repo` identity with `llm-grace` (`Justfile`, - `EXPLAINME.adoc`, `TEST-NEEDS.adoc`). -- Allowlisted `SKELETON.adoc` at the repo root; converted the tech-debt audit - note from Markdown to AsciiDoc. -- README / docs: withdrew the "PMPL licensing debt" framing per ADR-0005, and - wrapped three documentation mentions of SPDX identifiers so `reuse` no - longer mis-parses them as headers. - -### Fixed -- Corrected a broken `find -exec` (missing `{}` and terminator) in the - end-to-end template-instantiation test. - -### Removed -- Generated Idris2 build artifacts under `src/interface/build/` (now - git-ignored). - -### Closed -- Issue #3 ("Licensing debt 2: PMPL-overlay migration") — withdrawn per - ADR-0005; closed as not planned. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..5949bf0 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,9 @@ +== Contributing + +[arabic] +. Fork the repository +. Create a feature branch +. Ensure SPDX headers on all files +. Submit a pull request + +*Author:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 8725e71..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,9 +0,0 @@ - -# Contributing - -1. Fork the repository -2. Create a feature branch -3. Ensure SPDX headers on all files -4. Submit a pull request - -**Author:** Jonathan D.A. Jewell diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..ffd8986 --- /dev/null +++ b/README.adoc @@ -0,0 +1,77 @@ +https://www.mozilla.org/MPL/2.0/[image:https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg[License: +MPL-2.0]] +image:https://img.shields.io/badge/status-design-orange.svg[Status: +design] + +Graceful degradation for concurrent LLM/agent terminals. When system +resources get hairy, sessions back off *voluntarily and in priority +order* — before the OS OOM-kills everything at once — so the work that +matters survives and a returning human comes back to an *autopsy, not a +smoking crater*. + +== Why + +Run several agent terminals on one box and the failure mode is brutal: +nothing backs off, memory craters, and the OS kills the whole VM — every +session dies at once, ungracefully, mid-thought. `+llm-grace+` makes +that failure *legible, bounded, and recoverable*. + +== How (one paragraph) + +A tiny monitor reads cheap signals the kernel already emits (`+/proc+` +counters — memory, swap-out rate, iowait, disk saturation, loadavg) and +reads them as *signatures*, not thresholds: the classic "`disk-thrash + +low CPU`" pattern is the pre-OOM tell. Sessions coordinate through one +shared crash-safe LMDB ledger. Under pressure, the *least valuable* work +yields first — value measured as motion, not size, so a thrashing +runaway is shed before productive work — climbing a per-session ladder: +silent PAUSE (auto-resumes) → CHECKPOINT (a human-in-the-loop latch, +loud) → clean TERMINATE (state already saved, never auto-relaunched). +Every transition is timestamped; terminated sessions get a per-session +autopsy, and the whole episode aggregates into one timeline so you can +see *how it went wobbly*. + +== Ethos (anti-failure-theatre) + +The autopsy and death-spiral timeline are fallbacks you hope never to +read, *not features to admire*. Success is the tool’s own invisibility: +thousands of silent cheap pauses, near-zero loud events. If you read +autopsies often, the tool has failed at its real job. No warranty — the +promise is not "`it won’t go wrong`" but "`when it does, you’ll know +exactly what killed you, and nothing is lost.`" + +== Status + +Design phase. The architecture is decided and recorded as ADRs: + +* link:docs/decisions/0003-graceful-degradation-architecture.adoc[ADR-0003 +— full architecture] +* link:docs/decisions/0004-attention-decay-vs-persist.adoc[ADR-0004 — +attention: persist] +* link:docs/decisions/0005-licensing-mpl-now-pmpl-overlay-later.adoc[ADR-0005 +— licensing posture (deliberate MPL-2.0 exception; no PMPL debt)] + +Build is tracked as native sub-issues under the requirements epic. First +adapter targets Claude Code hooks (`+PreToolUse+`, `+UserPromptSubmit+`, +`+SessionStart+`); the core idea is adapter-agnostic. It will be built +*test-first* against a controlled memory balloon in an isolated session +before anything goes global. + +== Licence + +*MPL-2.0* (see LICENSE) — legally effective today. + +This is a *deliberate, owner-ruled standalone exception* to the estate +canonical `+MPL-2.0+`, not drift. It is consistent with the estate +model: `+MPL-2.0+` (= Palimpsest-MPL) has MPL-2.0 as its automatic legal +base, so an MPL-2.0 repo is a clean subset. There is *no* "`PMPL +relicensing debt`" — that framing was a corrected false premise. +Canonical policy: `+hyperpolymath/standards+` `+LICENCE-POLICY.adoc+`. +Rationale: +link:docs/decisions/0005-licensing-mpl-now-pmpl-overlay-later.adoc[ADR-0005]. + +== Provenance / housekeeping + +Scaffolded from `+rsr-template-repo+` (the neutral RSR skeleton). The +full RSR placeholder bootstrap and the per-file SPDX relicense are +tracked build sub-issues rather than rushed inline — foundation-first. diff --git a/README.md b/README.md deleted file mode 100644 index bbf23a6..0000000 --- a/README.md +++ /dev/null @@ -1,81 +0,0 @@ - - -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](https://www.mozilla.org/MPL/2.0/) -![Status: design](https://img.shields.io/badge/status-design-orange.svg) - -Graceful degradation for concurrent LLM/agent terminals. When system -resources get hairy, sessions back off **voluntarily and in priority -order** — before the OS OOM-kills everything at once — so the work that -matters survives and a returning human comes back to an **autopsy, not a -smoking crater**. - -# Why - -Run several agent terminals on one box and the failure mode is brutal: -nothing backs off, memory craters, and the OS kills the whole VM — every -session dies at once, ungracefully, mid-thought. `llm-grace` makes that -failure **legible, bounded, and recoverable**. - -# How (one paragraph) - -A tiny monitor reads cheap signals the kernel already emits (`/proc` -counters — memory, swap-out rate, iowait, disk saturation, loadavg) and -reads them as **signatures**, not thresholds: the classic "disk-thrash + -low CPU" pattern is the pre-OOM tell. Sessions coordinate through one -shared crash-safe LMDB ledger. Under pressure, the **least valuable** -work yields first — value measured as motion, not size, so a thrashing -runaway is shed before productive work — climbing a per-session ladder: -silent PAUSE (auto-resumes) → CHECKPOINT (a human-in-the-loop latch, -loud) → clean TERMINATE (state already saved, never auto-relaunched). -Every transition is timestamped; terminated sessions get a per-session -autopsy, and the whole episode aggregates into one timeline so you can -see **how it went wobbly**. - -# Ethos (anti-failure-theatre) - -The autopsy and death-spiral timeline are fallbacks you hope never to -read, **not features to admire**. Success is the tool’s own -invisibility: thousands of silent cheap pauses, near-zero loud events. -If you read autopsies often, the tool has failed at its real job. No -warranty — the promise is not "it won’t go wrong" but "when it does, -you’ll know exactly what killed you, and nothing is lost." - -# Status - -Design phase. The architecture is decided and recorded as ADRs: - -- [ADR-0003 — full - architecture](docs/decisions/0003-graceful-degradation-architecture.adoc) - -- [ADR-0004 — attention: - persist](docs/decisions/0004-attention-decay-vs-persist.adoc) - -- [ADR-0005 — licensing posture (deliberate MPL-2.0 exception; no PMPL - debt)](docs/decisions/0005-licensing-mpl-now-pmpl-overlay-later.adoc) - -Build is tracked as native sub-issues under the requirements epic. First -adapter targets Claude Code hooks (`PreToolUse`, `UserPromptSubmit`, -`SessionStart`); the core idea is adapter-agnostic. It will be built -**test-first** against a controlled memory balloon in an isolated -session before anything goes global. - -# Licence - -**MPL-2.0** (see [LICENSE](LICENSE)) — legally effective today. - -This is a **deliberate, owner-ruled standalone exception** to the estate -canonical `MPL-2.0`, not drift. It is consistent with the estate model: -`MPL-2.0` (= Palimpsest-MPL) has MPL-2.0 as its automatic legal base, so -an MPL-2.0 repo is a clean subset. There is **no** "PMPL relicensing -debt" — that framing was a corrected false premise. Canonical policy: -`hyperpolymath/standards` `LICENCE-POLICY.adoc`. Rationale: -[ADR-0005](docs/decisions/0005-licensing-mpl-now-pmpl-overlay-later.adoc). - -# Provenance / housekeeping - -Scaffolded from `rsr-template-repo` (the neutral RSR skeleton). The full -RSR placeholder bootstrap and the per-file SPDX relicense are tracked -build sub-issues rather than rushed inline — foundation-first. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..7fa19c7 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,11 @@ +== Security Policy + +=== Reporting a Vulnerability + +*Email:* j.d.a.jewell@open.ac.uk + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5aecb31..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,13 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -**Email:** j.d.a.jewell@open.ac.uk - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc index af50472..b3a41d9 100644 --- a/docs/tech-debt-2026-05-26.adoc +++ b/docs/tech-debt-2026-05-26.adoc @@ -1,82 +1,80 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +== Tech-Debt Audit — llm-grace — 2026-05-26 -= Tech-Debt Audit — llm-grace — 2026-05-26 +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`. -*Source:* estate-wide automated scan 2026-05-26. + -*Companion:* https://github.com/hyperpolymath/standards/tree/main/docs/audits[hyperpolymath/standards 2026-05-26 estate-debt audits]. + -*Combined severity:* `LOW`. +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. -This file records the _raw findings_ — it does not by itself fix the debt. -Each section ends with a 'Recommended next move' line; closing the debt is -follow-up work. +=== 1. Proof debt -== 1. Proof debt +Scanner counted the following markers in proof-bearing files of this +repo: -Scanner counted the following markers in proof-bearing files of this repo: - ----- +.... files= 13 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 6 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 ----- - -*Total markers:* 6. *Severity:* `>06`. +.... -*Marker types* (any non-zero counts above): +*Total markers:* 6. *Severity:* `+>06+`. -* Coq `Axiom`/`Admitted` — unconditional proof escapes. -* Lean `sorry`/`axiom` — Lean's equivalent. -* Agda `postulate` — accepted axiomatically. -* Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -* Idris2 top-level `partial` — totality-check waived. -* F\* `assume val`/`admit_p` — F\* admit. -* `TODO PROOF` / `OWED:` — self-documented debt markers. -* `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. -*Recommended next move:* triage each finding into one of: (a) discharge by -proof, (b) cover with property-tests + a documented refutation budget, or -(c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. -== 2. Licence debt +=== 2. Licence debt -[cols="1,1",options="header"] +[cols=",",options="header",] |=== -| Field | Value - -| LICENSE file | `LICENSE` -| SPDX header | `NONE` -| Manifest licence | `NONE` -| Body classifier | `MPL-2.0-pure` -| Severity | `ok` +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+NONE+` +|Manifest licence |`+NONE+` +|Body classifier |`+MPL-2.0-pure+` +|Severity |`+ok+` |=== *Recommended next move:* none for licence. -== 3. Documentation debt +=== 3. Documentation debt -[cols="1,1",options="header"] +[cols=",",options="header",] |=== -| Field | Value - -| README lines | 77 -| `docs/` files | 72 -| `docs/` LoC | 4841 -| CHANGELOG.md | Y -| CONTRIBUTING.md | Y -| CODE_OF_CONDUCT.md | N -| SECURITY.md | Y -| Severity | `OK` +|Field |Value +|README lines |77 +|`+docs/+` files |72 +|`+docs/+` LoC |4841 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |N +|SECURITY.md |Y +|Severity |`+OK+` |=== *Recommended next move:* none for docs. -== Cross-references +=== Cross-references -* Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -* Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -* Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` -''' +''''' -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This -file is informational — closing the debt is follow-up work owned by the -maintainer. +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index c16ff5e..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,71 +0,0 @@ - - -# Tech-Debt Audit — llm-grace — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 13 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 6 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 6. **Severity:** `>06`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `NONE` | -| Manifest licence | `NONE` | -| Body classifier | `MPL-2.0-pure` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 77 | -| `docs/` files | 72 | -| `docs/` LoC | 4841 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | N | -| SECURITY.md | Y | -| Severity | `OK` | - -**Recommended next move:** none for docs. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/session/README.adoc b/session/README.adoc new file mode 100644 index 0000000..d14a6d7 --- /dev/null +++ b/session/README.adoc @@ -0,0 +1,45 @@ +== Session Bindings (Thin Local Layer) + +This directory provides local integration for central session-management +standards. + +Authoritative protocols live in: + +* `+../standards/session-management-standards/+` (or +`+$SESSION_STANDARDS_DIR+`) + +This repo keeps only thin bindings: + +* `+dispatch.sh+` maps canonical commands to central protocol paths. +* `+custom-checks.k9+` defines repo-local policy checks. +* `+local-hooks.sh+` provides optional repo-specific hook behavior. + +=== Canonical Commands + +* `+intake repo +` +* `+checkpoint change +` +* `+verify maintenance +` +* `+verify substantial +` +* `+verify release +` +* `+close planned +` +* `+close urgent +` +* `+recover repo +` +* `+handover full +` +* `+handover split +` +* `+handover model +` +* `+handover human +` + +=== Justfile Aliases + +Run `+just session-help+` to list aliases, then use recipes such as: + +* `+just intake-repo path=.+` +* `+just checkpoint-change path=.+` +* `+just verify-maintenance path=.+` +* `+just close-planned path=.+` +* `+just handover-model path=.+` + +=== Runtime Artifacts + +Runtime files are generated per repository in `+.session/+` and are not +canonical standards text. diff --git a/session/README.md b/session/README.md deleted file mode 100644 index 70d7444..0000000 --- a/session/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Session Bindings (Thin Local Layer) - -This directory provides local integration for central session-management standards. - -Authoritative protocols live in: - -- `../standards/session-management-standards/` (or `$SESSION_STANDARDS_DIR`) - -This repo keeps only thin bindings: - -- `dispatch.sh` maps canonical commands to central protocol paths. -- `custom-checks.k9` defines repo-local policy checks. -- `local-hooks.sh` provides optional repo-specific hook behavior. - -## Canonical Commands - -- `intake repo ` -- `checkpoint change ` -- `verify maintenance ` -- `verify substantial ` -- `verify release ` -- `close planned ` -- `close urgent ` -- `recover repo ` -- `handover full ` -- `handover split ` -- `handover model ` -- `handover human ` - -## Justfile Aliases - -Run `just session-help` to list aliases, then use recipes such as: - -- `just intake-repo path=.` -- `just checkpoint-change path=.` -- `just verify-maintenance path=.` -- `just close-planned path=.` -- `just handover-model path=.` - -## Runtime Artifacts - -Runtime files are generated per repository in `.session/` and are not canonical standards text.