Directory contracts

Directories in the tree

35

Carrying a contract

27

Exempt, by their governing contract

8

The tree

Each row is a directory of .ai. A directory carries its own contract, or the contract that governs its subtree exempts it — instances of a kind, such as a skill and its examples, owe no contract of their own. What applies to a path is majordomus context resolve <path>; this page is the shape that resolution walks.

• .ai/ .aisubtree final

  ai.layer — Repository AI context

  The protocol of the layer: what it holds, who owns which half, how it is discovered, and what outranks what.

• repo/ .ai/reposubtree extend

  ai.repo — Tracked repository context

  The tracked half of the layer and what each section under it is for.

• adrs/ .ai/repo/adrssubtree extend

  ai.repo.adrs — Architecture decisions

  Accepted, durable decisions about how this repository is built.

• applications/ .ai/repo/applicationssubtree extend

  ai.repo.applications — Applications

  The contexts the tool suits, when each fits and when it does not, composed from use cases.

• benchmarks/ .ai/repo/benchmarkssubtree extend

  ai.repo.benchmarks — Benchmarks

  The recorded baselines a performance claim is compared against, one directory per measured surface.

• pages/ .ai/repo/benchmarks/pagessubtree extend

  ai.repo.benchmarks.pages — Publication baselines

  What publishing the site cost on a named platform, kept as the comparison for the next run.

  tracks scripts/pages

• rust/ .ai/repo/benchmarks/rustsubtree extend

  ai.repo.benchmarks.rust — Executable baselines

  Per-platform baselines for the Rust executable's commands, with the policy that decides a regression.

  tracks apps/majordomus-cli/src/bench, scripts/rust-check

• ci/ .ai/repo/cisubtree extend

  ai.repo.ci — Continuous integration

  The gates this repository runs, which changed paths select them, and what publication may spend.

  tracks scripts/ci-plan, scripts/pages, .github/workflows/validate.yml

• deployments/ .ai/repo/deploymentssubtree extend

  ai.repo.deployments — Deployments

  One canonical object per deployment of this repository's executable; every container and provider artifact is generated from it and none of them is authoritative.

  tracks share/schemas/majordomus/deployment/deployment.v1.schema.json, share/kinds.yaml

• features/ .ai/repo/featuressubtree extend

  ai.repo.features — Product features

  What the product does for a person, one feature per file, each made of things the other registries already own; every surface that presents a feature is derived from these files.

  tracks apps/majordomus-cli/src/product.rs, apps/majordomus-cli/src/capability/builtin/product.rs, site/templates/index.html, site/templates/feature.html, site/templates/features-section.html

• knowledge/ .ai/repo/knowledgesubtree extend

  ai.repo.knowledge — Knowledge

  How repository knowledge is declared and discovered, never collected.

  tracks lib/knowledge.sh, share/knowledge-sources.yaml

• curated/ .ai/repo/knowledge/curatedsubtree extend

  ai.repo.knowledge.curated — Curated notes

  What this repository chose to write about itself, discovered as a knowledge source class.

• profiles/ .ai/repo/profilessubtree extend

  ai.repo.profiles — Profiles

  How much context, effort and ceremony a task gets, declared per working mode.

  tracks lib/common.sh, share/allow/profile.txt

• project/ .ai/repo/projectsubtree extend

  ai.repo.project — Project model

  Milestones as outcomes, issues as execution contracts, and a dependency graph that decides what is next.

  tracks lib/project.sh, lib/project.awk, share/allow/project.txt

• issues/ .ai/repo/project/issuessubtree extend

  ai.repo.project.issues — Issues

  Execution contracts: one bounded change each, with its scope, its dependencies and the evidence it must leave.

  tracks share/allow/issue.txt

• milestones/ .ai/repo/project/milestonessubtree extend

  ai.repo.project.milestones — Milestones

  One outcome each, written as the problem it ends and the state that proves it ended.

  tracks share/allow/milestone.txt

• prompts/ .ai/repo/promptssubtree extend

  ai.repo.prompts — Prompt assets

  The provider-neutral prompts the tool renders, with the tokens it fills in.

  tracks lib/prompt.sh, share/allow/prompt.txt

• providers/ .ai/repo/providerssubtree extend

  ai.repo.providers — Provider templates

  The one source each provider bootstrap is rendered from; the files at the root are output.

  tracks lib/update.sh, .ai/repo/policy.yaml

• releases/ .ai/repo/releasessubtree extend

  ai.repo.releases — Published releases

  One record per published release, written by the release pipeline and read by every projection of the public release metadata.

• rules/ .ai/repo/rulessubtree extendchildren required

  ai.repo.rules — Repository rules

  The rule object format, where rules live, how they are loaded and composed.

  tracks lib/rules.sh, lib/doctrine.sh, share/standard/majordomus, share/allow/rule.txt

• project/ .ai/repo/rules/projectsubtree extend

  ai.repo.rules.project — Project rules

  The rules this repository wrote for itself, one file each, resolved with the vendored baseline.

• sessions/ .ai/repo/sessionssubtree extend

  ai.repo.sessions — Session records

  One immutable record per closed execution episode, derived from git and the ledger and shared with every surface.

  tracks lib/session.sh, share/schemas/majordomus/session-record/session-record.v1.schema.json

• skills/ .ai/repo/skillssubtree extendchildren exempt

  ai.repo.skills — Skills

  Reusable provider-neutral operational procedures, loaded only when the task is about them.

• deploy-site/ .ai/repo/skills/deploy-site

  No contract of its own; .ai/repo/skills/README.md exempts the directories below it.

• implement/ .ai/repo/skills/implement

  No contract of its own; .ai/repo/skills/README.md exempts the directories below it.

• examples/ .ai/repo/skills/implement/examples

  No contract of its own; .ai/repo/skills/README.md exempts the directories below it.

• repo-review/ .ai/repo/skills/repo-review

  No contract of its own; .ai/repo/skills/README.md exempts the directories below it.

• examples/ .ai/repo/skills/repo-review/examples

  No contract of its own; .ai/repo/skills/README.md exempts the directories below it.

• use-cases/ .ai/repo/use-casessubtree extend

  ai.repo.use-cases — Use cases

  The tasks people perform with the tool, each one a file with the commands, rules and claims it names and the scenario section that proves it.

• why/ .ai/repo/whysubtree extendchildren exempt

  ai.repo.why — Why this tool exists

  The operational moments this tool answers, the audiences that recognise them and the areas they fall under, each one a file that every projection is derived from.

  tracks site/templates/why-section.html, site/templates/why.html

• areas/ .ai/repo/why/areas

  No contract of its own; .ai/repo/why/README.md exempts the directories below it.

• audiences/ .ai/repo/why/audiences

  No contract of its own; .ai/repo/why/README.md exempts the directories below it.

• moments/ .ai/repo/why/moments

  No contract of its own; .ai/repo/why/README.md exempts the directories below it.

• workflows/ .ai/repo/workflowssubtree extend

  ai.repo.workflows — Workflows

  The multi-step processes a worker follows here, and when each applies.

  tracks lib/start.sh, lib/check.sh, lib/finish.sh, lib/handover.sh, lib/plan.sh

• workspaces/ .ai/repo/workspacessubtree extend

  ai.repo.workspaces — External workspaces

  One declaration per external workspace this repository is authorised to read; the content it names is this checkout's state and is never here.

  tracks share/schemas/majordomus/workspace/workspace.v1.schema.json, share/kinds.yaml

How a chain is composed

The effective context for a path is every applicable document from the root down to it, least specific first, ordered by depth, then the declared order, then the path. A subtree document applies to its directory and everything below; a directory document to its own directory alone; an explicit one to the directories it lists. extend appends, replace names the ancestors it stands in for, and final may not be superseded by anything below it.