Program map

Every module of the CLI, every file it reads and writes, scanned out of the shell sources rather than drawn by hand.

Nobody drew this. scripts/lib/architecture-scan.awk reads bin/majordomus and lib/*.sh on every build and reports what it can prove: which module sources which, and which file under .ai/ each module names. A module that stops touching a file loses its edge the same day. A diagram that cannot go stale is worth more than a prettier one that can.

What an edge means

Direction comes from the line the reference sits on — the redirection it is behind, or the command word that introduces it. A path handed straight to a helper is drawn as uses, not guessed at, because a wrong arrow here would be a claim the sources do not support. Read the scanner if you want the exact rule; it is forty lines.

static reference scan of bin/majordomus and lib/*.sh

reads sources uses writes

Select a node to see what it is and what it touches.

Modules of the CLI and the files under .ai/ they touch. Solid arrows are reads and writes the scan could place; dashed arrows are references it would not claim a direction for.

The same graph as text — 94 nodes, 283 edges

majordomus entry
- sources → lib/adr.sh
- sources → lib/archive.sh
- sources → lib/bench.sh
- sources → lib/capture.sh
- sources → lib/check.sh
- sources → lib/checkpoint.sh
- sources → lib/common.sh
- sources → lib/context.sh
- sources → lib/decision.sh
- sources → lib/doctor.sh
- sources → lib/doctrine.sh
- sources → lib/evidence.sh
- sources → lib/finish.sh
- sources → lib/handover.sh
- sources → lib/history.sh
- sources → lib/init.sh
- sources → lib/knowledge.sh
- sources → lib/migrate.sh
- sources → lib/plan.sh
- sources → lib/prompt.sh
- sources → lib/question.sh
- sources → lib/recover.sh
- sources → lib/rules.sh
- sources → lib/search.sh
- sources → lib/session.sh
- sources → lib/skills.sh
- sources → lib/start.sh
- sources → lib/update.sh
- sources → lib/usecase.sh
- sources → lib/watch.sh
common module
- reads → .ai/manifest.yaml
- reads → .ai/repo/policy.yaml
- reads → .ai/repo/providers
- sources → lib/capture.sh
- sources → lib/changed.sh
- sources → lib/rust_bin.sh
- uses → .ai/local/state/session-current.yaml
- uses → .ai/local/state/sessions-open
- writes → .ai/local/cache/flat
- writes → .ai/local/state/current.yaml
- writes → .ai/local/state/ledger.jsonl
- writes → .ai/local/state/mcp/ensure.log
- bin/majordomus sources → this
adr module
the repository's architecture decisions: list, show, propose, check
- sources → lib/context.sh
- sources → lib/knowledge.sh
- sources → lib/rules.sh
- writes → .ai/repo/adrs/.id.lock
- bin/majordomus sources → this
- lib/doctor.sh sources → this
knowledge module
the compiled index over what this repository states, and the records it derives
- reads → .ai/local/state/current.yaml
- reads → .ai/local/state/sessions-open
- sources → lib/changed.sh
- sources → lib/decision.sh
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- uses → .ai/local/state/completed
- uses → .ai/local/state/decisions.md
- uses → .ai/repo/knowledge/sources.yaml
- uses → .ai/repo/policy.yaml
- bin/majordomus sources → this
- lib/adr.sh sources → this
- lib/capture.sh sources → this
- lib/check.sh sources → this
- lib/context.sh sources → this
- lib/derive.sh sources → this
- lib/session.sh sources → this
- lib/skills.sh sources → this
rules module
the effective rule set: vendored baseline plus project rules (read-only, except vendor update)
- reads → .ai/repo/rules/vendor
- bin/majordomus sources → this
- lib/adr.sh sources → this
- lib/doctrine.sh sources → this
- lib/init.sh sources → this
- lib/usecase.sh sources → this
context module
what the next worker needs to know now, within budget
- reads → .ai/local/state/decisions.md
- reads → .ai/local/state/ledger.jsonl
- reads → .ai/local/state/open-questions.md
- reads → .ai/repo/project/issues
- sources → lib/context_docs.sh
- sources → lib/decision.sh
- sources → lib/handover.sh
- sources → lib/history.sh
- sources → lib/intent_binding.sh
- sources → lib/knowledge.sh
- sources → lib/prompt.sh
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- bin/majordomus sources → this
- lib/adr.sh sources → this
- lib/doctor.sh sources → this
- lib/prompt.sh sources → this
- lib/session_context.sh sources → this
- lib/watch.sh sources → this
repo/adrs/.id.lock artifact
- lib/adr.sh writes → this
archive module
a snapshot of the tracked tree, for reading or checking elsewhere
- reads → .ai/repo/archive.yaml
- bin/majordomus sources → this
repo/archive.yaml artifact
- lib/archive.sh reads → this
bench module
time every public command, cold and warm, against the baseline
- sources → lib/commands.sh
- bin/majordomus sources → this
commands module
- lib/bench.sh sources → this
- lib/check.sh sources → this
- lib/doctor.sh sources → this
- lib/usecase.sh sources → this
capture module
record the person's raw prompts from a provider hook, and prove it
- sources → lib/checkpoint.sh
- sources → lib/derive.sh
- sources → lib/handover.sh
- sources → lib/knowledge.sh
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- uses → .ai/local/session-contexts
- uses → .ai/local/state/sessions-open
- uses → .ai/repo/policy.yaml
- writes → .ai/local/state/mcp/ensure.log
- bin/majordomus sources → this
- lib/common.sh sources → this
- lib/doctor.sh sources → this
- lib/usecase.sh sources → this
session module
open, inspect and close one execution episode
- reads → .ai/local/state/ledger.jsonl
- sources → lib/changed.sh
- sources → lib/derive.sh
- sources → lib/knowledge.sh
- sources → lib/project.sh
- sources → lib/session_context.sh
- uses → .ai/local/state/locks/outbox-drain
- uses → .ai/local/state/locks/session-pointer
- uses → .ai/local/state/session-current.yaml
- uses → .ai/local/state/sessions
- uses → .ai/local/state/sessions-open
- bin/majordomus sources → this
- lib/capture.sh sources → this
- lib/context.sh sources → this
- lib/derive.sh sources → this
- lib/doctor.sh sources → this
- lib/knowledge.sh sources → this
- lib/recover.sh sources → this
local/state/sessions-open artifact
- lib/doctor.sh reads → this
- lib/knowledge.sh reads → this
- lib/capture.sh uses → this
- lib/common.sh uses → this
- lib/recover.sh uses → this
- lib/session.sh uses → this
local/session-contexts artifact
- lib/capture.sh uses → this
- lib/init.sh uses → this
- lib/migrate.sh uses → this
derive module
- reads → .ai/local/state/current.yaml
- reads → .ai/local/state/decisions.md
- reads → .ai/local/state/ledger.jsonl
- sources → lib/decision.sh
- sources → lib/knowledge.sh
- sources → lib/question.sh
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- lib/capture.sh sources → this
- lib/checkpoint.sh sources → this
- lib/handover.sh sources → this
- lib/session.sh sources → this
rust_bin module
- lib/capture.sh sources → this
- lib/common.sh sources → this
- lib/context.sh sources → this
- lib/derive.sh sources → this
- lib/doctor.sh sources → this
- lib/gates.sh sources → this
- lib/intent_binding.sh sources → this
- lib/knowledge.sh sources → this
- lib/recover.sh sources → this
- lib/skills.sh sources → this
local/state/mcp/ensure.log artifact
- lib/capture.sh writes → this
- lib/common.sh writes → this
checkpoint module
record compact progress inside the active task
- sources → lib/derive.sh
- sources → lib/handover.sh
- uses → .ai/local/state/checkpoints
- writes → .ai/local/state/current.yaml
- bin/majordomus sources → this
- lib/capture.sh sources → this
handover module
write an append-only continuation record (body on stdin)
- sources → lib/derive.sh
- sources → lib/intent_binding.sh
- uses → .ai/local/state/handovers
- writes → .ai/local/state/current.yaml
- bin/majordomus sources → this
- lib/capture.sh sources → this
- lib/checkpoint.sh sources → this
- lib/context.sh sources → this
- lib/finish.sh sources → this
- lib/prompt.sh sources → this
- lib/start.sh sources → this
- lib/watch.sh sources → this
repo/policy.yaml artifact
- lib/common.sh reads → this
- lib/init.sh reads → this
- lib/capture.sh uses → this
- lib/context_docs.sh uses → this
- lib/doctor.sh uses → this
- lib/knowledge.sh uses → this
- lib/migrate.sh uses → this
- lib/update.sh uses → this
changed module
- reads → .ai/repo/scope.yaml
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- lib/check.sh sources → this
- lib/common.sh sources → this
- lib/knowledge.sh sources → this
- lib/session.sh sources → this
repo/scope.yaml artifact
- lib/changed.sh reads → this
- lib/doctor.sh reads → this
- lib/init.sh reads → this
- lib/migrate.sh uses → this
local/state/checkpoints artifact
- lib/doctor.sh reads → this
- lib/finish.sh reads → this
- lib/changed.sh uses → this
- lib/check.sh uses → this
- lib/checkpoint.sh uses → this
- lib/context.sh uses → this
- lib/derive.sh uses → this
- lib/init.sh uses → this
- lib/migrate.sh uses → this
- lib/prompt.sh uses → this
- lib/recover.sh uses → this
- lib/search.sh uses → this
- lib/update.sh uses → this
- lib/watch.sh uses → this
local/state/handovers artifact
- lib/doctor.sh reads → this
- lib/changed.sh uses → this
- lib/context.sh uses → this
- lib/derive.sh uses → this
- lib/finish.sh uses → this
- lib/handover.sh uses → this
- lib/prompt.sh uses → this
- lib/search.sh uses → this
- lib/start.sh uses → this
- lib/update.sh uses → this
- lib/watch.sh uses → this
- lib/init.sh writes → this
- lib/migrate.sh writes → this
check module
is the current task consistent with policy, scope, state?
- sources → lib/changed.sh
- sources → lib/commands.sh
- sources → lib/decision.sh
- sources → lib/doctrine.sh
- sources → lib/evidence.sh
- sources → lib/gates.sh
- sources → lib/knowledge.sh
- sources → lib/question.sh
- sources → lib/start.sh
- sources → lib/usecase.sh
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/decisions.md
- uses → .ai/local/state/ledger.jsonl
- uses → .ai/local/state/open-questions.md
- writes → .ai/local/state/current.yaml
- bin/majordomus sources → this
- lib/doctor.sh sources → this
- lib/finish.sh sources → this
- lib/start.sh sources → this
- lib/watch.sh sources → this
doctrine module
what rules are enforced, by what, and whether they are wired
- sources → lib/rules.sh
- bin/majordomus sources → this
- lib/check.sh sources → this
- lib/doctor.sh sources → this
local/state/current.yaml artifact
- lib/derive.sh reads → this
- lib/knowledge.sh reads → this
- lib/check.sh writes → this
- lib/checkpoint.sh writes → this
- lib/common.sh writes → this
- lib/finish.sh writes → this
- lib/handover.sh writes → this
- lib/start.sh writes → this
local/state/open-questions.md artifact
- lib/context.sh reads → this
- lib/init.sh reads → this
- lib/migrate.sh reads → this
- lib/prompt.sh reads → this
- lib/check.sh uses → this
- lib/doctor.sh uses → this
- lib/question.sh uses → this
- lib/search.sh uses → this
local/state/ledger.jsonl artifact
- lib/context.sh reads → this
- lib/derive.sh reads → this
- lib/doctor.sh reads → this
- lib/evidence.sh reads → this
- lib/recover.sh reads → this
- lib/session.sh reads → this
- lib/check.sh uses → this
- lib/search.sh uses → this
- lib/watch.sh uses → this
- lib/common.sh writes → this
- lib/history.sh writes → this
local/state/decisions.md artifact
- lib/context.sh reads → this
- lib/derive.sh reads → this
- lib/init.sh reads → this
- lib/migrate.sh reads → this
- lib/prompt.sh reads → this
- lib/check.sh uses → this
- lib/decision.sh uses → this
- lib/finish.sh uses → this
- lib/knowledge.sh uses → this
- lib/search.sh uses → this
start module
begin a scoped task under a profile
- sources → lib/check.sh
- sources → lib/context_docs.sh
- sources → lib/handover.sh
- sources → lib/intent_binding.sh
- uses → .ai/local/state/handovers
- writes → .ai/local/state/archive
- writes → .ai/local/state/current.yaml
- bin/majordomus sources → this
- lib/check.sh sources → this
question module
open, resolve and list questions that block acceptance
- uses → .ai/local/state/open-questions.md
- bin/majordomus sources → this
- lib/check.sh sources → this
- lib/derive.sh sources → this
- lib/doctor.sh sources → this
- lib/watch.sh sources → this
decision module
record or read durable decisions
- uses → .ai/local/state/decisions.md
- bin/majordomus sources → this
- lib/check.sh sources → this
- lib/context.sh sources → this
- lib/derive.sh sources → this
- lib/doctor.sh sources → this
- lib/knowledge.sh sources → this
- lib/prompt.sh sources → this
- lib/watch.sh sources → this
usecase module
the executable use cases: list, show, validate, run, coverage, impact, scaffold
- sources → lib/capture.sh
- sources → lib/commands.sh
- sources → lib/evidence.sh
- sources → lib/rules.sh
- writes → .ai/local/cache/use-cases
- writes → .ai/local/evidence/live
- writes → .ai/local/evidence/use-cases
- bin/majordomus sources → this
- lib/check.sh sources → this
- lib/doctor.sh sources → this
evidence module
record that one obligation the task declared has been discharged
- reads → .ai/local/state/ledger.jsonl
- sources → lib/gates.sh
- bin/majordomus sources → this
- lib/check.sh sources → this
- lib/usecase.sh sources → this
gates module
- sources → lib/rust_bin.sh
- lib/check.sh sources → this
- lib/evidence.sh sources → this
repo/providers artifact
- lib/common.sh reads → this
- lib/doctor.sh uses → this
- lib/migrate.sh uses → this
- lib/update.sh uses → this
manifest.yaml artifact
- lib/common.sh reads → this
local/cache/flat artifact
- lib/common.sh writes → this
local/state/session-current.yaml artifact
- lib/common.sh uses → this
- lib/recover.sh uses → this
- lib/session.sh uses → this
intent_binding module
- sources → lib/rust_bin.sh
- lib/context.sh sources → this
- lib/handover.sh sources → this
- lib/plan.sh sources → this
- lib/start.sh sources → this
history module
read the append-only ledger back
- writes → .ai/local/state/ledger.jsonl
- bin/majordomus sources → this
- lib/context.sh sources → this
prompt module
list, show and render repository-local prompt assets
- reads → .ai/local/state/decisions.md
- reads → .ai/local/state/open-questions.md
- sources → lib/context.sh
- sources → lib/decision.sh
- sources → lib/handover.sh
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- bin/majordomus sources → this
- lib/context.sh sources → this
- lib/doctor.sh sources → this
- lib/watch.sh sources → this
context_docs module
- uses → .ai/repo/policy.yaml
- lib/context.sh sources → this
- lib/start.sh sources → this
repo/project/issues artifact
- lib/context.sh reads → this
- lib/plan.sh uses → this
- lib/project.sh uses → this
deployment module
- lib/doctor.sh sources → this
doctor module
governance only: is every declared enforcement wired here?
- reads → .ai/README.md
- reads → .ai/local/state/checkpoints
- reads → .ai/local/state/handovers
- reads → .ai/local/state/ledger.jsonl
- reads → .ai/local/state/sessions-open
- reads → .ai/repo/scope.yaml
- sources → lib/adr.sh
- sources → lib/capture.sh
- sources → lib/check.sh
- sources → lib/commands.sh
- sources → lib/context.sh
- sources → lib/decision.sh
- sources → lib/deployment.sh
- sources → lib/doctrine.sh
- sources → lib/project.sh
- sources → lib/prompt.sh
- sources → lib/question.sh
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- sources → lib/skills.sh
- sources → lib/update.sh
- sources → lib/usecase.sh
- uses → .ai/local/state/open-questions.md
- uses → .ai/repo/policy.yaml
- uses → .ai/repo/providers
- uses → .ai/repo/rules/vendor
- bin/majordomus sources → this
- lib/watch.sh sources → this
skills module
the repository's skills: list, show and check them
- reads → .ai/repo/skills
- sources → lib/knowledge.sh
- sources → lib/rust_bin.sh
- bin/majordomus sources → this
- lib/doctor.sh sources → this
project module
- reads → .ai/repo/project/project.yaml
- uses → .ai/repo/project/issues
- writes → .ai/repo/project/milestones
- lib/doctor.sh sources → this
- lib/plan.sh sources → this
- lib/session.sh sources → this
update module
regenerate provider projections from policy
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- uses → .ai/repo/policy.yaml
- uses → .ai/repo/providers
- writes → .ai/local/prompts
- bin/majordomus sources → this
- lib/doctor.sh sources → this
README.md artifact
- lib/doctor.sh reads → this
- lib/init.sh uses → this
repo/rules/vendor artifact
- lib/init.sh reads → this
- lib/migrate.sh reads → this
- lib/rules.sh reads → this
- lib/doctor.sh uses → this
finish module
evaluate the finish contract; refuse if unmet
- reads → .ai/local/state/checkpoints
- sources → lib/check.sh
- sources → lib/handover.sh
- uses → .ai/local/state/decisions.md
- uses → .ai/local/state/handovers
- writes → .ai/local/state/completed
- writes → .ai/local/state/current.yaml
- bin/majordomus sources → this
local/state/completed artifact
- lib/knowledge.sh uses → this
- lib/recover.sh uses → this
- lib/finish.sh writes → this
init module
create the .ai/ layer in this repository (refuses to overwrite)
- reads → .ai/local/state/decisions.md
- reads → .ai/local/state/open-questions.md
- reads → .ai/repo/policy.yaml
- reads → .ai/repo/rules/vendor
- reads → .ai/repo/scope.yaml
- sources → lib/rules.sh
- uses → .ai/README.md
- uses → .ai/local/session-contexts
- uses → .ai/local/state/checkpoints
- uses → .ai/repo/README.md
- uses → .ai/repo/applications
- uses → .ai/repo/deployments}
- uses → .ai/repo/features
- uses → .ai/repo/knowledge/candidates/README.md
- uses → .ai/repo/knowledge/curated/README.md
- uses → .ai/repo/mesh
- uses → .ai/repo/profiles/README.md
- uses → .ai/repo/project/README.md
- uses → .ai/repo/prompts/README.md
- uses → .ai/repo/rules/README.md
- uses → .ai/repo/rules/project/README.md
- uses → .ai/repo/sessions}
- uses → .ai/repo/skills
- uses → .ai/repo/use-cases
- uses → .ai/repo/why
- uses → .ai/repo/workflows
- writes → .ai/local/prompts
- writes → .ai/local/state/handovers
- bin/majordomus sources → this
- lib/migrate.sh sources → this
repo/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/profiles/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/prompts/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/rules/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/rules/project/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/knowledge/curated/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/knowledge/candidates/README.md artifact
- lib/init.sh uses → this
repo/workflows artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/skills artifact
- lib/skills.sh reads → this
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/use-cases artifact
- lib/init.sh uses → this
repo/applications artifact
- lib/init.sh uses → this
repo/why artifact
- lib/init.sh uses → this
repo/features artifact
- lib/init.sh uses → this
repo/sessions} artifact
- lib/init.sh uses → this
repo/deployments} artifact
- lib/init.sh uses → this
repo/project/README.md artifact
- lib/init.sh uses → this
- lib/migrate.sh uses → this
repo/mesh artifact
- lib/init.sh uses → this
local/prompts artifact
- lib/migrate.sh uses → this
- lib/init.sh writes → this
- lib/update.sh writes → this
repo/knowledge/sources.yaml artifact
- lib/knowledge.sh uses → this
machine_lock module
migrate module
move pre-.ai project data from .majordomus/ into .ai/ (explicit, backed up)
- reads → .ai/local/state/decisions.md
- reads → .ai/local/state/open-questions.md
- reads → .ai/repo/rules/vendor
- sources → lib/init.sh
- uses → .ai/local/prompts
- uses → .ai/local/session-contexts
- uses → .ai/local/state/checkpoints
- uses → .ai/repo/README.md
- uses → .ai/repo/knowledge/curated/README.md
- uses → .ai/repo/policy.yaml
- uses → .ai/repo/profiles/README.md
- uses → .ai/repo/project/README.md
- uses → .ai/repo/prompts/README.md
- uses → .ai/repo/providers
- uses → .ai/repo/rules/README.md
- uses → .ai/repo/rules/project/README.md
- uses → .ai/repo/scope.yaml
- uses → .ai/repo/sessions/README.md
- uses → .ai/repo/skills
- uses → .ai/repo/templates/README.md
- uses → .ai/repo/workflows
- writes → .ai/local/state/handovers
- bin/majordomus sources → this
repo/sessions/README.md artifact
- lib/migrate.sh uses → this
repo/templates/README.md artifact
- lib/migrate.sh uses → this
plan module
the milestone and issue model: validate, read, and move an issue
- sources → lib/intent_binding.sh
- sources → lib/project.sh
- uses → .ai/repo/project/issues
- writes → .ai/repo/project/milestones
- bin/majordomus sources → this
repo/project/milestones artifact
- lib/plan.sh writes → this
- lib/project.sh writes → this
repo/project/project.yaml artifact
- lib/project.sh reads → this
recover module
bring this checkout's record stores back to what the contract describes
- reads → .ai/local/state/ledger.jsonl
- sources → lib/rust_bin.sh
- sources → lib/session.sh
- uses → .ai/local/state/archive
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/completed
- uses → .ai/local/state/session-current.yaml
- uses → .ai/local/state/sessions-open
- bin/majordomus sources → this
local/state/archive artifact
- lib/recover.sh uses → this
- lib/start.sh writes → this
search module
find durable records without reading all of them
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/decisions.md
- uses → .ai/local/state/handovers
- uses → .ai/local/state/ledger.jsonl
- uses → .ai/local/state/open-questions.md
- bin/majordomus sources → this
session_context module
- sources → lib/context.sh
- lib/session.sh sources → this
local/state/sessions artifact
- lib/session.sh uses → this
local/state/locks/outbox-drain artifact
- lib/session.sh uses → this
local/state/locks/session-pointer artifact
- lib/session.sh uses → this
sha256 module
local/evidence/use-cases artifact
- lib/usecase.sh writes → this
local/cache/use-cases artifact
- lib/usecase.sh writes → this
local/evidence/live artifact
- lib/usecase.sh writes → this
watch module
what has drifted: state, policy, projections, retention
- sources → lib/check.sh
- sources → lib/context.sh
- sources → lib/decision.sh
- sources → lib/doctor.sh
- sources → lib/handover.sh
- sources → lib/prompt.sh
- sources → lib/question.sh
- uses → .ai/local/state/checkpoints
- uses → .ai/local/state/handovers
- uses → .ai/local/state/ledger.jsonl
- bin/majordomus sources → this

42modules

51state files

23write paths

Every number above is counted from the scan at build time. The scanner is scripts/lib/architecture-scan.awk; the data it produced for this build is architecture.json.