chore: pin ct-conventions v0.5.0

.gitignore

@@ -33,4 +33,7 @@ Manifest.toml
 # claude
 CLAUDE.local.md
 .claude/
-.coverage/
+.coverage/
+
+# ct-conventions, cloned at the tag pinned in AGENTS.md
+.conventions/

.markdownlint.json

@@ -0,0 +1,7 @@
+{
+    "MD013": false,
+    "MD024": { "siblings_only": true },
+    "MD033": false,
+    "MD046": false,
+    "MD051": false
+}

AGENTS.md

@@ -9,39 +9,55 @@ Quick-reference for any agent working on this repository.
 CTParser is a single flat module — no submodule split, no `ext/`.
 
 ```text
-src/        # onepass.jl (the `@def` parser), defaults.jl, initial_guess.jl, utils.jl
-test/       # Test suite: flat files (not test/suite/)
-docs/       # Documentation site (DocumenterVitepress)
+src/           # onepass.jl (the `@def` parser), defaults.jl, initial_guess.jl, utils.jl
+test/          # Test suite: flat files (not test/suite/)
+docs/          # Documentation site (DocumenterVitepress)
+.conventions/  # ct-conventions, cloned at the pinned tag (git-ignored)
 ```
 
 ---
 
-## Developer Resources
+## Conventions
 
-Design philosophy, operational rules, plan templates, and CI/CD conventions live in the
-[control-toolbox Handbook](https://github.com/control-toolbox/Handbook):
+The coding conventions live in
+[ct-conventions](https://github.com/control-toolbox/ct-conventions), pinned below to a
+SemVer release tag (`vX.Y.Z`). Read them from a local clone in `.conventions/`
+(git-ignored, not a submodule). If it is missing, or `git -C .conventions describe --tags`
+is not the pinned tag, (re)create it:
 
-| Topic | Link |
+```bash
+rm -rf .conventions
+git -c advice.detachedHead=false clone --quiet --depth 1 --branch v0.5.0 https://github.com/control-toolbox/ct-conventions.git .conventions
+```
+
+**Pinned version: ct-conventions v0.5.0.** Cite rules by identifier (`MOD3`, `TST1`), and
+state the version you applied in plans and reports.
+
+Read in this order:
+
+| File | Content |
 | --- | --- |
-| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PHILOSOPHY.md) |
-| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/RULES.md) |
-| Plan template | [`PLAN.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PLAN.md) |
-| CI/CD workflows (centralized reusable workflows, label-gated triggers) | [`WORKFLOWS.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/WORKFLOWS.md) |
+| [`rules/general.md`](.conventions/rules/general.md) | Rules that hold everywhere — **always read** |
+| [`README.md`](.conventions/README.md) | Index of the rule files, one per area (`MOD`, `TYP`, `DIM`, `EXC`, `PERF`, `DOC`, `TST`, `SITE`, `CHG`) |
+| [`method.md`](.conventions/method.md) | How to work: tests, coverage, docs build, output capture |
+| [`plan-template.md`](.conventions/plan-template.md) | Template for a substantial piece of work |
+
+How agents behave on these repositories is described in
+[ct-agents](https://github.com/control-toolbox/ct-agents). The CI workflows and their
+trigger labels are described in
+[CTActions `docs/WORKFLOWS.md`](https://github.com/control-toolbox/CTActions/blob/main/docs/WORKFLOWS.md).
 
 ---
 
 ## Key Conventions
 
-- **No top-level exports** — use `Package.symbol` everywhere.
-- **Qualified imports** — `using Pkg: Pkg`, never bare `using Pkg`; `import` is never
-  used.
-- **Fake types at module top-level** — never inside test functions.
-- **Structured errors** — seven typed exceptions under `CTException`; pick by the
-  IncorrectArgument / PreconditionError / NotImplemented rule.
-- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET;
-  setup-path dispatch is fine.
-- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a
-  length-1 vector.
-- **Plans before code** — write a plan and confirm with the user before touching files.
-- **Docstrings last** — written only after all implementation steps are stable.
-- **Never commit or push without explicit user approval.**
+- **English everywhere** — code, docs, commits, issues, PRs (`GEN1`).
+- **No top-level exports** — use `Package.symbol` everywhere (`MOD8`).
+- **Qualified imports** — `using Pkg: Pkg`, never bare `using Pkg`; `import` is never used (`MOD3`, `MOD4`).
+- **Fake types at module top-level** — never inside test functions (`TST3`).
+- **Structured errors** — seven typed exceptions; pick by the choice rule (`EXC1`).
+- **Type stability enforced** — hot paths `@inferred`-clean, verified with JET (`TYP8`, `PERF1`–`PERF5`).
+- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number` (`DIM1`).
+- **Plan before code** — a local agent proposes a plan ([`plan-template.md`](.conventions/plan-template.md)) and waits for confirmation before working on code. The process for remote agents is still to be defined.
+- **Docstrings last** — written once the implementation is stable (`DOC1`–`DOC8`).
+- **The human merges** — an agent never merges a pull request.

CLAUDE.md

@@ -1,47 +1,5 @@
-# CTParser.jl — Agent Navigation Guide
+# CTParser.jl — Claude Code
 
-Quick-reference for any agent working on this repository.
+All agent instructions live in `AGENTS.md`; this file only redirects to it.
 
----
-
-## Repository Layout
-
-CTParser is a single flat module — no submodule split, no `ext/`.
-
-```text
-src/        # onepass.jl (the `@def` parser), defaults.jl, initial_guess.jl, utils.jl
-test/       # Test suite: flat files (not test/suite/)
-docs/       # Documentation site (DocumenterVitepress)
-```
-
----
-
-## Developer Resources
-
-Design philosophy, operational rules, plan templates, and CI/CD conventions live in the
-[control-toolbox Handbook](https://github.com/control-toolbox/Handbook):
-
-| Topic | Link |
-| --- | --- |
-| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://github.com/control-toolbox/Handbook/blob/main/PHILOSOPHY.md) |
-| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://github.com/control-toolbox/Handbook/blob/main/RULES.md) |
-| Plan template | [`PLAN.md`](https://github.com/control-toolbox/Handbook/blob/main/PLAN.md) |
-| CI/CD workflows (centralized reusable workflows, label-gated triggers) | [`WORKFLOWS.md`](https://github.com/control-toolbox/Handbook/blob/main/WORKFLOWS.md) |
-
----
-
-## Key Conventions
-
-- **No top-level exports** — use `Package.symbol` everywhere.
-- **Qualified imports** — `using Pkg: Pkg`, never bare `using Pkg`; `import` is never
-  used.
-- **Fake types at module top-level** — never inside test functions.
-- **Structured errors** — seven typed exceptions under `CTException`; pick by the
-  IncorrectArgument / PreconditionError / NotImplemented rule.
-- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET;
-  setup-path dispatch is fine.
-- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a
-  length-1 vector.
-- **Plans before code** — write a plan and confirm with the user before touching files.
-- **Docstrings last** — written only after all implementation steps are stable.
-- **Never commit or push without explicit user approval.**
+@AGENTS.md

CONTRIBUTING.md

@@ -12,3 +12,11 @@ If you want to ask a question, feel free to start a discussion [here](https://gi
 
 >[!NOTE]
 > If you want to add an application or a package to the control-toolbox ecosystem, please follow this [set up tutorial](https://github.com/orgs/control-toolbox/discussions/65).
+
+---
+
+## Developer Resources
+
+The [ct-conventions](https://github.com/control-toolbox/ct-conventions) repository (coding rules, method, plan template) is pinned to a SemVer release tag in `AGENTS.md` ("Pinned version"). Read it from a local clone in `.conventions/`, which git ignores; `AGENTS.md` gives the clone command.
+
+It is not a git submodule: `Pkg.add` on Julia 1.10 fails on a package whose tree contains one (`cannot get submodules without a working tree`). To bump it, change the tag in `AGENTS.md` (the "Pinned version" line and the clone command), then re-clone.