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
6 changes: 5 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
# Save / load solution data files
*.jld2
*.json
!.markdownlint.json

# System-specific files and directories generated by the BinaryProvider and BinDeps packages
# They contain absolute paths specific to the host computer, and so should not be committed
Expand Down Expand Up @@ -39,4 +40,7 @@ Manifest.toml

#
.windsurf/
.reports/
.reports/

# ct-conventions, cloned at the tag pinned in AGENTS.md
.conventions/
7 changes: 7 additions & 0 deletions .markdownlint.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"MD013": false,
"MD024": { "siblings_only": true },
"MD033": false,
"MD046": false,
"MD051": false
}
65 changes: 40 additions & 25 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,40 +9,55 @@ Quick-reference for any agent working on this repository.
CTDirect is a single flat module — no submodule split, no `ext/`.

```text
src/ # DOCP construction (DOCP_*.jl), collocation.jl, direct_shooting.jl, ode/ schemes
test/ # Test suite: flat files (not test/suite/) — aqua.jl, problems/, gpu tests
docs/ # Documentation site (DocumenterVitepress)
src/ # DOCP construction (DOCP_*.jl), collocation.jl, direct_shooting.jl, ode/ schemes
test/ # Test suite: flat files (not test/suite/) — aqua.jl, problems/, gpu tests
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. (The current source still uses `import` in places — treat the Handbook rule as
the target for new/edited code, not a description of existing lines.)
- **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`). The current source still uses `import` in places: the rule is the target for new and edited code, not a description of existing lines.
- **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.
10 changes: 9 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,19 @@
<!-- markdownlint-disable MD024 -->
# Changelog

All notable changes to CTDirect will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### 📚 Documentation

- ct-conventions pinned at 0.5.0 in `AGENTS.md` (read from a git-ignored clone in
`.conventions/`); `AGENTS.md` cites rules by identifier, `CLAUDE.md` redirects to it, and
the references to the former Handbook become rule identifiers. One `.markdownlint.json`
(`GEN2`) replaces the `markdownlint-disable MD024` comment of this changelog (`CHG2`).

## [1.1.6-beta] - 2026-08-30

Fixes two more unresolved cross-references in inherited discretization docstrings, same shape
Expand Down
49 changes: 3 additions & 46 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,5 @@
# CTDirect.jl — Agent Navigation Guide
# CTDirect.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

CTDirect is a single flat module — no submodule split, no `ext/`.

```text
src/ # DOCP construction (DOCP_*.jl), collocation.jl, direct_shooting.jl, ode/ schemes
test/ # Test suite: flat files (not test/suite/) — aqua.jl, problems/, gpu tests
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. (The current source still uses `import` in places — treat the Handbook rule as
the target for new/edited code, not a description of existing lines.)
- **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
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions probe/shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ in a `CTModels.Model`, and what the cost of each candidate fix would be.

It backs the roadmap item
[#610 §7 / discussion #609 §7](https://github.com/control-toolbox/CTDirect.jl/discussions/609)
and the Handbook rule
[`philosophy/dimension-and-shape.md`](https://github.com/control-toolbox/Handbook/blob/main/philosophy/dimension-and-shape.md):
and the ct-conventions rule
[`DIM1`](https://github.com/control-toolbox/ct-conventions/blob/main/rules/dimension.md):

> A one-dimensional quantity is a `scalar`, never a length-1 vector.

Expand Down
6 changes: 3 additions & 3 deletions probe/shape/probe_shape.jl
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
# dynamics!(r, t, x, u, v) lagrange(t, x, u, v) mayer(x0, xf, v)
# path!(r, t, x, u, v) boundary!(r, x0, xf, v)
#
# The Handbook contract (philosophy/dimension-and-shape.md) says a 1-D quantity must
# The ct-conventions contract (DIM1) says a 1-D quantity must
# reach the user function as a `Number`, never as a length-1 vector, with the coercion
# driven by the *declared* dimension (`only` when dim == 1, `identity` otherwise).
#
Expand Down Expand Up @@ -84,7 +84,7 @@ end
#
# Every user function records the *types it was handed* into SEEN, and computes with
# `[1]` indexing so it stays correct whether it receives a scalar or a 1-vector
# (the Handbook's "safe common denominator").
# (the "safe common denominator" of ct-conventions DIM3).
# =============================================================================

const SEEN = Dict{Symbol,Any}()
Expand Down Expand Up @@ -507,4 +507,4 @@ println()
println("Legend for block A cells: <arg1>/<arg2>/<arg3>")
println(" dynamics / lagrange / path : x / u / v")
println(" mayer / boundary : x0 / xf / v")
println("Contract target (Handbook): 1-D quantity → Number; n-D → Vec(n).")
println("Contract target (ct-conventions DIM1): 1-D quantity → Number; n-D → Vec(n).")
Loading