From 0985473b6ab1b4c061deff7e2e9fa1c0b756f9e1 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:25:59 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CHANGELOG.adoc | 52 +++++++++++++++ CHANGELOG.md | 48 -------------- CONTRIBUTING.adoc | 9 +++ CONTRIBUTING.md | 9 --- README.adoc | 77 +++++++++++++++++++++++ README.md | 81 ------------------------ SECURITY.adoc | 11 ++++ SECURITY.md | 13 ---- docs/tech-debt-2026-05-26.adoc | 112 ++++++++++++++++----------------- docs/tech-debt-2026-05-26.md | 71 --------------------- session/README.adoc | 45 +++++++++++++ session/README.md | 42 ------------- 12 files changed, 249 insertions(+), 321 deletions(-) create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 session/README.adoc delete mode 100644 session/README.md 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.