# 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.