Conventions

The rules a thing has to satisfy to be finished, for any Solid Plans Software project. Philosophy.md holds the design discipline these rules are derived from and is the why behind them, workflow.md says how work is done and tools.md what to invoke; this document is the checkable half — what a module looks like, what documents it carries, and what a change has to leave behind before it counts as done.

These rules are language-agnostic on the same seam Philosophy.md states: the framework owns structure and contracts, a repo adapter owns the language it adapts. So a rule here is stated so that any adapter’s author can act on it, illustrated with Python where an example makes it concrete, and the spelling one language gives it lives with that language’s adapter — INSTRUCTIONS.md in the package the repository’s repoAdapter coordinate resolves to. A repository’s commands and its adapter are themselves Python whatever language they adapt, so the CLI application section below is host-language shape and crosses nothing.

A convention here is not a matter of taste. Each one exists because the alternative is that every new module re-decides the same question, and every structural improvement then has to be made once per answer. Where a rule has a reason, the reason is written next to it: the next exception is argued against the reason, never against the text.

Module structure

The manifest is the inventory of src/, in both directions

Everything in a module’s src/ is either module machinery or a unit the manifest declares, and the correspondence is checked both ways:

The entrypoint has one spelling on purpose. A module whose entrypoint is named after the module reads well in its own checkout and badly everywhere else: the exception becomes “a bare file whose name matches the module”, which a check has to derive rather than name, and the invocation then differs per application for no reason a caller benefits from. One spelling means one invocation everywhere — python -m <module>.src.app in Python — and a static exception a reader can hold in their head.

The two are one invariant. Every package in src/ is a declared unit and every declaration has its unit, machinery aside, and a difference in either direction is a gate failure rather than a warning — the MOD001 lint rule reads each repository’s own manifest, which is where its code is edited, and names which side is wrong.

The dynamic exception is what makes the rule livable without making it toothless. A declaration is what turns a file into a real unit: it has an owner, a place in the typed dependency graph, and a name the module answers for. So a genuinely single-file concern does not need a wrapper directory to be legitimate — it needs to be declared. A loose file has none of that, which is the actual complaint: its ownership, its tests, and its schema have nowhere to live.

Such a module is declared with rootDir naming the file and entryPoint naming that same file: the file is the unit, so it is its own entry point rather than pointing at a second file beside it. Dependency detection reads it the same way — the file’s imports are the module’s, and they stop being credited to whichever module encloses the directory it sits in.

Constants follow from this and need no rule of their own. Constants shared across a module’s packages are a manifest-declared constants module at src/ — a single-file submodule, a leaf in the dependency graph that every consumer visibly depends on; Python’s is src/constants.py. Package-local constants stay in the package that owns their concern. Which tier a constant belongs to is answered by its imports rather than by guessing: one importing package means local, two means shared. The constants-location check knows both homes by name — it accepts a constants.py wherever it sits — so it is the two-tier question above, not the check, that decides which one a constant goes to; a shared constant parked in a package’s own file passes the check and still leaves every other package importing across a boundary that is nobody’s. The facade stays pure either way — siblings import the constants submodule directly, and the module’s boundary facade re-exports only the subset that crosses the module boundary. Packages define, the facade exposes, and nothing is defined in the facade itself.

A dependency on another repository’s package is declared by the module that calls it

A module nested in another declares the coordinate of a package it calls among its own dependencies and imports that package itself. The boundary facade is for the other kind of crossing: a module the same manifest declares outside the top-level module, which a nested module still reaches only through the facade, and what a generated type binds.

The reason is what a declaration costs when it is placed too high. A package declared on the top-level module and re-exported through its facade is a dependency of every module nested there, whether one of them calls it or all of them do, so a change in it reaches them all: selecting by change runs nearly every test of the nest for a change in a package a single nested module called. Declared on that module, the same change runs the caller and what depends on it. module dependency list --validate accepts a coordinate on a nested module and module dependency detect --validate holds the declaration to the import, so the narrow declaration is checked like any other.

What stays on the top-level module is what it imports in its own files and what its facade hands down because the whole nest is built on it. A package one or two nested modules call is theirs to declare.

The producer’s side of the same question goes the other way: an application publishes one API, and its internal libraries stay nested in it. Splitting an API into pieces that each depend on less only pays where the commands behind the pieces reach different code, and that is a measurement before it is a design. A proposal to split an application’s API owes two counts first: how many of its commands reach each library, and how many of its recent changes a consumer’s pieces would have missed.

A package is a unit of responsibility, not a wrapper for a file

The check can only see file placement and manifest declarations, and there are two cheap ways to satisfy it that fix nothing. One is to wrap each bare file in a directory of its own — eight loose files become eight one-file packages, and the tree is exactly as disorganized as before with an extra level of nesting. The other is to declare every bare file in the manifest and move on. Neither is the fix, and an agent working to get the gate green will find both immediately.

A directory under src/ earns its place by being a cohesive subsystem: one concern, with its schema, generated types, validator, and tests co-located — the schema that defines the boundary, the logic that serves it, nothing else’s business inside. The test is what else moves in with the file. If a file’s schema, tests, and closest collaborators come along, and the directory has a one-line answer to “what is this subsystem for”, it is a package. If the file arrives alone and the directory name is the file name, it is a wrapper.

The same test applies to a large loose file that is really a seam between several subsystems: it splits along the responsibilities it spans, not into one package named after the file. Two files that are two halves of one subsystem move into that subsystem rather than becoming two packages.

The manifest half has a structural guard the wrapper half does not: manifest changes are flagged for human review, so every dynamic exception is a decision a person signed off on rather than an edit made to pass a check. The declaration is the outcome of deciding a file is a genuine single-file unit — never the move that makes the check pass. Editing the manifest to silence this rule is the signal to stop and reorganize instead, or to surface the question.

A genuinely self-contained single-file concern has two legitimate forms: a manifest-declared bare file when it is small and stable, a one-file directory package when its schema and tests are visibly on their way. Either needs its one-line answer. When neither yields an obvious home, that is a design question to raise — not a directory to invent, and not a manifest line to add.

A repository’s code lives under src/

Every repository keeps its implementation in src/, whatever kind of module it holds. An application’s src/ sits below its app definition and its typed documents; a library’s sits below the package root that is its public surface — whatever declares that surface in the language, the facade modules the package declares public, its generated types, its schema, and nothing else. In Python that is the root __init__.py, the facade modules named in __public_submodules__, and __types__/.

One shape rather than two is the point. A repository whose code is spread across its root is a repository that answers structural questions differently from its neighbours: where a unit goes, what a path means, which directory a new feature lands in. Fixing that once per repository is the cost this convention removes, and it is what makes a change to how repositories work something that can be made in bulk rather than translated into each layout in turn.

The public surface stays at the root, because that is what a consumer imports. Where a package declares public submodules, each is a small facade module at the root re-exporting from src/, so the surface a consumer names is unchanged by how the implementation is arranged behind it — which is the whole reason for having a declared surface.

The build discovers a repository’s packages rather than being told them twice

A build that requires an explicit list of a repository’s packages has a second declaration of what the tree already says, and it drifts in both directions while hiding both. An entry naming a directory the build cannot find fails a fresh clone and every worktree while an existing checkout keeps working, which makes the failure read as a broken clone rather than as a wrong list; a package missing from the list is invisible until something packages the repository for real.

So the list is not kept — the layout is arranged so the build can discover it, which is one declaration instead of two and nothing to forget in the change that adds a package. What the layout has to be for discovery to work is the language’s answer and is the adapter’s to state.

Where a build genuinely cannot discover them, the list is not left to memory: the package joins it in the same change that creates it, and a test holds the list to the tree in both directions, so the change that forgets fails rather than the clone that follows it.

Every repository carries its own manifest.yml at its root

The correspondence above is checked against a manifest, so a repository whose modules are declared only in a consumer’s manifest cannot be checked in its own checkout — the invariant would hold from that consumer’s checkout and nowhere else, which is the wrong place for it, since the repository is where the code is edited. A repository that stands alone declares what it contains.

An application’s rootDir is its repository root rather than the src/ inside it: a module rooted below the root moves where its generated code expects the boundary facade to sit.

A schema store is reached by declaration and never by search. A coordinate in a document resolves against the store of the repository that holds the document, and never against a store found further up. A repository reaches another store’s documents only through a reference it declares and anyone can follow — vendoredSchemas, read from the stores its schema catalog is wired to — because an undeclared walk to a parent’s store is coupling nothing records and a clone standing alone cannot reproduce.

The documentation set

A module a reader or an agent cannot orient in is as unfinished as one with loose files in src/. The documents that do the orienting are part of the shape, not a per-repository decision.

What a README is for

A README states what its repository or module is now — its surface, its contracts, its rules, and the reasoning that makes them make sense. Every README is held to that, a submodule’s included. It is not a changelog and not a record of how the code got here: no used to, no longer, formerly, now lives in, the old behaviour, no account of what was removed, renamed or split out, and no this once broke anecdote. A reader who has never seen the previous shape should not be able to tell there was one.

Rationale survives the rule; history does not. Where a past failure is why a rule exists, write the rule and the failure it prevents in the present tense — “a model asked to track them miscounts” rather than “a model miscounted, which is how a table once rendered wrong”. The reason is still there, and it stays true after the next change instead of quietly becoming a second, stale account of the code.

Evolution belongs in git history, commit messages, pull request bodies and the queue notes that own the work — never in a README, and never in the main context file either. A document that carries it goes stale silently, and a reader cannot tell which half is current. The main context file is held to the same rule as a README: it states what to do in this repository now, with at most a clause of reason per rule, and it carries no dated summary of recent work — a session that needs to know how something came to be reads the history, where the account is attached to the change it describes.

A public module’s own README is client documentation

The README at the root of a public module – packages/<name>/README.md, the one inside the package – is that module’s documentation for the people it is released to, and it is published as written. A module is public when its manifest says audience: public, one of the three audiences below. The README sits in the directory the module is archived from, so it is in what a client receives; a release also files it on the module’s entry in the catalog clients pull from, and documentation is generated from that catalog alone. So there is no second, client-facing copy to keep in step – the same answer client help has, one text written for whoever receives it. For a library the README is the whole of the documentation and stands alone: what the library is for, how it is obtained, its public surface, and the document formats it defines. For an application it is the overview; the configuration and command reference are generated from the application’s declarations, so the README says what each area is for and restates neither. Installation is in neither: the toolchain’s install documents itself.

A module has one of three audiences, stated as audience in its manifest. public is released to clients and documented for them: a release files it in the catalog clients obtain packages from, with its README, and it is listed in the documentation generated from that catalog. hidden is released to clients the same way and documented nowhere: nothing a client browses lists it, so it is obtained by being told its coordinate, or it arrives beside a module that depends on it. internal is what a module is by stating none, and reaches no client. public and hidden together are the external audiences. So “is this public” is two questions – whether a module is external, which public and hidden are, and whether it is documented for one, which public alone is – and anything that reads an audience says which it asks. A library that reaches a client depends, at run time and at build time, only on modules that reach one too, public or hidden, and dependency validation refuses any other by name; hidden is a library’s audience, never an application’s.

It names nothing internal, and nothing hidden. No internal library or application – a module is internal unless its manifest says otherwise – no hidden library, since naming one in documentation documents it, no internal mechanism, no pull request, and nothing about how the repository is built, vendored, gated or released: no repository that pins it, no dev vendor or lib/, no catalog wiring, no account of the gate or of CI, no measurement, no ruling. What the product itself works with is named freely, as it is in client help. A public library’s dependencies are public or hidden, so a README names the public ones as what arrives with it and says nothing of the rest.

It names a tool as the executable a client runs. Anything a client reads refers to a tool as an independent executable, by its name – impl-tool issue run --issue <file> – and never as a package: no python -m impl_tool.src.app, no invocation through a package manager, no import name standing in for the tool. The package spelling describes a checkout of the tool’s source, which a client does not have, and it is how the tool is built rather than what it is called. That holds for every tool a public document mentions, its own included, and for a library’s README that shows a command line.

The README at the repository’s root is the repository’s own, and says everything else. It is read by whoever has the repository, which for a private repository is the people who work in it and never a client, so it is held to “What a README is for” and to nothing more. It opens by saying what the repository is and pointing at the module’s README for what the module is and how it is used, and then carries what that README may not: the layout of the source, how the tests are kept, how the package sits in the repository and why it is built the way it is. It does not restate the module’s README – two copies of a reference are two things to keep in step – so the whole account is the two read together. What is true only of working in the repository, what a fresh clone needs before it builds or how its gate is started, is the main context file’s, and behaviour is SPEC.md’s.

Where a module is rooted at its repository, the two are one file, and it is the client’s. A module whose rootDir is . has no directory of its own for a second README, so the README at the root is the one inside the package and is held to the client rule; what a contributor needs goes in the main context file. The same holds by choice for a repository that is itself public: its front page is read by clients, so it is written for them.

It links only to what a client receives. A relative link is followed from where the README is, inside the module, and names a tracked file under the module’s rootDir: the module’s archive carries what the repository tracks there. It does not climb out of the module – to the repository’s README, the main context file or the shared documents – and it does not link to a pull request or into the repository’s own forge account.

A hidden module’s README is held to the same rule. It is documentation nobody is pointed at, and the module’s archive still carries it to whoever was told the module’s name, so it names nothing internal, runs a tool by its executable’s name and links only inside the module. It may name another hidden module, which its reader was told of the same way, and a hidden module owes no README at all.

It links each platform type, schema and error code it names, as a sentinel. A sentinel is a Markdown link whose target names the kind of thing it names: schema:<namespace>:<name> for a schema, schema:<namespace>:<name>#<definition> for one of its definitions, by the key the schema files it under, builtin:<type> for a built-in type of the schema language, and error:<CODE> for an error code – [`ManifestModule`](schema:manifest:manifest#manifestModule). It reads as a link wherever the README is rendered, and the documentation generated from a release resolves each one to the page of what it names. So every such name is written as one in the ordinary course of keeping the README, by whoever keeps it, rather than added afterwards. A built-in’s name is also an ordinary word – string, path – so nothing catches it written bare, and it is linked by hand where a reader would want the page.

project readme list --validate holds it, in the gate. It refuses, in the README at the root of a module declared public or hidden, the name of a module declared internal – and in a public module’s, the name of a hidden one – a tool run as a package through an interpreter, a relative link that leaves the module’s root, a link to a pull request and a link into the repository’s own forge account, a sentinel naming nothing the tree declares, and a code span that is exactly a declared error code or the class name generated for an exported schema’s definition with no sentinel linking it; and it refuses a public module’s README being absent. It has no allowance: a violation is moved to the repository’s README, never excused. A plain project readme list reads every module’s README the same way and reports, which is how one is brought into shape before its module’s audience is declared. The check reads names and links; that the README says what the module is, in words a client can use, is review’s.

What a SPEC is for

A SPEC states the behaviour its module has now, precisely enough to be wrong about — the command surface, what each command takes, what it resolves, what it refuses, what it writes, and the reasoning that makes those answers hang together. The README says what a module is; the spec says what it does. Its test is whether a reader can hold the code up against it and say which of the two is wrong.

It is addressed to somebody who has to know what the thing does, never to somebody reconstructing a decision, and that is what decides what it leaves out. The circumstance a rule arrived under — the defect it was found by, the experiment that settled it, the shape it replaced, the day it broke something — belongs in the commit message that made the change, the queue note that owns the work, or the pull request body, each of which is read by somebody asking how we got here. A spec carrying it makes the reader strain the behaviour out of an account of its own history.

The narration to refuse is the README rule’s, in the tenses a spec reaches for: no was, used to, previously, no longer, this replaced, this is what three defects were each found by, no walk-through of an investigation and its numbers, and no paragraph whose subject is the software’s past rather than the software. Where a past failure is why a rule exists, write the failure as a standing property — “a prompt written into the middle of a JSON document is a parse error in the reader” — rather than as an event the rule is the sequel to. The reason still argues for the rule, and it stays true after the next change instead of becoming a second, stale account of the code.

A measurement is behaviour when it is a limit the reader has to work within, and history when it is the story of how a default got chosen: “sound to about 20KB of diff and fabricating by 60KB” is a property of the model a caller must plan around, where the run that discovered it is not. The same number can be either, and what decides it is whether somebody using the thing needs it.

Where the rule that survives is one sentence and the paragraph around it was the account of how we found it, the sentence is the edit. A spec comes out shorter than the history it was written from, and that is the outcome rather than a loss.

CLI applications

An application and its commands are host-language code — Python, in every repository and whatever language that repository is otherwise written in, because the framework loads them in process — so the file names below are the names everywhere rather than one language’s spelling of them.

A CLI application is a module like any other, plus the following. The through-line is that the application’s typed documents live at module root and its code lives in src/.

A typed document’s schema is schema.yml. The directory it sits in is what says which document it defines, so repeating that in the filename adds nothing and takes one more place a rename has to reach: config/schema.yml, state/schema.yml, manifest/schema.yml. The same holds at a repository root, where the repository’s name is what the directory says. A schema carrying a name of its own is one that is not the directory’s single subject — a feature’s schema beside the code it defines, like measurement.schema.yml, where the directory holds a subsystem rather than one document.

Config, state, and manifest are the same kind of thing: a typed document at the application’s boundary, defined by a schema and consumed as one generated object. That is why all three sit at module root rather than in src/, which is the code. A future document of the same kind gets the same treatment.

A git-ignored typed document is migrated by the code that writes it

A typed document root carries the version of the schema it was written under. That field is granted rather than authored, so a schema change that adds or requires one reaches every tracked document through the same merge that carries the change — and reaches a git-ignored document not at all. What is left behind is not a stale file somebody will notice: it is a document the application validates before it does anything, so the next invocation refuses to start, and the tool that would repair it is the tool that will not run. That is the shape to design against, because a repair which requires a working copy of the thing being repaired is no repair.

So the rule is about who writes the document, and it splits three ways.

The corollary is worth stating for whoever lands the next grant: a change that makes a field inherent to every document root is not finished when the tracked documents carry it. It is finished when every ignored document root in the repository has been named, checked against which of the three cases above it belongs to, and either migrated by its writer, moved into tracking, or shown to be a layer rather than a document. A document that is neither is one that will stop a tool on somebody else’s machine, long after the change that caused it.

A CLI module exports nothing but its command surface and its api

Nothing outside the module imports anything from it except the generated api — src/ internals and the root config/state/manifest packages included. This is enforced rather than advised, on the same footing as the public-boundary rule and a module’s boundary facade: for a CLI module the facade is api, and there is no other door.

The replacements are the shapes already in use: reach another application by process invocation with a JSON envelope, or by its api, or vendor the schema of the document you actually need. An import that must cross anyway takes an explicit exemption carrying its reason and what would remove it — written where the rule is, so it is a decision somebody can argue with rather than a reach nobody reads.

The EXP001 lint rule enforces this. It reads which modules are applications from the manifest — declaring a module kind: executable is what gives it a boundary, so a new application arrives with one — and it reads a dotted name passed to import_module as well as a static import, because that is where a reach hides from a reader grepping for imports.

The boundary is also what keeps an application repository’s internals free to move. Reached as a process or through one name, a module’s import surface no longer depends on what a consumer named the checkout directory, and internals can be reorganized without any consumer noticing.

Pairing rules

Compatibility

No compatibility shims unless explicitly directed. A name that has drifted is corrected immediately and every reference updated, and a mechanism whose upkeep exceeds its value is deleted rather than deprecated — Philosophy.md carries both as design discipline, and they are conventions here because a change that leaves a shim behind is not finished.