AGENTS.md@.github · diff

git:20261018.4f752a3 to git:20261019.6b254e1

4 added, 2 removed. Audit A to A.

## Fast functional CI

`ci.yml` runs on main pushes, pull requests and manual dispatch. It uses Linux

and Python 3.14: lint/types and public data/security guards, complementary pipeline smoke

shards and required selected full-module contract jobs, standalone wheel builds and focused behavioral tests,

and the required `CI Gate`. `.github/project-smoke.json` names the actual tests;

the smoke runner refuses missing projects, empty selections and escaping paths.

These are functional checks, with no full-suite coverage or native acceptance claim.

Main/manual runs select every public project. Exact project-only PRs include

transitive consumers; shared, unknown or ambiguous changes select the full roster.

Infrastructure includes changed tests and declared Source owners without dropping

the legacy union. `CI Gate` requires both test lanes and checks their original

pytest selection/outcome receipts for an exact disjoint union. JUnit is diagnostic.

Routine automatic jobs contain at most twenty complete modules, with dedicated

- jobs for selected process measurement and Root acceptance modules. At most eight

+ jobs for selected process measurement, run-matrix and Root acceptance modules. At most eight

routine jobs run concurrently; the 540-second job-body clock is unchanged.

The existing bounded execution boundary cleans up owned descendants and retains

the original OS/effective exits in a diagnostic that grants no acceptance.

Full contract jobs explicitly clear marker and keyword filters, refuse any

deselection, and use the established 120-second infrastructure pytest default;

explicit family/module markers and original operation deadlines retain authority.

The CLI setting does not alter timeout defaults in nested producer environments.

`platform-native-preflight.yml` adds an incomplete cold installed diagnostic;

- its bounded one-exemplar result never qualifies full release acceptance.

+ it prepares only the selected exemplar and its declared local providers, then

+ uses the production Original/Current admissions without a duplicate all-project

+ prelude. Its bounded result never qualifies full release acceptance.

The former cross-version/full-suite matrix remains in `hardening.yml`, invoked

manually. `platform-required-acceptance.yml` is also manual-only; its original

custody requirements remain mandatory for formal release acceptance. Further

hardening choices and the local commands are in [`docs/development/ci.md`](../docs/development/ci.md).

Required Linux auxiliary qualification uses the Source-derived project matrix.

Each complete public project and the separate Root checks own one serial

`--matrix-cell` operation with `--auxiliary-workers 1` and 1,800 seconds.

This versioned partition changes aggregate scheduling and compute allowance;

it never qualifies an earlier failed global invocation. Root preparation/admission stay

serial, with one complete gate at a time per project. The gates within each

cell share its original deadline. Fresh installed candidate and release readers

live-authenticate every exact producer job, artifact and attempt and require the

complete disjoint gate union. Passing auxiliary observations require verified

guardian cleanup; deadline refusals retain absent child IDs and exit codes.

Cleanup admission also requires a successful final token census: an observation

error cannot stand in for verified absence.

Functional infrastructure smoke and selected contract jobs, complete Linux Root

observations, and Linux auxiliary acceptance prepare a fresh unprivileged

execution account before custody. The strict census keeps its global process

view and same-owner rule. Setup detaches shared cache hardlinks before scoped

ownership changes and forwards only declared runtime inputs. Original commands

retain their arguments and exit status; an always-run export copies readiness

bytes for the runner's artifact reader without changing captured permissions.

Source-declared disposable pytest scratch is excluded from that transport;

the exclusion record grants no observation or receipt authority.

Prepared model services keep their original runner-owned cleanup. Hosted checks

must verify the profile; setup and local tests alone establish no Linux or release

acceptance.

# GitHub Integration

## Overview

The `.github/` directory contains GitHub-specific configuration and automation for the Research Project Template. This includes continuous integration workflows, issue templates, PR templates, and other GitHub integrations that ensure code quality and collaborative development.

**Human entry point:** [README.md](README.md) — GitHub overview, doc map, and [Agent & automation entry point](README.md#agent--automation-entry-point). **This file (`AGENTS.md`):** job names, paths, and thresholds for automation and agents.

## Publication

**Title**: *A template/ approach to Reproducible Generative Research: Architecture and Ergonomics from Configuration through Publication*

**DOI**: [10.5281/zenodo.19139090](https://doi.org/10.5281/zenodo.19139090)

**Record**: [zenodo.org/records/19139090](https://zenodo.org/records/19139090)

**License**: Apache 2.0

Public exemplar GitHub/Zenodo records are generated into [`.github/README.md`](README.md#published-exemplars--pipeline-productivity-advanced-provenance-and-autopoiesis) from [`../docs/_generated/publication_records.md`](../docs/_generated/publication_records.md). Refresh them with:

```bash

uv run python scripts/docgen/publication_records.py --refresh-external

```

## Directory Structure

```mermaid

flowchart TB

GH[.github/]

GH --> META[AGENTS.md · README.md]

GH --> DEP[dependabot.yml Automated dependency updates]

GH --> PRT[PULL_REQUEST_TEMPLATE.md]

GH --> ITPL[ISSUE_TEMPLATE]

GH --> WF[workflows]

ITPL --> ITPL_DOCS[AGENTS.md · README.md]

ITPL --> ITPL_F[config.yml · bug_report.md · feature_request.md · documentation.md]

WF --> WF_DOCS[AGENTS.md · README.md]

WF --> WF_FAST[ci.yml Linux/Python 3.14 functional checks · CI Gate]

WF --> WF_CI[hardening.yml 20 jobs — 2 conditional via detect outputs — fep-lean, setup-hook-windows-smoke — manual-only lanes — public-matrix-receipt, test-infra-slow — 1 aggregation gate — ci-gate]

WF --> WF_STALE[stale.yml Auto-label/close stale issues/PRs]

WF --> WF_REL[release.yml GitHub Releases on version tags]

WF --> WF_REQUIRED[platform-required-acceptance.yml Original observations + strict candidate collector]

WF --> WF_DA[dependabot-automerge.yml Auto-merge safe Dependabot PRs]

classDef d fill:#0f172a,stroke:#0f172a,color:#fff

classDef pkg fill:#1e3a8a,stroke:#0f172a,color:#fff

classDef f fill:#0f766e,stroke:#0f172a,color:#fff

class GH d

class ITPL,WF pkg

class META,DEP,PRT,ITPL_F,WF_DOCS,WF_FAST,WF_CI,WF_STALE,WF_REL,WF_REQUIRED f

```

## Continuous Integration (CI/CD)

### Optional exhaustive hardening (`workflows/hardening.yml`)

**Triggers:** manual **`workflow_dispatch`** only.

**Concurrency:** Each manual hardening run retains its unique run group so later commits or dispatches cannot cancel exact-commit verification.

**Pipeline jobs** (job ids in `hardening.yml`; display names differ — use `name:` for branch protection):

**20 jobs total; 2 depend on optional-project presence (fep-lean, setup-hook-windows-smoke), gated by the `detect` job's outputs

(`needs.detect.outputs.*`) — NOT a job-level `hashFiles()` (that is invalid

in a job `if:` and rejects the whole workflow at parse). 2 further jobs

(`public-matrix-receipt`, `test-infra-slow`) run only on the manual dispatch.**

| --- | --- | --- | --- | --- | --- |

| 1 | `detect` | Detect optional projects | — | — | ubuntu (always) |

| 3 | `actionlint` | Actionlint | — | — | ubuntu (always) |

| 4 | `lint` | Lint & Type Check | — | 3.14 | ubuntu |

| 5 | `health` | Static Health Report | — | 3.14 | ubuntu |

| 12 | `validate` | Validate Manuscripts | — | 3.14 | ubuntu |

| 13 | `security` | Security Scan | — | 3.14 | ubuntu |

| 14 | `docs-lint` | Documentation Lint | — | 3.14 | ubuntu |

| 16 | `public-matrix-receipt` | Public Matrix Receipt (receipt-bearing full matrix) | — | 3.14 | ubuntu · schedule/manual only |

**Lint job** also runs `uv run python -m infrastructure.skills check-all-exports` (MED5 `__all__` gate), `scripts/audit/check_tracked_generated_artifacts.py` (rejects generated outputs and local `.codegraph/` indexes), **`scripts/audit/check_template_drift.py --strict`** (exemplar doc/script drift against Layer-1 contracts), and **`scripts/audit/check_tracked_all.py`** — the **confidentiality guard** that fails CI if any path outside the public allowlists for `projects/`, `fonds/`, `rules/`, or `tools/` is git-tracked (this is a public repo; confidential/rotating resources are local-only). **`validate`** runs manuscript markdown validation (one dir per invocation, looped over `projects/*/manuscript/`), `scripts/docgen/api_reference.py --check`, and imports each `projects.{name}.src`. **`security`** runs blocking **`pip-audit`** (IDs from [`.github/pip-audit-ignore.txt`](pip-audit-ignore.txt), up to 3 retries on failure) and **`bandit -c bandit.yaml -r -ll`** over `infrastructure/`, `scripts/`, and `projects/`. Path exclusions (`projects/working/`, `projects/ongoing/`, `projects/published/`, `projects/archive/`, `projects/other/`, plus `.venv`, `site-packages`, `.lake`, the vendored `infrastructure/steganography/kmyth` submodule, and named rotating research projects such as `projects/BeeStack` — **not** the rendered `projects/active/` mirror) live in [`bandit.yaml`](../bandit.yaml) (`exclude_dirs`).

**Display name (branch protection):** the optional fep_lean job is reported as **`fep_lean (gauss + lake)`** (`hardening.yml` `name:` on job id `fep-lean`). It runs only when the `detect` job sets `fep_lean == 'true'` (`if: needs.detect.outputs.fep_lean == 'true'`) — a job-level `hashFiles()` is **invalid** in a job `if:` and would reject the whole workflow at parse, which is why the `detect` job exists. When fep_lean lives under `projects/working/`, `detect` reports `false` and the job is skipped. Promote with `mv projects/working/fep_lean projects/active/fep_lean` to activate CI. **Branch protection must NOT mark the two conditional jobs (`fep-lean`, `setup-hook-windows-smoke`) as required** — they are skipped (not failed) when their project is absent, so requiring them would wedge every PR.

Infrastructure and project coverage are uploaded to **Codecov** only from their

Python 3.14 / `ubuntu-latest` cells; upload failures do not fail CI.

The `verify-no-mocks` job runs [`scripts/audit/verify_no_mocks.py`](../scripts/audit/verify_no_mocks.py) at the repository root (not under `.github/`).

### Stale Workflow (`workflows/stale.yml`)

Runs daily. Issues → stale after 60 days, closed after 14 more. PRs → stale after 30 days, closed after 14 more. Exempt labels: `pinned`, `security`, `in-progress`, `blocked`, `do-not-close`.

### Release Workflow (`workflows/release.yml`)

Triggered by `v*.*.*` tag pushes or manual dispatch with a tag. It resolves the

requested tag before checkout, checks out that exact ref, proves `HEAD` matches

the dereferenced tag commit, and explicitly prepares the locked public-exemplar

and installed-build environment before offline admission or checks. It runs the

root release contract, bounded pipeline-smoke infra test lane plus no-mocks gate on the tagged SHA,

the fail-closed capability manifest, the complete Python 3.12–3.14 installed

wheel matrix outside source checkouts, and strict rendered publication audit

across the canonical public roster. Root 4+ additionally requires an explicit

same-repository successful hosted run and artifact bound to that exact revision,

the aggregate receipt hash, and every required candidate acceptance gate.

The candidate includes

[`platform-required-acceptance.yml`](workflows/platform-required-acceptance.yml):

six original Root minor/platform units, common and native observations, and a

strict collector that uploads only the passed complete exact-source bundle.

Its presence does not establish successful hosted acceptance, integration into

`main`, or publication; ordinary CI uploads cannot authorize this handoff.

Tag pushes without the explicit handoff stop. The 4.0.2 candidate remains Unreleased during development. Final changelog and

release-intent metadata must be frozen before exact-revision acceptance; those

bytes do not establish publication. The prepared 4.0.0 candidate was not published.

The release uses `softprops/action-gh-release@v3.0.3` with

**`generate_release_notes`** off. Root 4+ reads `docs/releases/<tag>.md` for its

actual tag, such as the [4.0.2 candidate notes](../docs/releases/v4.0.2.md), and

adds accepted-commit, hosted-run and receipt-hash bindings. It publishes the

admitted installed wheel, exact final source distribution, tag-selected overview

PNG and byte manifest, then verifies retrieved asset hashes. Earlier major tags

retain the short git-log excerpt.

### Dependabot Automerge Workflow (`workflows/dependabot-automerge.yml`)

Triggered by `pull_request_target` on Dependabot PRs only (`github.actor == 'dependabot[bot]'`). Enables GitHub native auto-merge (`gh pr merge --auto --squash`) for `semver-minor` and `semver-patch` updates. Major bumps are left for human review. The workflow never checks out or executes PR HEAD code — it only reads update metadata and calls the GitHub API — so the elevated `pull_request_target` trigger does not expose secrets to untrusted code. Auto-merge must also be enabled in repository settings (Settings → General → "Allow auto-merge").

## Dependabot (`dependabot.yml`)

[`dependabot.yml`](dependabot.yml) at the repository root: **GitHub Actions** (`package-ecosystem: github-actions`, `directory: /`) and **Python** (`package-ecosystem: pip`, `directory: /`) both read the root **`pyproject.toml`** / lockfile — compatible with **uv**. Weekly **Monday 09:00 UTC**, max **5** open PRs per ecosystem. Groups: **`actions-minor`** (Actions minor/patch), **`dev-tools`** and **`scientific-core`** (Python).

## Quality Gates

| Gate | Threshold |

| --- | --- |

| Ruff lint | zero violations |

| Ruff format | zero diffs |

| mypy strict gate | zero errors across the generated public source scope |

| Mock-framework lexical gate | zero prohibited imports/calls (`--inventory` debt remains advisory) |

| Public capability parity | exact public roster and CI matrix; unique normalized package identities; complete moving-patch Python series; parseable source/tests; compiled/confined direct hydration; reason-bearing skips |

| Infrastructure coverage | ≥ 60% |

| Project coverage (per-project standalone) | ≥ 90% |

| Combined-union public-project gate (`DEFAULT_FAIL_UNDER`) | ≥ 75% via local `scripts/pipeline/stage_01_test.py --project-only --all-projects --public-projects` (CI `test-project` enforces per-exemplar 90% only) |

| pip-audit | zero known vulns not listed in `.github/pip-audit-ignore.txt` |

| Bandit MEDIUM+ (`-c bandit.yaml`) | zero findings |

| Mermaid diagrams render under `mmdc` | zero failures |

| Markdown cross-links resolve on disk | zero broken links |

| Permanent-template folders carry `AGENTS.md` + `README.md` | zero missing pairs |

| `N Python (sub)packages` claims match reality | zero stale counts |

| Rotating projects in long-lived docs are conditional | zero ghost references |

| Import time | ≤ 5 s |

| Module line count (`scripts/gates/module_line_count_check.py`) | warn ≥ 800 / fail ≥ 950 for `infrastructure/` + `scripts/`; warn ≥ 150 / fail ≥ 250 for `projects/*/scripts/` |

## Local Pre-Push Parity (`.pre-commit-config.yaml`)

The repo ships a [`.pre-commit-config.yaml`](../.pre-commit-config.yaml) with

**seven pre-push hooks** that mirror (or partially mirror) CI gates so pushes

that would fail CI fail locally first:

| Hook id | Mirrors CI step | Typical runtime |

| --- | --- | :-: |

| `pre-push-quick` | `verify-no-mocks` + `check_tracked_all` + `tests/infra_tests/git_hook_smoke/` | ~3 s |

| `docs-contract-guard` | `check_template_drift.py --strict` + AGENTS personal-memory test | ~5 s |

| `bandit-quick` | `security` job Bandit step (`-c bandit.yaml -r -ll`) | ~5–30 s |

| `skills-check` | `infrastructure.skills check` (manifest freshness) | <1 s |

| `operations-check` | `infrastructure.skills operations-check` (operation-manifest freshness) | <1 s |

| `all-exports-check` | `infrastructure.skills check-all-exports` (lint job MED5 gate) | <1 s |

| `skill-reachability-check` | docs-lint skill front-door and index completeness gate | <1 s |

As of 2026-10-13, `docs-contract-guard` does not run `COUNTS.md`

synchronization and dated coverage provenance checks on every push. All its