From 48272ea1706a9734faed58e07448cfcb7027008b Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 13 Jun 2026 15:00:25 +0200 Subject: [PATCH] Add project CLAUDE.md and ignore machine-local .claude files - CLAUDE.md: project guidance for Claude Code (repo layout, commands, architecture, no-collapse guardrails). - .gitignore: exclude .claude/settings.local.json and .claude/*.local.* (personal permission allowlists and transient ralph-loop session state). Co-Authored-By: Claude Opus 4.8 --- .gitignore | 4 ++ CLAUDE.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 36b13f1..cc0a2fe 100644 --- a/.gitignore +++ b/.gitignore @@ -174,3 +174,7 @@ cython_debug/ # PyPI configuration file .pypirc +# Claude Code (machine-local, not shared) +.claude/settings.local.json +.claude/*.local.* + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..47573fd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,107 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repository is + +InfoTechCanon is a markdown-first **canon** — a body of kernel documents, domain +models, and specialized standards for building interoperable information-processing +systems. The repository has two layers: + +- **Repository root** is the *service, governance, and workplan shell*: Python + package (`src/info_tech_canon/`), manifests (`canon.yaml`, `pyproject.toml`), + governance docs (`INTENT.md`, `SCOPE.md`), and `workplans/`. +- **`infospace/`** is the one concrete **infospace** — the actual canon content + (kernel/models/standards/profiles/agent assets/etc.) that the service operates on. + +The canon content is data; the Python package is a thin read-mostly service over it. + +## Commands + +```bash +# Run the CLI from source (no install needed) +PYTHONPATH=src python3 -m info_tech_canon + +# Maintenance targets (wrap the CLI) +make validate # validate canon, write infospace/validation/latest.json +make index # refresh generated indexes and views +make tree # refresh the generated infospace tree +make agent-briefs # refresh generated agent briefs +make test # python3 -m pytest + +# Tests +python3 -m pytest # full suite +python3 -m pytest tests/test_cli.py # one file +python3 -m pytest tests/test_cli.py -k inspect # one test by name + +# Read-only local HTTP API (stdlib only) +PYTHONPATH=src python3 -m info_tech_canon api --host 127.0.0.1 --port 8765 +``` + +Common CLI subcommands: `inspect`, `artifacts [--kind K]`, `models`, `standards`, +`validate [--write PATH]`, `index`, `tree`, `agent-briefs`, `views [name]`, +`graph [--format json|mermaid]`, `review-kit`, `alignment-template`, +`profile inspect|validate|graph `, `api`. After `pip install`, the same +commands are available via the `info-tech-canon` console script. + +## Architecture + +**Service surface (CLI / JSON / API are one contract).** `cli.py`, `api.py`, and +the `info_tech_canon.service` functions are three faces of the *same* operations. +Every operation lives as a function in `service.py` returning a JSON-serializable +dict with an `ok` boolean; `cli.py` prints it and `api.py` serves it. When you add +or change an operation, update all three so the contract stays consistent. Errors +are raised as `CanonServiceError(code, message, details)` and rendered as +`{"ok": false, "error": {...}}` (CLI exit code 2). + +**`bench.py` is the boundary to `infospace-bench`.** Artifact loading, collection +checks, relationship summaries, and mermaid export are *not* implemented here — they +come from the sibling repo `infospace-bench` (a path dependency at +`~/infospace-bench`, declared in `pyproject.toml`). `bench.py` loads that package's +modules by file path under an internal alias and re-exports `Infospace`, +`KnowledgeArtifact`, `load_infospace`, `run_collection_checks`, +`relationship_summary`, `export_mermaid`. Behavior depending on artifact loading or +graph/check logic lives in `infospace-bench`, not here. + +**Manifests.** `canon.yaml` (repo root) is the human/governance manifest of the +canon's kernel/models/standards. `infospace/infospace.yaml` is the machine config +that `load_infospace` consumes — it lists disciplines (paths), schema locations, and +`viability` thresholds. `validate` cross-checks artifact paths/relationships against +the loaded infospace and enforces viability thresholds (e.g. redundancy/coverage/ +coherence/consistency/granularity) plus structural checks from `validation.py`. + +**Profiles** (`profiles.py`) are concrete proofs under `infospace/profiles//` +with a `profile.yaml`. `small-saas` is the first executable profile proof. + +## Generated files — do not edit by hand + +`make index/tree/agent-briefs` and `validate --write` produce files carrying a +`GENERATED ... do not edit` header (under `infospace/views/`, `infospace/indexes/`, +`infospace/agent/briefs/`, `infospace/validation/latest.json`, the tree manifest). +Edit the *source* artifacts and regenerate; never hand-edit generated output. + +## Workplans + +Work is tracked in `workplans/` against `workplans/index.yaml` (statuses like +`finished`/`active`). Consumer-side work belongs in the consumer's own repo, not +here — `repository scope` is producer-only. Use the project's `/ralph-workplan` +skill (not raw `/ralph-loop`) when running a workplan loop. + +## Conventions and guardrails + +- **Boring and inspectable.** stdlib + PyYAML only in this package; no heavy + dependencies. Python for code, YAML for manifests/schemas, Markdown for docs. +- **Do not collapse canonical concepts** when editing canon content. These are kept + deliberately distinct: Organization Role / AccessRole / CARING Canonical Role; + Actor / Subject / Principal; Policy / Control / Evidence; Dataset / DataStore; + Artifact / Release / Deployment / Runtime State; Network Intent / Policy / + Configuration / Observed State; Alert / Incident. Tags are never substitutes for + canonical fields, relationships, policies, or evidence. +- CARING is a *standard* (`standards/caring/`, namespace `itc-caring`), not merely + an access-control profile. + +## State Hub note + +`chore(consistency): sync task status from DB [auto]` commits and `.custodian-brief.md` +come from the external Custodian State Hub, not from code in this repo. They are +auto-generated; don't treat them as manual work to reconcile here.