generated from coulomb/repo-seed
tegwick
48272ea170
- 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 <noreply@anthropic.com>
108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# 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 <command>
|
|
|
|
# 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 <profile>`, `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/<name>/`
|
|
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.
|