Skip to content

SETUP.md

Latest commit

 

History

History
162 lines (122 loc) · 7.39 KB

SETUP.md

File metadata and controls

162 lines (122 loc) · 7.39 KB
Raw

Setup

Everything here is configured for Claude Code. Copy this tree into your repository root, git init, and run claude.

What is in here

CLAUDE.md                    project constitution, loaded every session
SETUP.md                     this file
.gitignore
config/cost-parameters.yaml  economic parameters, versioned with provenance
config/sources.yaml          collection cadence, formats, gap tolerance
pyproject.toml               uv project: deps, `collectors` script, pytest and ruff config
src/collectors/              V1 archival collectors (built, tested)
scripts/                     collect.sh, crontab and launchd examples
tests/                       17 failure-injection tests
reports/collection-status.md generated every run — do not edit
docs/
  00-charter.md              the contract  (v1.1)
  01-architect-field-guide.md  your reference — read this yourself
  CURRENT-STAGE.md           what stage is active and what is out of scope
  decision-journal.md        yours, Claude cannot write it
  measurements.md            yours, Claude cannot write it
  adr/                       yours, Claude cannot write it
.claude/
  settings.json              permissions, hooks, env
  rules/                     6 rule files, 3 of them path-scoped
  agents/                    4 subagents
  skills/                    4 verification skills
  hooks/                     4 Python hooks

Before first run

  1. Set your contact address. Edit SOURCE_USER_AGENT in .claude/settings.json. SEC requires a declared User-Agent with a real contact; an anonymous one gets blocked faster.
  2. Check Python is on PATH. The hooks are Python 3, no dependencies.
  3. chmod +x .claude/hooks/*.py scripts/collect.sh if the executable bit did not survive the copy.
  4. uv sync to build the environment.
  5. Start Claude Code and run /status to confirm the settings loaded, then /hooks to confirm all four hooks registered.

The division of labour

This setup exists to enforce one rule:

Loops automate toil. They never automate decisions.

Claude fetches, parses, benchmarks, verifies and challenges. You decide the ontology, the thresholds, the storage, and you write every ADR. The hooks make that structural rather than aspirational — Claude is denied write access to docs/adr/, decision-journal.md, measurements.md, the charter, the field guide, and data/raw/.

If you find yourself accepting an agent-authored architecture decision, the setup has failed even though nothing errored.

Permissions model

.claude/settings.json uses three tiers:

  • allow — reads, greps, tests, lint, git inspection and staging, archive listing. No interpreter wildcards, because Bash(python3 *) is arbitrary code execution.
  • ask — network fetches, dependency installs, docker, psql. You see every outbound request during V0/V1, which is when you are still learning what the sources do.
  • deny — human-owned artefacts, raw data, secrets, rm -rf, git push, hard resets.

Deny beats allow. Loosen ask → allow once a source contract is stable; do not loosen deny.

The four hooks

Hook Event Effect
protect-human-artifacts.py PreToolUse on Edit/Write Denies writes to ADRs, journal, measurements, charter, guide, raw data
protect-raw-data.py PreToolUse on Bash Denies shell paths around the same protections (rm, mv, sed -i, redirects)
check-provenance.py PostToolUse on Edit/Write Advisory: flags quantities in docs/ with no provenance marker
session-context.py SessionStart Loads current stage, ADR inventory, recent measurements, restates the prime directive

The first two are enforcement. settings.json draws the boundary; the hooks catch what a static rule cannot.

The four subagents

Invoke with @architecture-reviewer, or let Claude dispatch them.

  • architecture-reviewer — read-only and deliberately adversarial. Audits provenance, ADR quality, unjustified components, stage drift, and any place a model sits in the decision path. Reports, never fixes. Run it weekly and at every stage exit. This is the agent closest to your actual goal.
  • data-inspector — reads real records and produces numbers with methods. Reports them in chat; you record them.
  • collector-engineer — builds V1 archival collectors under the source contract rules.
  • benchmark-runner — runs technology comparisons and reports results. Never picks a winner; that is an ADR.

The four skills

Invoke as /verify-source-contract, /verify-golden-case, /stage-exit, /adr-draft, or let Claude trigger them by description.

verify-source-contract includes six failure injections that must actually be run, not designed for. stage-exit checks the four things every stage ships: capability, failure injected, measurement, decision. adr-draft produces ADR content in chat and refuses to create the file.

Rules loading

.claude/rules/10-provenance.md and 60-evaluation.md load every session. The other four are path-scoped via paths: frontmatter and load only when Claude touches the matching directories — source contract rules when it opens src/collectors/, canonical model rules when it opens src/canonical/, and so on. This keeps the always-on context small.

Collectors are already built

src/collectors/ is V1, done and tested against the live publishers. See docs/02-collection-runbook.md for the full runbook.

uv sync                                     # .venv + deps + the `collectors` console script
export SOURCE_USER_AGENT="YourProject (you@example.com)"

uv run collectors run --all --dry-run       # what would be fetched, with sizes
uv run collectors run --source gleif        # start capturing deltas today
uv run collectors status                    # gaps, latest captures, recent failures
uv run pytest                               # 17 failure-injection tests
uv run ruff check                           # lint

(Non-uv: pip install -r requirements.txt, export PYTHONPATH="$PWD/src", python3 -m collectors ....)

Then schedule it — scripts/crontab.example or the launchd plist. Full copies are off by default; deltas and small artefacts only, so the first days cost tens of megabytes rather than tens of gigabytes.

Start here

Week 0, day 1:  Schedule the collectors. GLEIF deltas and the Companies House PSC snapshot
                are being overwritten right now and cannot be recovered later. This is the
                only genuinely time-sensitive item in the project.

                crontab -e   # paste scripts/crontab.example, fix REPO and contact address

Week 0, day 2:  Start V0 properly with collectors already running in the background.

                @data-inspector measure crosswalk coverage: what percentage of UK GLEIF
                records carry a resolvable Companies House number, sliced by entity status
                and legal form?

Then read docs/01-architect-field-guide.md end to end once, without taking notes.

A note on scope

The charter runs to V21. V11 is the credible-product checkpoint — identity resolution, relationship traversal, sanctions screening with defensible negatives, and a reproducible memo. That is a coherent system with a story. Everything beyond it is depth you add while interviewing, not a prerequisite for having something to show.

The classic failure of ambitious portfolio projects is never shipping. Aim at V11.