aisignoff 0.4.0__tar.gz

aisignoff-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pascal Jung
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

aisignoff-0.4.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: aisignoff
+Version: 0.4.0
+Summary: Sign off on AI use per file: declare and check AI generation (G0-G3), human review (H0-H3) and AI review (A0-A3), REUSE-style.
+Author: Industrial Mathematics Group
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/industrial-mathematics-group/aisignoff
+Project-URL: Issues, https://github.com/industrial-mathematics-group/aisignoff/issues
+Keywords: ai,declaration,provenance,code review,research software,reuse
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# aisignoff
+
+[![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-generation.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#g-generation)
+[![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-human-review.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#h-human-review)
+[![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-review.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#a-ai-review)
+
+![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-generation.json)
+![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-human-review.json)
+![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-ai-review.json)
+
+**Declare and check how each file was created and reviewed**, using the Industrial Mathematics Group's AI levels:
+- **G0–G3:** how much an AI generated;
+- **H0–H3:** how thoroughly a human reviewed it;
+- **A0–A3:** how thoroughly an AI reviewed it.
+
+The name is meant both ways: the AI signs off on what it generated or reviewed, and so does the human ("ai", said in German, sounds like "I"). It's a declaration you sign off on, not a cryptographic signature.
+
+It works like [REUSE](https://reuse.software) does for licences: a path-based `SIGNOFF.toml`, optional tags in file headers, and a `lint` command for CI.
+
+It complements the declaration in pull requests, where the levels are ticked in the PR template:
+
+| | PR declaration | `SIGNOFF.toml` |
+|---|---|---|
+| Describes | each **change** merged into `main` | the **current state** of every file |
+| Good for | code developed through pull requests | results, data, notebooks, papers, single-commit uploads |
+| Checked by | the *AI declaration* PR check | `aisignoff lint` |
+
+The keys of `SIGNOFF.toml` and the inline tags are the same ones the PR check shows in its job summary.
+
+The levels are defined in the [AI policy](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#ai-assisted-contributions):
+
+| Generation | | Human review | | AI review | |
+|---|---|---|---|---|---|
+| **G0** | Human | **H0** | Plausibility check | **A0** | None |
+| **G1** | AI-assisted | **H1** | Tested | **A1** | Self-check by the generating session |
+| **G2** | AI-generated | **H2** | Reviewed line by line | **A2** | Review by a new session |
+| **G3** | AI-autonomous | **H3** | Independently validated | **A3** | Extensive review or benchmark by a different model |
+
+For human-written content (G0) there is no generating session, so it can't have A1: any AI review of it is A2 or A3.
+
+## Install
+
+```bash
+pip install aisignoff
+# or, without touching your environment:
+pipx install aisignoff      # or: uv tool install aisignoff
+```
+
+The latest development version: `pip install "aisignoff @ git+https://github.com/industrial-mathematics-group/aisignoff"`.
+
+Requires Python 3.11 or newer; no other dependencies.
+
+## Quick start
+
+```bash
+# 1. A default for everything (here: written by a human, reviewed line by line, no AI review)
+aisignoff init -g G0 -H H2 -a A0 --reviewed-by "Jane Doe"
+
+# 2. Declare what is different, by file, folder or glob
+aisignoff annotate results/ -g G2 -H H1 -a A1 \
+    --assisted-by "Claude Opus 5.5 (Anthropic)" \
+    --ai-reviewed-by "Claude Opus 5.5 (Anthropic), same session" --reviewed-by "Jane Doe"
+aisignoff annotate "scripts/*.jl" -g G1 -H H3 -a A2 --assisted-by "GitHub Copilot" \
+    --ai-reviewed-by "Claude Opus 5.5 (Anthropic), new session" --reviewed-by "Jane Doe"
+
+# 3. Check that every file is declared correctly
+aisignoff lint
+```
+
+`annotate` refuses incomplete declarations, and anything below the repository's policy (e.g. G2 without `--assisted-by`, or G2 with `-a A0`). It also checks that the resulting `SIGNOFF.toml` is still valid, and leaves it unchanged if not. Paths are handled like this:
+- **Inside the project root:** files outside `--root` are refused, also with `--inline`.
+- **Files and folders:** existing files are matched exactly, even with `*` or `?` in their name, and a folder becomes `folder/**`.
+- **Globs:** quote them, e.g. `"scripts/*.jl"`. Inside the project they're read relative to the current directory, as the shell would; with `--root` from outside, relative to the root. Globs with `..` or absolute paths are refused.
+
+## SIGNOFF.toml
+
+```toml
+version = 3
+exclude = ["reviews/**", "docs/build/**"]   # optional: files that need no declaration
+
+[policy]                                 # optional: minimum levels
+"*" = { human = "H1" }
+G3  = { human = "H2", ai = "A2" }
+
+[[annotations]]
+path = "**"
+AI-Generation = "G0"
+Human-Review = "H2"
+AI-Review = "A0"
+Reviewed-by = "Jane Doe"
+
+[[annotations]]
+path = ["results/**", "figures/*.pdf"]
+AI-Generation = "G2"
+Human-Review = "H3"
+AI-Review = "A3"
+Assisted-by = ["Claude Opus 5.5 (Anthropic)"]
+AI-Reviewed-by = "GPT-5 (OpenAI), full benchmark against reference solutions"
+Reviewed-by = "Jane Doe"
+```
+
+- **`path`**: one glob or a list, relative to the repository root.
+  - `*` stays within a folder, `**` crosses folders (`**/` also matches no folder), and `?` is one character.
+  - `\*`, `\?` and `\\` match those characters literally.
+  - This is modelled on `REUSE.toml`, plus `?`.
+- **The last matching annotation wins**, so put the general default first and the exceptions after it.
+- **Keys:** the levels and the names below. `Assisted-by`, `AI-Reviewed-by` and `Reviewed-by` take a string or a list.
+- **Every file needs a valid declaration:**
+
+| Key | Required for |
+|---|---|
+| `AI-Generation`, `Human-Review`, `AI-Review` | every file |
+| `Reviewed-by` (the responsible human) | every file |
+| `Assisted-by` | G1–G3; not allowed for G0 |
+| `AI-Reviewed-by` | A1–A3; not allowed for A0 |
+
+- **Placeholders:** any value may be `"TODO"`, e.g. `Human-Review = "TODO"` when an agent declares its part and a person adds the human review later. `annotate` accepts it too: `-H TODO` without `--reviewed-by` also writes `Reviewed-by` as TODO, so the person fills in both together. It still checks the axes that are filled in. `lint` reports every TODO until it's filled in.
+- **Minimum levels:** G1–G3 always need at least **A1**: AI-written content must at least be self-checked. The `[policy]` table can require more (for G0, a minimum of A1 means A2):
+  - `"*"` sets the default for every generation level;
+  - `G0`–`G3` refine it per generation level, overriding the `"*"` values key by key.
+- **Which files are checked:**
+  - **In a git repository:** all tracked files plus untracked files that aren't ignored, so `.gitignore` is respected. If git can't be run there, aisignoff stops with an error rather than ignoring `.gitignore`.
+  - **Outside git:** every file below the root.
+  - **Always skipped:** `SIGNOFF.toml` itself (and `AIDECL.toml`, its old name) and anything under `exclude`. Exclude the folder of committed AI reviews (`reviews/` by default, see CONTRIBUTING.md), since the reviews themselves need no declaration.
+
+## Inline tags
+
+Source files and documents can also carry the declaration in a comment within their first 30 lines:
+
+```julia
+# AI-Generation: G2
+# Human-Review: H2
+# AI-Review: A2
+# Assisted-by: Claude Opus 5.5 (Anthropic)
+# AI-Reviewed-by: Claude Opus 5.5 (Anthropic), fresh review session
+# Reviewed-by: Jane Doe
+```
+
+Three rules keep documentation from being mistaken for a declaration:
+
+- **The file type's own comment syntax:**
+  - `#` in Julia, Python or YAML;
+  - `//` or `/* */` in C-like languages;
+  - `%` in LaTeX;
+  - `<!-- -->` in Markdown and HTML.
+
+  Fenced code blocks in Markdown are skipped. File types without a known comment syntax, such as `.txt`, `.csv`, `.json`, notebooks or `LICENSE`, are only declared through `SIGNOFF.toml`.
+- **Start of the line:** the comment must start the line. Only `*` continuation lines of a `/* */` comment may be indented, so indented examples in docstrings are ignored.
+- **A contiguous block with a valid level:** tag lines count only as a block of adjacent lines that contains a valid level line, such as `AI-Generation: G2` or `AI-Review: A0`. A comment that merely explains the keys, like `#   AI-Generation: G0-G3`, is ignored. `TODO` (a placeholder, e.g. left by `aisignoff migrate` or an agent) also counts as a level here, so a block with an unfilled TODO is found and fails `lint`.
+
+`aisignoff annotate FILE … --inline` writes or updates these lines for you:
+- **Placement:** after a shebang, an encoding line, an XML declaration or (in Markdown) YAML front matter.
+- **The rest of the file stays untouched,** including line endings and a byte-order mark.
+- **Safety:** it refuses if the block wouldn't fit into the first 30 lines. It reads the result back and restores the file if the tags couldn't be read.
+
+**Precedence:** a file's inline tags win over `SIGNOFF.toml` ("closest"), unless the matching annotation sets `precedence = "override"`. This works per axis:
+- **The axes** are generation (`AI-Generation` with `Assisted-by`), human review (`Human-Review` with `Reviewed-by`) and AI review (`AI-Review` with `AI-Reviewed-by`).
+- **An axis counts as declared inline** when its level line is present. Any axis the inline block leaves out comes from the matching annotation.
+- **A name line on its own,** such as `Assisted-by` without `AI-Generation`, is an error.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `aisignoff init [-g G -H H -a A …]` | Create `SIGNOFF.toml`, optionally with a default for all files |
+| `aisignoff annotate PATHS -g G -H H -a A [--assisted-by …] [--ai-reviewed-by …] --reviewed-by …` | Append an annotation (`--inline`: tag the files themselves) |
+| `aisignoff lint [--strict]` | Fail if any file lacks a valid declaration, falls below the policy, or if no files were found (`--strict`: also on annotations that match nothing) |
+| `aisignoff report [--files] [--json]` | Summary per axis, one line per file (with the problems), or JSON; invalid declarations count as "undeclared", as in the badges |
+| `aisignoff badge [--out DIR] [--weight files\|lines]` | Write shields.io badges `aisignoff-generation.json`, `aisignoff-human-review.json` and `aisignoff-ai-review.json` |
+| `aisignoff migrate [--dry-run] [--from 2]` | Convert declarations of earlier versions, see below |
+
+Use `--root DIR` before the command to run on another directory, e.g. `aisignoff --root ../paper lint`.
+
+Exit codes: `0` success, `1` problems found by `lint`, `2` usage or configuration errors.
+
+## Migrating from earlier versions
+
+**From aidecl** (up to version 0.3.0). The tool, its command and its file were renamed: `aidecl` is now `aisignoff`, and `AIDECL.toml` is now `SIGNOFF.toml`. The keys, levels and inline tags stay the same.
+- **Reinstall:** `pipx uninstall aidecl && pipx install aisignoff` (or the same with pip).
+- **Rename the file:** `aisignoff migrate` renames `AIDECL.toml` to `SIGNOFF.toml` and keeps its content. If the file still uses version 1 or 2, it's converted in the same step, as described below. Commit the rename (`git add -A SIGNOFF.toml AIDECL.toml`).
+- **Until then,** aisignoff still reads `AIDECL.toml` and prints a warning. Having both files is an error.
+- **Badges** are now called `aisignoff-generation.json`, `aisignoff-human-review.json` and `aisignoff-ai-review.json`; update the URLs in your README (see "In CI" below).
+
+**Between versions of the file format,** `aisignoff migrate` converts `SIGNOFF.toml` and the inline tags to version 3, all or nothing. Without `SIGNOFF.toml`, inline tags with the old AI review scale need `--from 2`; `migrate` points this out when it finds `AI-Review: A-`. `--from 2` then creates a version-3 `SIGNOFF.toml` without annotations, which records that the tags are converted, so they're never shifted twice. Once `SIGNOFF.toml` is version 3, `--from 2` is refused.
+
+**From version 2** (AI review A-, A0–A3). The scale moved up by one, so only `AI-Review` (and `ai` in `[policy]`) changes. Comments and layout of `SIGNOFF.toml` are kept.
+
+| Old | New |
+|---|---|
+| A- (none) | A0 |
+| A0 (self-check) | A1; for G0 a TODO, since human-written content has no self-check |
+| A1 (independent session) | A2 |
+| A2 (different model) | A2, with a note: raise it to A3 if the review was extensive or benchmarked |
+| A3 (different model with benchmark) | A3 |
+
+**From version 1** (one verification axis, V0–V3):
+
+| Old | New |
+|---|---|
+| V0 (human, line by line) | H2, and A0 for G0 |
+| V1 / V2 (independent agent, same / different model) | A2 |
+| V3 (human + independent agent) | H2 + A2 |
+| `Tested-by` | `Reviewed-by` |
+| `Verified-by` | `AI-Reviewed-by` |
+
+What the old levels don't say must be added by a person. Examples are the human review of a V1 file, or the AI review of an AI-written V0 file. `migrate` marks these with a `TODO` comment in `SIGNOFF.toml` and with a `TODO` value in inline tags (e.g. `# Human-Review: TODO`), and `lint` reports them until they're filled in. When converting version 1, comments in `SIGNOFF.toml` are not carried over.
+
+## In CI
+
+The organisation provides a ready-made workflow (*Actions → New workflow → AI file declarations*). It runs `aisignoff lint` on every push and pull request and publishes the badges to the `badges` branch:
+
+```markdown
+![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-generation.json)
+![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-human-review.json)
+![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-ai-review.json)
+```
+
+The badges turn red and show an "undeclared" share while files are missing a valid declaration.
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest
+aisignoff lint      # the tool declares its own files, too (see SIGNOFF.toml)
+```
+
+**Releasing:** bump `version` in `pyproject.toml`, `src/aisignoff/__init__.py` and `uv.lock`, then publish a GitHub release with the tag `vX.Y.Z`. The *Publish to PyPI* workflow builds the package and uploads it through PyPI's trusted publishing, so no token is stored in the repository.

aisignoff-0.4.0/README.md

@@ -0,0 +1,228 @@
+# aisignoff
+
+[![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-generation.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#g-generation)
+[![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-human-review.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#h-human-review)
+[![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/ai-review.json)](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#a-ai-review)
+
+![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-generation.json)
+![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-human-review.json)
+![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/aisignoff/badges/aisignoff-ai-review.json)
+
+**Declare and check how each file was created and reviewed**, using the Industrial Mathematics Group's AI levels:
+- **G0–G3:** how much an AI generated;
+- **H0–H3:** how thoroughly a human reviewed it;
+- **A0–A3:** how thoroughly an AI reviewed it.
+
+The name is meant both ways: the AI signs off on what it generated or reviewed, and so does the human ("ai", said in German, sounds like "I"). It's a declaration you sign off on, not a cryptographic signature.
+
+It works like [REUSE](https://reuse.software) does for licences: a path-based `SIGNOFF.toml`, optional tags in file headers, and a `lint` command for CI.
+
+It complements the declaration in pull requests, where the levels are ticked in the PR template:
+
+| | PR declaration | `SIGNOFF.toml` |
+|---|---|---|
+| Describes | each **change** merged into `main` | the **current state** of every file |
+| Good for | code developed through pull requests | results, data, notebooks, papers, single-commit uploads |
+| Checked by | the *AI declaration* PR check | `aisignoff lint` |
+
+The keys of `SIGNOFF.toml` and the inline tags are the same ones the PR check shows in its job summary.
+
+The levels are defined in the [AI policy](https://github.com/industrial-mathematics-group/.github/blob/main/.github/CONTRIBUTING.md#ai-assisted-contributions):
+
+| Generation | | Human review | | AI review | |
+|---|---|---|---|---|---|
+| **G0** | Human | **H0** | Plausibility check | **A0** | None |
+| **G1** | AI-assisted | **H1** | Tested | **A1** | Self-check by the generating session |
+| **G2** | AI-generated | **H2** | Reviewed line by line | **A2** | Review by a new session |
+| **G3** | AI-autonomous | **H3** | Independently validated | **A3** | Extensive review or benchmark by a different model |
+
+For human-written content (G0) there is no generating session, so it can't have A1: any AI review of it is A2 or A3.
+
+## Install
+
+```bash
+pip install aisignoff
+# or, without touching your environment:
+pipx install aisignoff      # or: uv tool install aisignoff
+```
+
+The latest development version: `pip install "aisignoff @ git+https://github.com/industrial-mathematics-group/aisignoff"`.
+
+Requires Python 3.11 or newer; no other dependencies.
+
+## Quick start
+
+```bash
+# 1. A default for everything (here: written by a human, reviewed line by line, no AI review)
+aisignoff init -g G0 -H H2 -a A0 --reviewed-by "Jane Doe"
+
+# 2. Declare what is different, by file, folder or glob
+aisignoff annotate results/ -g G2 -H H1 -a A1 \
+    --assisted-by "Claude Opus 5.5 (Anthropic)" \
+    --ai-reviewed-by "Claude Opus 5.5 (Anthropic), same session" --reviewed-by "Jane Doe"
+aisignoff annotate "scripts/*.jl" -g G1 -H H3 -a A2 --assisted-by "GitHub Copilot" \
+    --ai-reviewed-by "Claude Opus 5.5 (Anthropic), new session" --reviewed-by "Jane Doe"
+
+# 3. Check that every file is declared correctly
+aisignoff lint
+```
+
+`annotate` refuses incomplete declarations, and anything below the repository's policy (e.g. G2 without `--assisted-by`, or G2 with `-a A0`). It also checks that the resulting `SIGNOFF.toml` is still valid, and leaves it unchanged if not. Paths are handled like this:
+- **Inside the project root:** files outside `--root` are refused, also with `--inline`.
+- **Files and folders:** existing files are matched exactly, even with `*` or `?` in their name, and a folder becomes `folder/**`.
+- **Globs:** quote them, e.g. `"scripts/*.jl"`. Inside the project they're read relative to the current directory, as the shell would; with `--root` from outside, relative to the root. Globs with `..` or absolute paths are refused.
+
+## SIGNOFF.toml
+
+```toml
+version = 3
+exclude = ["reviews/**", "docs/build/**"]   # optional: files that need no declaration
+
+[policy]                                 # optional: minimum levels
+"*" = { human = "H1" }
+G3  = { human = "H2", ai = "A2" }
+
+[[annotations]]
+path = "**"
+AI-Generation = "G0"
+Human-Review = "H2"
+AI-Review = "A0"
+Reviewed-by = "Jane Doe"
+
+[[annotations]]
+path = ["results/**", "figures/*.pdf"]
+AI-Generation = "G2"
+Human-Review = "H3"
+AI-Review = "A3"
+Assisted-by = ["Claude Opus 5.5 (Anthropic)"]
+AI-Reviewed-by = "GPT-5 (OpenAI), full benchmark against reference solutions"
+Reviewed-by = "Jane Doe"
+```
+
+- **`path`**: one glob or a list, relative to the repository root.
+  - `*` stays within a folder, `**` crosses folders (`**/` also matches no folder), and `?` is one character.
+  - `\*`, `\?` and `\\` match those characters literally.
+  - This is modelled on `REUSE.toml`, plus `?`.
+- **The last matching annotation wins**, so put the general default first and the exceptions after it.
+- **Keys:** the levels and the names below. `Assisted-by`, `AI-Reviewed-by` and `Reviewed-by` take a string or a list.
+- **Every file needs a valid declaration:**
+
+| Key | Required for |
+|---|---|
+| `AI-Generation`, `Human-Review`, `AI-Review` | every file |
+| `Reviewed-by` (the responsible human) | every file |
+| `Assisted-by` | G1–G3; not allowed for G0 |
+| `AI-Reviewed-by` | A1–A3; not allowed for A0 |
+
+- **Placeholders:** any value may be `"TODO"`, e.g. `Human-Review = "TODO"` when an agent declares its part and a person adds the human review later. `annotate` accepts it too: `-H TODO` without `--reviewed-by` also writes `Reviewed-by` as TODO, so the person fills in both together. It still checks the axes that are filled in. `lint` reports every TODO until it's filled in.
+- **Minimum levels:** G1–G3 always need at least **A1**: AI-written content must at least be self-checked. The `[policy]` table can require more (for G0, a minimum of A1 means A2):
+  - `"*"` sets the default for every generation level;
+  - `G0`–`G3` refine it per generation level, overriding the `"*"` values key by key.
+- **Which files are checked:**
+  - **In a git repository:** all tracked files plus untracked files that aren't ignored, so `.gitignore` is respected. If git can't be run there, aisignoff stops with an error rather than ignoring `.gitignore`.
+  - **Outside git:** every file below the root.
+  - **Always skipped:** `SIGNOFF.toml` itself (and `AIDECL.toml`, its old name) and anything under `exclude`. Exclude the folder of committed AI reviews (`reviews/` by default, see CONTRIBUTING.md), since the reviews themselves need no declaration.
+
+## Inline tags
+
+Source files and documents can also carry the declaration in a comment within their first 30 lines:
+
+```julia
+# AI-Generation: G2
+# Human-Review: H2
+# AI-Review: A2
+# Assisted-by: Claude Opus 5.5 (Anthropic)
+# AI-Reviewed-by: Claude Opus 5.5 (Anthropic), fresh review session
+# Reviewed-by: Jane Doe
+```
+
+Three rules keep documentation from being mistaken for a declaration:
+
+- **The file type's own comment syntax:**
+  - `#` in Julia, Python or YAML;
+  - `//` or `/* */` in C-like languages;
+  - `%` in LaTeX;
+  - `<!-- -->` in Markdown and HTML.
+
+  Fenced code blocks in Markdown are skipped. File types without a known comment syntax, such as `.txt`, `.csv`, `.json`, notebooks or `LICENSE`, are only declared through `SIGNOFF.toml`.
+- **Start of the line:** the comment must start the line. Only `*` continuation lines of a `/* */` comment may be indented, so indented examples in docstrings are ignored.
+- **A contiguous block with a valid level:** tag lines count only as a block of adjacent lines that contains a valid level line, such as `AI-Generation: G2` or `AI-Review: A0`. A comment that merely explains the keys, like `#   AI-Generation: G0-G3`, is ignored. `TODO` (a placeholder, e.g. left by `aisignoff migrate` or an agent) also counts as a level here, so a block with an unfilled TODO is found and fails `lint`.
+
+`aisignoff annotate FILE … --inline` writes or updates these lines for you:
+- **Placement:** after a shebang, an encoding line, an XML declaration or (in Markdown) YAML front matter.
+- **The rest of the file stays untouched,** including line endings and a byte-order mark.
+- **Safety:** it refuses if the block wouldn't fit into the first 30 lines. It reads the result back and restores the file if the tags couldn't be read.
+
+**Precedence:** a file's inline tags win over `SIGNOFF.toml` ("closest"), unless the matching annotation sets `precedence = "override"`. This works per axis:
+- **The axes** are generation (`AI-Generation` with `Assisted-by`), human review (`Human-Review` with `Reviewed-by`) and AI review (`AI-Review` with `AI-Reviewed-by`).
+- **An axis counts as declared inline** when its level line is present. Any axis the inline block leaves out comes from the matching annotation.
+- **A name line on its own,** such as `Assisted-by` without `AI-Generation`, is an error.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `aisignoff init [-g G -H H -a A …]` | Create `SIGNOFF.toml`, optionally with a default for all files |
+| `aisignoff annotate PATHS -g G -H H -a A [--assisted-by …] [--ai-reviewed-by …] --reviewed-by …` | Append an annotation (`--inline`: tag the files themselves) |
+| `aisignoff lint [--strict]` | Fail if any file lacks a valid declaration, falls below the policy, or if no files were found (`--strict`: also on annotations that match nothing) |
+| `aisignoff report [--files] [--json]` | Summary per axis, one line per file (with the problems), or JSON; invalid declarations count as "undeclared", as in the badges |
+| `aisignoff badge [--out DIR] [--weight files\|lines]` | Write shields.io badges `aisignoff-generation.json`, `aisignoff-human-review.json` and `aisignoff-ai-review.json` |
+| `aisignoff migrate [--dry-run] [--from 2]` | Convert declarations of earlier versions, see below |
+
+Use `--root DIR` before the command to run on another directory, e.g. `aisignoff --root ../paper lint`.
+
+Exit codes: `0` success, `1` problems found by `lint`, `2` usage or configuration errors.
+
+## Migrating from earlier versions
+
+**From aidecl** (up to version 0.3.0). The tool, its command and its file were renamed: `aidecl` is now `aisignoff`, and `AIDECL.toml` is now `SIGNOFF.toml`. The keys, levels and inline tags stay the same.
+- **Reinstall:** `pipx uninstall aidecl && pipx install aisignoff` (or the same with pip).
+- **Rename the file:** `aisignoff migrate` renames `AIDECL.toml` to `SIGNOFF.toml` and keeps its content. If the file still uses version 1 or 2, it's converted in the same step, as described below. Commit the rename (`git add -A SIGNOFF.toml AIDECL.toml`).
+- **Until then,** aisignoff still reads `AIDECL.toml` and prints a warning. Having both files is an error.
+- **Badges** are now called `aisignoff-generation.json`, `aisignoff-human-review.json` and `aisignoff-ai-review.json`; update the URLs in your README (see "In CI" below).
+
+**Between versions of the file format,** `aisignoff migrate` converts `SIGNOFF.toml` and the inline tags to version 3, all or nothing. Without `SIGNOFF.toml`, inline tags with the old AI review scale need `--from 2`; `migrate` points this out when it finds `AI-Review: A-`. `--from 2` then creates a version-3 `SIGNOFF.toml` without annotations, which records that the tags are converted, so they're never shifted twice. Once `SIGNOFF.toml` is version 3, `--from 2` is refused.
+
+**From version 2** (AI review A-, A0–A3). The scale moved up by one, so only `AI-Review` (and `ai` in `[policy]`) changes. Comments and layout of `SIGNOFF.toml` are kept.
+
+| Old | New |
+|---|---|
+| A- (none) | A0 |
+| A0 (self-check) | A1; for G0 a TODO, since human-written content has no self-check |
+| A1 (independent session) | A2 |
+| A2 (different model) | A2, with a note: raise it to A3 if the review was extensive or benchmarked |
+| A3 (different model with benchmark) | A3 |
+
+**From version 1** (one verification axis, V0–V3):
+
+| Old | New |
+|---|---|
+| V0 (human, line by line) | H2, and A0 for G0 |
+| V1 / V2 (independent agent, same / different model) | A2 |
+| V3 (human + independent agent) | H2 + A2 |
+| `Tested-by` | `Reviewed-by` |
+| `Verified-by` | `AI-Reviewed-by` |
+
+What the old levels don't say must be added by a person. Examples are the human review of a V1 file, or the AI review of an AI-written V0 file. `migrate` marks these with a `TODO` comment in `SIGNOFF.toml` and with a `TODO` value in inline tags (e.g. `# Human-Review: TODO`), and `lint` reports them until they're filled in. When converting version 1, comments in `SIGNOFF.toml` are not carried over.
+
+## In CI
+
+The organisation provides a ready-made workflow (*Actions → New workflow → AI file declarations*). It runs `aisignoff lint` on every push and pull request and publishes the badges to the `badges` branch:
+
+```markdown
+![AI generation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-generation.json)
+![Human review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-human-review.json)
+![AI review](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/industrial-mathematics-group/<repo>/badges/aisignoff-ai-review.json)
+```
+
+The badges turn red and show an "undeclared" share while files are missing a valid declaration.
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest
+aisignoff lint      # the tool declares its own files, too (see SIGNOFF.toml)
+```
+
+**Releasing:** bump `version` in `pyproject.toml`, `src/aisignoff/__init__.py` and `uv.lock`, then publish a GitHub release with the tag `vX.Y.Z`. The *Publish to PyPI* workflow builds the package and uploads it through PyPI's trusted publishing, so no token is stored in the repository.

aisignoff-0.4.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aisignoff"
+version = "0.4.0"
+description = "Sign off on AI use per file: declare and check AI generation (G0-G3), human review (H0-H3) and AI review (A0-A3), REUSE-style."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Industrial Mathematics Group" }]
+keywords = ["ai", "declaration", "provenance", "code review", "research software", "reuse"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.scripts]
+aisignoff = "aisignoff.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/industrial-mathematics-group/aisignoff"
+Issues = "https://github.com/industrial-mathematics-group/aisignoff/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

aisignoff-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aisignoff-0.4.0/src/aisignoff/__init__.py

@@ -0,0 +1,2 @@
+"""aisignoff: declare and check AI generation (G0-G3), human review (H0-H3) and AI review (A0-A3) per file."""
+__version__ = "0.4.0"

aisignoff-0.4.0/src/aisignoff/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())