info-tech-canon/CLAUDE.md

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

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