From 485769771cc55d1cbe0d7f3ddfd73e3db4fd4bcf Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Thu, 15 Oct 2026 18:13:50 +0200 Subject: [PATCH] chore: pin ct-conventions v0.5.0 - AGENTS.md pins ct-conventions v0.5.0 (read from a git-ignored clone in .conventions/) and cites rules by identifier; CLAUDE.md redirects to it. - References to the former Handbook become rule identifiers. - One .markdownlint.json (GEN2); CONTRIBUTING.md says where the conventions are and how to bump them. Co-Authored-By: Claude Opus 5.5 --- .gitignore | 5 +++- .markdownlint.json | 7 +++++ AGENTS.md | 64 +++++++++++++++++++++++++++++----------------- CLAUDE.md | 48 +++------------------------------- CONTRIBUTING.md | 8 ++++++ 5 files changed, 62 insertions(+), 70 deletions(-) create mode 100644 .markdownlint.json diff --git a/.gitignore b/.gitignore index 5528badd..7af5975f 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,7 @@ Manifest.toml # claude CLAUDE.local.md .claude/ -.coverage/ \ No newline at end of file +.coverage/ + +# ct-conventions, cloned at the tag pinned in AGENTS.md +.conventions/ diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..72ef7a5c --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,7 @@ +{ + "MD013": false, + "MD024": { "siblings_only": true }, + "MD033": false, + "MD046": false, + "MD051": false +} diff --git a/AGENTS.md b/AGENTS.md index ab6e4d8c..f9a8a139 100644 --- a/AGENTS.md +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md index 508cb879..e8713845 100644 --- a/CLAUDE.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d183077..4480cb9f 100644 --- a/CONTRIBUTING.md +++ b/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.