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
16 changes: 16 additions & 0 deletions LICENSE-TEMPLATES
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
MIT No Attribution

Copyright 2026 K. C. Ramakrishna

Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
7 changes: 4 additions & 3 deletions dev/build_skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
same ``metadata.version`` added.
- ``references/``: the state contract, the playbooks, the kickoff prompt, the shared prompt on how to talk to the
user (from ``audit/prompts/``), the check files, the stack profiles,
ADR 0003, the ADR policy and the ADR template, ``spec/command-surface.md`` and the spec decisions, the state schema and its docs, and the parts of
ADR 0003, the greenfield ADR policy and ADR template, ``spec/command-surface.md`` and the spec decisions, the state schema and its docs, and the parts of
the Tools CLI reference that cover the carried tools (:data:`TOOLS_CLI_SECTIONS`). The playbook templates
(:data:`IMPLEMENT_TEMPLATE_FILES`) sit beside the playbooks in ``references/playbooks/templates/``, so a playbook
step can copy one into the target.
Expand Down Expand Up @@ -336,8 +336,9 @@ def build_bundle(out_dir: Path) -> Path:
"implement/docs/architecture/adrs/0003-push-and-pr-policy.md",
"references/adrs/0003-push-and-pr-policy.md",
),
("docs/ADR_POLICY.md", "references/adr-policy/ADR_POLICY.md"),
("docs/templates/adr-template.md", "references/adr-policy/adr-template.md"),
# The greenfield copies (MIT-0), the ones `establish-docs-contract` adapts into a target, not `docs/` (GFDL).
("greenfield/templates/docs/ADR_POLICY.md", "references/adr-policy/ADR_POLICY.md"),
("greenfield/templates/docs/templates/adr-template.md", "references/adr-policy/adr-template.md"),
("spec/command-surface.md", "references/spec/command-surface.md"),
("spec/decisions/0001-constraint-artifact.md", "references/spec/decisions/0001-constraint-artifact.md"),
("spec/decisions/0002-lint-in-the-gate.md", "references/spec/decisions/0002-lint-in-the-gate.md"),
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/implement-master.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@

### `define-command-surface`

The repository exposes the seven verbs of [`spec/command-surface.md`](../../spec/command-surface.md) on one

Check notice on line 48 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 37 words (limit 25)
authoritative runner per component, `check` composes `format:check`, `typecheck` and `test` in that order, any
second runner only delegates, and no read-only verb writes to the working tree.

Expand All @@ -71,7 +71,7 @@

### `configure-quality-tools`

The repository has a formatter, a linter, a type checker in its strictest practical mode and a dependency

Check warning on line 74 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 47 words (limit 25)
scan, each configured in a committed file and reachable through its verb, adopted so that today's code keeps
`check` green and existing debt is counted, recorded and cannot grow.

Expand All @@ -97,7 +97,7 @@

### `pin-execution-environment`

Every run of the repository gets the same toolchain and the same dependency versions: each ecosystem has a

Check warning on line 100 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 61 words (limit 25)
committed pin (JDK, Node, package manager), each component has a tracked lockfile that matches its manifest, the
pins in CI, Dockerfiles and version files agree with each other, and every tool version the gate runs sits in a
manifest that dependency automation reads.
Expand All @@ -111,7 +111,7 @@

**What it never does:**

- Do not choose a runtime major for the owner, and do not move a major in this theme without the owner's

Check notice on line 114 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 28 words (limit 25)
decision and a green build on it.
- Do not hand-edit a lockfile or regenerate one that already passes.
- Do not run `npm install`, `npm update` or `./gradlew dependencies --update-locks` to "refresh" while
Expand All @@ -126,7 +126,7 @@

### `untrack-generated`

No build output is tracked in the repository, or the output that has to stay tracked says so in its first

Check notice on line 129 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 35 words (limit 25)
lines, and every concern (lint, format, test, types, security) has one authoritative root config.

| Check | What the playbook does |
Expand All @@ -150,7 +150,7 @@

### `env-inventory-and-secrets`

An agent can list every variable a script, build or application reads without seeing one value: a committed

Check warning on line 153 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 47 words (limit 25)
example file declares the names (required or optional), no secret-bearing file is tracked without a recorded
owner decision, and the ignore rules cover every secret shape the audit probes.

Expand All @@ -163,7 +163,7 @@

**What it never does:**

- Do not print, quote, log or copy a value from any env, properties, realm, keystore or credentials file, and

Check notice on line 166 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 26 words (limit 25)
do not open a `.env`-like file.
- Do not rotate a credential, remove one from history or run a history-rewriting command: report and stop.
- Do not touch a tracked env file the owner keeps; do not add an ignore rule or `git rm --cached` for it.
Expand All @@ -179,7 +179,7 @@

### `add-ci-parity`

The gate an agent runs locally is the gate CI runs. CI calls the same verbs (`check`, and `security` where it

Check warning on line 182 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 47 words (limit 25)
exists), every scan or test step either blocks the merge or says in its name that it is report-only with its debt
recorded, and a committed record shows which CI job the platform requires before a merge.

Expand All @@ -196,7 +196,7 @@
- Do not add a third-party `uses:` action without owner approval; do not install a scanner the owner has not
approved.
- Do not rename the merge-gate job, drop a job from its `needs`, or lower a gate that already blocks.
- Do not leave a green no-op (a step that prints "skipped" and exits 0), and do not hide debt: a non-blocking

Check notice on line 199 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 27 words (limit 25)
step says so in its name.
- Do not claim a required check exists without the owner-supplied evidence; do not mark CI-04 `done` where the
platform cannot enforce it.
Expand All @@ -207,7 +207,7 @@

### `add-hooks-and-commit-rules`

A commit runs a fast local hook chain before it is created, with one committed configuration and a documented

Check notice on line 210 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 32 words (limit 25)

Check notice on line 210 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 35 words (limit 25)
one-time install. The commit-message convention runs in two places with one type list: a local `commit-msg` stage,
so an agent learns of a bad subject before it pushes, and a CI step, which no `--no-verify` can skip. The owner may
instead record the pull-request title check as enough. A guard in the same chain refuses a commit on a protected
Expand All @@ -234,7 +234,7 @@

### `add-baselines-and-ratchet`

Every kind of existing debt the repository carries is counted, committed as a baseline, and guarded inside the gate

Check warning on line 237 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 64 words (limit 25)
so the count can only go down; the test suite's coverage is measured and held by a floor that can only go up; and
the suite's status and its skip markers are recorded, so an agent can tell old debt from the debt it adds.

Expand Down Expand Up @@ -268,7 +268,7 @@

### `establish-docs-contract`

An agent finds permanent knowledge in one place: `docs/` has an index, a short style guide that the instruction

Check warning on line 271 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 43 words (limit 25)
file names, a decision log with a policy, a template and an index, and a short architecture page with a diagram that was
checked. Scratch work stays out of version control. Structural traps (very large files, binaries) are listed,
not moved.
Expand All @@ -279,7 +279,7 @@
| [`DOC-02` docs/STYLE_GUIDE.md exists](audit-master.md#doc-02-docsstyle_guidemd-exists) | Adds a one-page `docs/STYLE_GUIDE.md` and one line in the instruction file that names it |
| [`DOC-03` artefacts/ exists and is ignored](audit-master.md#doc-03-artefacts-exists-and-is-ignored) | Verifies the scratch directory rule; adds the ignore rule only if a scratch directory exists |
| [`DOC-04` ADR directory and index](audit-master.md#doc-04-adr-directory-and-index) | Adds `docs/adr/` with an ADR policy page, a template, an index and two or three first records for the owner to review |
| [`DOC-05` Docs are readable](audit-master.md#doc-05-docs-are-readable) | Adds a "Plain language" and a "Diagrams" section to the style guide (Steps 3); the pages this theme writes pass the rules. Existing pages are not rewritten. A prose check with a ratchet only when the owner names a licence for it (Inputs 6, Steps 8). Trigger: a confirmed finding, or `extra.doc-05` (Preconditions) |
| [`DOC-05` Docs are readable](audit-master.md#doc-05-docs-are-readable) | Adds a "Plain language" and a "Diagrams" section to the style guide (Steps 3); the pages this theme writes pass the rules. Existing pages are not rewritten. A prose check with a ratchet only when the owner picks one of three permissive licences for it (Inputs 6, Steps 8). Trigger: a confirmed finding, or `extra.doc-05` (Preconditions) |
| [`NAV-01` Declared component boundaries](audit-master.md#nav-01-declared-component-boundaries) | Verification only: lists the declared components in the architecture page |
| [`NAV-02` Obvious entry points](audit-master.md#nav-02-obvious-entry-points) | Verification only: names the entry points in the architecture page |
| [`NAV-03` Structural red flags](audit-master.md#nav-03-structural-red-flags) | Census of oversized files, catch-all directories, binaries and minified assets; document, never move |
Expand All @@ -290,7 +290,7 @@

- Do not mass-reformat or mass-fix existing Markdown, and do not turn off a lint rule to make a count fall.
- Do not create a second `docs/` or restructure the existing report folders.
- Do not copy content, paths, names or values from a private repository or workspace into an open-source

Check notice on line 293 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 29 words (limit 25)
repository's docs or ADRs, or from any target repository into the framework.
- Do not invent the reason behind a decision. Say what is inferred, or write "Rationale not recorded; owner to
fill in".
Expand All @@ -311,7 +311,7 @@

### `adapt-agents-md`

The canonical instruction file states this repository's own facts, and only those: the seven verbs as the team runs

Check warning on line 314 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 58 words (limit 25)
them, a single-test command, where documentation lives, when docs change with code, which paths are boundaries,
what an agent may do with branches and releases, which harnesses read the file, and nothing an agent could infer
from the code. Every line is true against the repository, and the file stays within the 400-line budget.
Expand Down Expand Up @@ -345,7 +345,7 @@
- Do not edit the prohibitions section; that is [`add-deny-rules`](../../implement/playbooks/add-deny-rules.md).
- Do not edit code to make a rule true, and do not drop a rule because the code breaks it.
- Do not create a harness configuration file to point at a second rules file.
- Do not write a fact an earlier theme has not made true (a verb that does not resolve, a docs page that does not

Check warning on line 348 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 41 words (limit 25)
exist), and do not name a harness in the reach line that does not load the file.
- Do not add generic prose, role-play persona text or an overview to fill a section. The reader persona of the
AGT-12 section is not generic text.
Expand All @@ -356,7 +356,7 @@

### `add-deny-rules`

The instruction file has one prohibitions section, under a heading that says so, with an explicit rule for each of

Check notice on line 359 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 32 words (limit 25)
the four concerns (tests, generated files and scratch, the default branch, secrets). Every test directory is named
in a code span, so an agent cannot "fix" a failing test by editing it. Scratch and tool-state directories are
ignored and untracked. The owner has a report of what each harness configuration in the repository lets an agent
Expand All @@ -379,7 +379,7 @@
- Do not write a flat ban on test directories; the rule is bounded.
- Do not edit, create or delete a harness permission file unless the owner recorded `agents_md.harness_deny=yes`,
and never create one.
- Do not untrack, ignore or delete a file the owner has not confirmed is scratch, and do not change which env files

Check notice on line 382 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 29 words (limit 25)
are tracked; state the owner's decision instead.
- Do not paste the CON-04 draft whole: an entry that matches nothing in the repository is noise.
- Do not open, print or quote a secret store while listing the paths.
Expand All @@ -390,7 +390,7 @@

### `add-repo-hygiene`

The repository tells a newcomer, human or agent, who owns what (CODEOWNERS), how to contribute (README,

Check warning on line 393 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 60 words (limit 25)
CONTRIBUTING, pull-request and issue templates), how to report a vulnerability (SECURITY), how releases happen
(a release-process page and, where the release tool writes one, the changelog), and where the rules for merging
live (the rules as code, and a branch-protection page that summarises them). Each file is small, true against the
Expand Down Expand Up @@ -433,7 +433,7 @@

### `register-index`

An agent that opens the repository can reach the code index without being told how: the index server is registered

Check warning on line 436 in docs/reference/implement-master.md

View workflow job for this annotation

GitHub Actions / docs

PL001

sentence has 42 words (limit 25)
where the harness the team uses reads it, an index exists for this checkout, and the repository says when to refresh
it. An audit run on any machine reaches the same verdict, because the registration an audit relies on is committed,
not left in one developer's home directory.
Expand Down
11 changes: 9 additions & 2 deletions docs/reference/licensing.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,20 @@
|---|---|
| Scripts and code: `audit/tools/`, `implement/tools/`, the playbook templates in `implement/playbooks/templates/` (a copy in a target carries `MIT`, `Apache-2.0` or `BSD-3-Clause`, as its owner picks, and keeps the copyright line), the engine code in `audit/engine/` (the `audit/` package, its tests and `build.py`), the dev-only checks and build tools in `dev/`, and their tests | AGPL-3.0-or-later |
| Documentation: this `docs/` tree, the engine's docs (`audit/engine/docs/`, its README and `AGENTS.md`), recipes, check files, playbooks, stack profiles, the check catalogue (`catalogue.json`) | GFDL 1.3 |
| Templates: `greenfield/templates/`, and the text an implement playbook copies or adapts from them into a target repository. A copy needs no notice | MIT-0 |
| JSON Schemas (`audit/schema/`) and their documentation | GFDL 1.3 |
| Example reports and other outputs published in this repository, including `audit/engine/examples/` | GFDL 1.3 |

The licence texts are root files: `LICENSE` holds the GFDL 1.3 text and `LICENSE-CODE` holds the AGPL text. Each skill
The licence texts are root files: `LICENSE` holds the GFDL 1.3 text, `LICENSE-CODE` holds the AGPL text and
`LICENSE-TEMPLATES` holds the MIT-0 text. Each skill
bundle that `dev/build_skills.py` builds carries a `LICENSE` file with the AGPL text.

SPDX identifiers: `AGPL-3.0-or-later` for code and `GFDL-1.3-only` for documentation, schemas and published outputs.
SPDX identifiers: `AGPL-3.0-or-later` for code, `MIT-0` for templates, and `GFDL-1.3-only` for documentation,
schemas and published outputs.

The templates are MIT-0 so that text copied into a repository, private and enterprise ones included, carries no
copyleft and no notice duty. The repository then owns its copy. For the same reason a playbook copies or adapts
text only from `greenfield/templates/`, never from this repository's `docs/`.

> [!NOTE]
> The AGPL covers the tools, not the repositories they analyse. Reports that you produce on your own repositories are yours; the tools place no licence on them. Outputs this project publishes as examples are GFDL 1.3.
5 changes: 5 additions & 0 deletions greenfield/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@

---

The files in `templates/` are MIT-0 ([`LICENSE-TEMPLATES`](../LICENSE-TEMPLATES)): copy and change them freely,
with no notice. Your project then owns its copy and picks its own licence.

---

## File Tree — What Gets Created

```
Expand Down
1 change: 1 addition & 0 deletions implement/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ folder.
## Rules

- Use the standard library only in `tools/`. Never add a third-party import.
- Text a playbook copies into a target comes from `greenfield/templates/` (MIT-0), never from `docs/` (GFDL 1.3).
- Code in `playbooks/templates/` is relicensed when a playbook copies it into a target. Only its copyright holder
changes it, or a contributor who agrees in writing to that relicensing. Say so in the pull request.
- Every tool follows the tool contract in [`audit/tools/README.md`](../audit/tools/README.md).
Expand Down
2 changes: 2 additions & 0 deletions implement/playbooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ Rules for every playbook:
- A playbook never restates a check's rubric or a requirement; it links to the check file in
[`audit/checks/`](../../audit/checks/README.md) and to `spec/`.
- Templates come from `greenfield/templates/` by reference, never copied verbatim into the playbook.
- Text a playbook copies or adapts into a target comes only from `greenfield/templates/` (MIT-0), never from
this repository's `docs/` (GFDL 1.3). See [licensing](../../docs/reference/licensing.md).
- Code a playbook copies into a target lives in [`templates/`](templates/), with its tests in
`implement/tools/tests/`. A copy carries `MIT`, `Apache-2.0` or `BSD-3-Clause`, as the owner picks, never this repository's.
- A playbook does not restate the shared procedure of `SKILL.md` Stages 2 to 4; it links to the stage step.
Expand Down
13 changes: 7 additions & 6 deletions implement/playbooks/establish-docs-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ not moved.
| DOC-02 | [03-documentation-contract.md](../../audit/checks/03-documentation-contract.md#doc-02--docsstyle_guidemd-exists) | Adds a one-page `docs/STYLE_GUIDE.md` and one line in the instruction file that names it |
| DOC-03 | [03-documentation-contract.md](../../audit/checks/03-documentation-contract.md#doc-03--artefacts-exists-and-is-ignored) | Verifies the scratch directory rule; adds the ignore rule only if a scratch directory exists |
| DOC-04 | [03-documentation-contract.md](../../audit/checks/03-documentation-contract.md#doc-04--adr-directory-and-index) | Adds `docs/adr/` with an ADR policy page, a template, an index and two or three first records for the owner to review |
| DOC-05 | [03-documentation-contract.md](../../audit/checks/03-documentation-contract.md#doc-05--docs-are-readable) | Adds a "Plain language" and a "Diagrams" section to the style guide (Steps 3); the pages this theme writes pass the rules. Existing pages are not rewritten. A prose check with a ratchet only when the owner names a licence for it (Inputs 6, Steps 8). Trigger: a confirmed finding, or `extra.doc-05` (Preconditions) |
| DOC-05 | [03-documentation-contract.md](../../audit/checks/03-documentation-contract.md#doc-05--docs-are-readable) | Adds a "Plain language" and a "Diagrams" section to the style guide (Steps 3); the pages this theme writes pass the rules. Existing pages are not rewritten. A prose check with a ratchet only when the owner picks one of three permissive licences for it (Inputs 6, Steps 8). Trigger: a confirmed finding, or `extra.doc-05` (Preconditions) |
| NAV-01 | [11-navigation.md](../../audit/checks/11-navigation.md#nav-01--declared-component-boundaries) | Verification only: lists the declared components in the architecture page |
| NAV-02 | [11-navigation.md](../../audit/checks/11-navigation.md#nav-02--obvious-entry-points) | Verification only: names the entry points in the architecture page |
| NAV-03 | [11-navigation.md](../../audit/checks/11-navigation.md#nav-03--structural-red-flags) | Census of oversized files, catch-all directories, binaries and minified assets; document, never move |
Expand Down Expand Up @@ -71,8 +71,8 @@ They stay here so a repository that has one has a procedure, and so the re-audit
> rather than implementing it. See the owner-facing comparison in the track research note
> (`node-vs-java-docs-lint`, not part of the recipe). An owner who asks "why not Java" gets this answer; the
> docs job stays separate from the build, so the build toolchain is unchanged.
2. **Style guide source.** Default: adapt the framework's
[`docs/STYLE_GUIDE.md`](../../docs/STYLE_GUIDE.md) (Diátaxis) to one page. The alternative
2. **Style guide source.** Default: adapt the greenfield
[`docs/STYLE_GUIDE.md`](../../greenfield/templates/docs/STYLE_GUIDE.md) (Diátaxis) to one page. The alternative
(the owner's own house rules) is allowed only when those rules are not private to a different repository.
Either way, the guide gains the "Plain language" and "Diagrams" sections (Steps 3) when DOC-05 is in the theme.
3. **First ADRs.** Ask which two or three existing decisions to record. With no owner preference, pick them
Expand Down Expand Up @@ -135,10 +135,11 @@ They stay here so a repository that has one has a procedure, and so the re-audit
the architecture page. Re-run the engine before the theme closes: `DOC-05` cites no line on those pages.
4. **ADRs (DOC-04).** Create `docs/adr/` with four parts:
- `README.md`, the index: a table of number, title and a one-line summary, linking every file by its path.
- `0000-template.md`, copied from the framework's [`adr-template.md`](../../docs/templates/adr-template.md):
- `0000-template.md`, copied from the greenfield
[`adr-template.md`](../../greenfield/templates/docs/templates/adr-template.md):
Context, Decision, Alternatives Considered, Consequences. It has no status, date or decider fields.
- An ADR policy page, adapted from the framework's [`ADR_POLICY.md`](../../docs/ADR_POLICY.md). Keep its
rules; replace the framework's folder list and links with the target's. Name the page to fit the target's
- An ADR policy page, adapted from the greenfield [`ADR_POLICY.md`](../../greenfield/templates/docs/ADR_POLICY.md).
Keep its rules; replace its folder list and links with the target's. Name the page to fit the target's
file names: `docs/ADR_POLICY.md` beside `docs/STYLE_GUIDE.md` by default, or `docs/adr-policy.md` where
the docs use lower-case names. The instruction-file line names it (Inputs 5).
- The first records, as `0001-short-title.md`.
Expand Down
Loading