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
1 change: 1 addition & 0 deletions commitlint.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,7 @@ const configuration: UserConfig = {
},

defaultIgnores: true,
ignores: [(commit) => commit.startsWith("Squashed '") || commit.includes('git-subtree-dir:')],
formatter: '@commitlint/format',
}

Expand Down
1 change: 1 addition & 0 deletions repos/constitution/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
node_modules/
1 change: 1 addition & 0 deletions repos/constitution/.husky/commit-msg
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
deno run --allow-read --allow-env --allow-run --allow-sys npm:@commitlint/cli@21 --edit $1
1 change: 1 addition & 0 deletions repos/constitution/.husky/pre-commit
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
deno task test
121 changes: 121 additions & 0 deletions repos/constitution/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# AGENTS.md — Constitution Repository

Single source of truth for the supreme design law of [System F Software](https://systemfsoftware.com). Consumer repos vendor via `git subtree` + symlink. This repo has no production code, no test suite, and no build step — it is two documents plus governance tooling (corpus validation, commit validation): `CONSTITUTION.md`, the maker's law, resident in every agent's context, all articles, always; and `ENFORCEMENT.md`, the instrument owner's doctrine, never loaded into the maker's context.

@CONSTITUTION.md

## Startup Workflow

Before making changes:

1. **Read this file** completely.
2. **Confirm the active task** with the user or the agent's task list.
3. **Review recent commits** with `git log --oneline -5`.
4. **Ensure current branch is not `main`** — feature branches only. If on main, create one.

## Working Rules

- **One task at a time.** Finish before starting the next.
- **Conventional commits required.** The commit-msg hook enforces `type(scope): description`. Run `git commit` through the hook — do not bypass with `--no-verify`.
- **Verification required.** Run the verification commands before claiming done.
- **Stay in scope.** Don't modify files unrelated to the task. Scope reduction requires explicit user approval.
- **Leave clean state.** The next session must run verification immediately.

## Amending the Constitution

### Corpus

- **`CONSTITUTION.md` (Resident):** the entire maker corpus — the Application section plus Articles I–V — loaded in every session. There is no retrieved half and no on-demand trigger: law that is not in the window is not law. Residency delivers obligation, not enforcement; the machinery of judgment lives outside the maker's reach.
- **`ENFORCEMENT.md` (Non-resident):** the instrument owner's doctrine — gate design, instrument-change discipline, enrollment law. Read by whoever builds or changes a gate, never `@`-imported into a maker's context. Consumer repos route to it from the leaves that own enforcement surfaces (lint plugins, guard scripts, CI workflows, rules directories, advisor rosters): one line — "You are editing an enforcement instrument. Read the vendored `ENFORCEMENT.md` before this lands." A routing line added anywhere else is the defect: the maker must not meet instrument doctrine while doing graded work.

### Writing a Rule

Rules are fenced YAML blocks with: `id`, `title`, `gate`, `do`, `dont`, `harm`, `check` (and optional `example`, `scope`, `layers`).

### Minting an ID

ID format: `CONST-<family><n>`. Pick the next free number in the family (never renumber to close gaps).

| Letter | Family | Purpose |
|---|---|---|
| `G` | Governance | Invoking constitution or resolving priority |
| `E` | Enforcement | The maker's conduct under judgment (evidence, the instrument boundary); instrument design lives in `ENFORCEMENT.md` |
| `P` | Purity | Decision functions and side-effect isolation |
| `D` | Domain modelling | Domain types and constraints |
| `B` | Boundary | Core/shell boundaries, effects, adapters |
| `T` | Testing | Testing strategy, mutation, properties |
| `N` | Naming & structure | Module organization and naming |
| `W` | Work discipline | Task scope, bypass declarations, reviews |
| `S` | Subtraction | Code deletion and structural simplification |

### Changing a Rule

- Same obligation reworded / moved: **keep ID**.
- Obligation narrowed, widened, split, or deleted: **retire old ID forever** and mint new one.
## Surface Classes

| Surface | Files | Rule |
|---|---|---|
| **Locked** | `AGENTS.md`, `.husky/_/`, verification scripts | Read and propose changes; do not edit to make verification pass. |
| **Editable** | `deno.json`, `deno.lock`, `commitlint.config.cjs`, `.gitignore`, `.husky/` (hooks only, not `_/`) | Edit freely within the active task. |
| **Human-controlled** | `CONSTITUTION.md`, `README.md`, merging to `main`, pushing, destructive ops | Propose changes; ask the user before acting. |

## Definition of Done

A task is done only when ALL of the following are true:

- [ ] Target changes are applied.
- [ ] Verification commands ran and passed.
- [ ] Commit uses conventional format (`type(scope): description`).
- [ ] Evidence recorded via the runtime memory system and task list.
- [ ] No dirty files left in the working tree.

## Verification Commands

```bash
deno task test # one file: schema, coverage, ids, families, dangling citations
deno run --allow-read --allow-env --allow-run npm:@commitlint/cli@21 --from HEAD~1
```

After a commit that deletes, splits, merges, or re-scopes a rule — not after every edit — also run the reassignment check against the revision before it:

```bash
deno task test --against <rev>
```

### Anti-Bypass Rules

- Run the **full command**, not parts in isolation.
- Evidence must be from the **current run**, not a prior session.
- **Any failure blocks done.** Do not bypass with `--no-verify`.
- Do not suppress, skip, or disable checks to make verification pass.

### Hallucination Prevention

- **Read before edit:** before editing a file, read it in the current session. Do not edit from memory.
- **Verify before claim:** before saying "done," the verification command must have run and its output recorded.
- **Search before write:** before writing code that calls a library API, read the actual API surface. Do not generate from training memory.

## Multi-Agent Ownership

When multiple agents work in the same repo:

- Each agent owns a disjoint file/module set.
- An agent must claim a file before editing it.
- Agents may not recursively delegate to each other.
- The one-shot verification must pass before any agent claims done.

## End of Session

Before ending a session:

1. Record current state, blockers, and next steps via the runtime memory system and task list.
2. Commit with a conventional-format message once work is in a safe state.
3. Leave the repo clean — `git status` should show nothing unexpected.

## Escalation

- **Constitution conflict**: `CONSTITUTION.md` is already in context — reread it there, not from disk.
- **Unclear requirements**: Ask the user.
- **Verification failure**: Record via memory, flag for review, do not bypass.
- **Scope ambiguity**: Re-read this file and the Definition of Done.
1 change: 1 addition & 0 deletions repos/constitution/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@AGENTS.md
21 changes: 21 additions & 0 deletions repos/constitution/CONCEPTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Concepts

Shared domain vocabulary for this project — entities, named processes, and status concepts with project-specific meaning. Seeded with core domain vocabulary, then accretes as ce-compound and ce-compound-refresh process learnings; direct edits are fine. Glossary only, not a spec or catch-all.

## Constitution corpus

### Constitution corpus
The complete set of law documents the repository ships, treated as one unit. The corpus is what the gate certifies and what agents are bound by — not any single file's contents. Shrinking the measured portion of the corpus is a defect, not an optimization.

### Rule
One fenced YAML block inside the constitution carrying an id of the form `CONST-<family><number>` — the family letter is one of G, E, P, D, B, T, N, W, S (governance, enforcement, purity, domain modelling, boundary, testing, naming & structure, work discipline, subtraction). A rule is the atomic unit of law: it is minted with a fresh number, amended in place, or vacated. Minting takes the next free number in the family — a minting law enforced by review, not by the gate. A vacated number is never reused for new law.


### Vacuous pass
A gate exiting green because it measured less than it claims — a missing input, an input that contributes nothing, a comparison arm that reads only part of the history. The output shape is identical to a healthy run, so the green actively certifies the absence of defects it did not look for. The doctrine this repo's gate is built on: assert the corpus, not only the contents; a gate that cannot fail is a certificate, not enforcement.

### Residency
The delivery contract for the maker's law: whatever must bind the agent's choices is always present in its context window, with no retrieval step. The counter-design — a thin resident pointer plus retrieved full text — forces presence at fetch time but never conformance at use time. Residency delivers obligation, not enforcement: the window tells the maker what is required, and whether the requirement held is decided afterward by instruments the maker cannot edit (ENFORCEMENT.md). What cannot fit residency is reference material and instrument doctrine, not law.

### Corpus gate
The single check that certifies the constitution corpus — schema of every rule block, id and family registry, citation integrity across the corpus, and cross-revision comparison on demand. It runs as the repository's test command and again at every commit through the pre-commit hook, which makes any corpus-shape change also a gate change: the gate certifies the very input set a restructure edits.
Loading