ccm

Deterministic cognitive-capability materialization engine for ai4X.

ccm is the shared cognitive-capability materialization module of ai4X. It owns the canonical deterministic implementation of cognitive compose parsing, source binding, graph resolution, bundle materialization, orphan cleanup, and bundle doctor validation for ccc/ bundles.

ccm is library-first. It is consumed by wrapper and runtime-validation surfaces such as kob and ask, but it is not itself a product CLI.

ccm follows the ai4X agent-first development model.

Consequences:

• Deterministic checks are handled through TypeScript tests, shell checks, and verify.
• Higher-order review, handover, planning, and delivery governance belong to root ai4X when ccm is evolved inside the ai4X suite context.
• Therefore:
  • doc/usr/* is the direct human-facing documentation surface.
  • doc/agn/* is the agent-facing onboarding and navigation surface.
  • doc/arc/* is module architecture and structure documentation.
  • local adm/dev/* is module-specific governance and normative technical reference.
  • local adm/ops/* is module-specific operations documentation.
• ccm is a first-class shared ai4X module, but ai4X is the governing suite context when ccm is used or evolved inside ai4X.¹
• That matters in practice because:
  • kob can own curation and Mechthild without also owning the deterministic bundle engine.
  • ask can validate consumed local-agent bundles without inheriting curation behavior.
  • imported and local authored cognitive capabilities share one graph, one materialization model, and one doctor model.
  • generated imports, ccc/index.md, orphan cleanup, and drift validation remain consistent across public and project-local agent flows.

What ccm Does

ccm owns:

• reading and validating ccc/cap.compose.yaml
• binding logical cognitive inventories to physical capability roots
• scanning imported and local authored cognitive capabilities
• computing the effective dependency-complete bundle and deterministic order
• materializing generated imported ccc/*.md
• generating ccc/index.md
• cleaning up orphaned generated imported files
• validating the materialized bundle deterministically through doctor logic

ccm does not own:

• AGENTS.md
• runtime/client projection
• technical capability composition
• ask session state
• kob product CLI UX
• source-ref update behavior such as kob cap update --source ... --ref ...
• authored curation decisions and local-agent naming

Those concerns belong to ask, kob, and tcp, or remain governed at ai4X root level.

Public Surface

The module exposes exactly three public operations:

• planCognitiveBundle(...)
• materializeCognitiveBundle(...)
• doctorCognitiveBundle(...)

All three operate on a concrete ccc/ root and a set of logical cognitive inventory bindings.

Verification

Install dependencies once:

npm install

Then run:

make verify

Documentation

• human primer: doc/usr/primer.md
• architecture: doc/arc/arc42.md
• source map: doc/agn/source-map.md
• contract: adm/dev/contracts/cognitive-capabilities-materialization.md

For Humans

Copy and paste this prompt to your LLM agent. Do not just read it yourself; let your agent explain ai4X to you:

Guide me through ccm setup, public surface orientation, and first validation by following these sources in order:
1. https://raw.githubusercontent.com/normenmueller/ccm/trunk/doc/agn/user-onboarding.md
2. https://raw.githubusercontent.com/normenmueller/ccm/trunk/doc/usr/primer.md
3. https://raw.githubusercontent.com/normenmueller/ccm/trunk/INSTALL
Then explain what ccm does, why it is library-first, and tell me the best next source for my goal.

For Agents

Use this bootstrap prompt when entering ccm from a local checkout or from GitHub:

You are entering the ccm repository for governed work.
If you have a local checkout, use the local equivalents of these sources. Otherwise fetch them directly:
1. https://raw.githubusercontent.com/normenmueller/ccm/trunk/AGENTS.md
2. https://raw.githubusercontent.com/normenmueller/ccm/trunk/doc/agn/maintainer-onboarding.md
3. https://raw.githubusercontent.com/normenmueller/ccm/trunk/doc/agn/source-map.md
4. https://raw.githubusercontent.com/normenmueller/ccm/trunk/doc/arc/arc42.md
5. https://raw.githubusercontent.com/normenmueller/ccm/trunk/adm/dev/contracts/cognitive-capabilities-materialization.md
If the work is inside the ai4X suite context, also load:
- https://raw.githubusercontent.com/normenmueller/ai4x/trunk/AGENTS.md
- https://raw.githubusercontent.com/normenmueller/ai4x/trunk/adm/dev/protocols/workflow.md
Then summarize the module structure, the package responsibilities, tell me which local or ai4X protocol applies to the current task, and do not infer workflow from repository layout alone.

License

See LICENSE. © 2026 nemron

Footnotes

1. #eyodf = "eat your own dog food". ccm is maintained with the same agent-first model it helps operationalize. ↩