manifest — living spec from source

manifest is the build-as-spec tool for The Interdependency. It treats the
factual half of a CLAUDE.md like a lockfile: generated from the code,
never hand-edited, and CI-enforced so it can't drift.

The line it draws

• Generate what is observable: package name, version, description,
  license, authors, repository URL, build backend, development status,
  supported Python versions, keywords, runtime dependencies, optional extras,
  top-level layout, and CI workflow filenames. These are the fields that repeat
  across repos and rot silently — the "myriad variables" nobody should type
  twice. (Fuzzy facts that can't be read with confidence — e.g. the exact test
  command — are deliberately left to hand-authored prose rather than risk
  emitting a wrong "fact".)
• Author what is judgement: why a boundary exists, scope, claim status
  (DEFENDED/FRONTIER), gotchas. The generator never touches these.
• hmmm is the seam: an unknown fact renders as hmmm, a visible gap, not
  a guess (per the msdmd doctrine this skill is built on).

Everything generated lives between two markers; everything else in the file is
yours:

<!-- BEGIN GENERATED:manifest -->
...derived facts...
<!-- END GENERATED:manifest -->

Usage

# Print the block (no writes) — see what would be generated
python .agents/skills/manifest/generate.py --root . --print

# Insert or refresh the block in CLAUDE.md
python .agents/skills/manifest/generate.py --root . --write

# CI drift gate: exit 1 if CLAUDE.md's block is stale or missing
python .agents/skills/manifest/generate.py --root . --check

# src-layout / non-root pyproject (e.g. edcmbone):
python .agents/skills/manifest/generate.py --pyproject backend/pyproject.toml --write

Flags: --root <dir> (default .), --file <doc> (default CLAUDE.md),
--pyproject <path> (default pyproject.toml), and exactly one of
--write / --check / --print.

Field requirements

The required generated fields are the observable repo facts the runner can
derive: package metadata, runtime dependencies, optional extras, top-level
layout, and CI workflow names. Judgement, rationale, test-command guesses, and
doctrine stay hand-authored outside the generated block. Unknown observable
facts render as hmmm.

Runner contract

A compliant manifest runner is stdlib-only, deterministic, idempotent, and
non-destructive. It reads pyproject.toml plus the file tree, rewrites only the
bytes between the manifest markers, supports --write, --check, and
--print, and exits non-zero when --check detects drift.

Wiring a repo (the propagation recipe)

1. Vendor generate.py to .agents/skills/manifest/generate.py (verbatim copy
   from this canonical source). Record the source commit SHA in the local
   .agents/skills/README.md note, and cite this repo + SHA in the propagation
   PR (the PR-citation requirement is in ORG_DISTRIBUTION.md).

2. Run --write once to insert the block near the top of CLAUDE.md. Leave the
   markers in place; never hand-edit between them.

3. Add a CI step that runs --check (a tiny manifest-check.yml workflow, or a
   step in the existing one) so a stale block fails the build.

4. Pin the vendored copy (drift gate). Vendoring duplicates this file, so
   guard the duplication: record its checksum and verify it in CI, so a repo's
   copy can never be silently forked.

   # at vendor time, from the repo root:
   ( cd .agents/skills/manifest && sha256sum generate.py > generate.py.sha256 )

   # in the CI job, before the --check step:
   - name: Vendored generate.py matches skill-lib (no local fork)
     run: cd .agents/skills/manifest && sha256sum -c generate.py.sha256

   The checksum is the same one skill-lib@<recorded-sha>/manifest/generate.py
   produces, so a reviewer can verify the copy is a pristine artifact of that
   commit. The only legal way to change a repo's generator is to change it here
   and re-vendor (which updates the SHA + checksum together). Catching the other
   direction — copies falling behind a newer skill-lib — is a skill-lib-side push
   concern (mirror/propagation), not the consumer gate.

5. After any change to pyproject.toml / version / deps / layout, run --write
   and commit the refreshed block — the same discipline as a lockfile.

Contract & boundaries

• Stdlib only. Uses tomllib, so it needs Python 3.11+ to run; it is a
  dev/CI tool and is never shipped inside a package.
• Deterministic & idempotent. --write twice is a no-op; that is what makes
  --check a stable gate.
• Non-destructive. It only ever rewrites the bytes between the two markers
  (or appends the block once if absent). Hand-authored prose is untouched.
• Additive scope. Start with the high-signal/low-noise fields above. New
  derived fields are an extension here (bump the block, keep markers stable), not
  a per-repo fork — portability depends on one generator.

Anti-patterns

• Hand-editing bytes inside the generated manifest markers.
• Emitting fuzzy or judgement-shaped facts as if they were mechanically derived.
• Forking the vendored generator in a consuming repo instead of changing this
  canonical source and re-vendoring.
• Running --write in CI when the intended gate is --check.