Skip to content

Bundle Tools

Portable, stdlib-only. Run from anywhere; both scripts locate the bundle root relative to their own location (the parent of this directory).

new_concept.py — scaffold a concept

python3 tools/new_concept.py <holder> <slug> --title "Display Name" [--type Concept]
# e.g.
python3 tools/new_concept.py 30-actors labour-unions-and-media --title "Labour Unions and Media"

Writes <holder>/<slug>.md from templates/concept.md with the frontmatter filled in (title, description placeholder, today's UTC timestamp, status: draft). It does not edit the holder's index.md — add the index line yourself, so a human decides the one-line description that ends up in the index.

<holder> must be an existing numbered holder directory (e.g. 30-actors) or new to create one at the next free prefix.

validate_bundle.py — convention check

python3 tools/validate_bundle.py            # whole bundle
python3 tools/validate_bundle.py 30-actors  # one holder

Exit code 0 = clean, 1 = findings. Checks:

  • frontmatter parses and required keys are present (type, title, description, status)
  • status is one of draft / stable / deprecated
  • generated.by uses the actor convention (agent/..., human:..., process:...)
  • every sources[].resource that is a bundle-relative path exists on disk
  • every bundle-rooted internal link (/holder/file.md) resolves
  • every footnote reference [^x] has a matching definition [^x]: in the same file
  • 95-inbox items carry stale_after and the date metadata
  • 96-journal/decisions.jsonl lines are valid JSON with the schema's required keys

It does not check whether claims are true. That is 90-playbooks/claim-verification-playbook.md.

Expected failure on a fresh scaffold

A just-scaffolded concept intentionally fails validation: the template's placeholder link (/00-foundations/example.md) does not resolve and sources is empty. That is the tool telling you the file is not finished. Replace the placeholder link and add real sources, then re-run.

Known quirk

validate_bundle.py uses PyYAML if importable and falls back to a small built-in parser for the frontmatter shapes used in this bundle. If you add exotic YAML (nested maps in sources[], anchors), install PyYAML rather than extending the fallback.