Find an object of the layer without reading everything

setup: active-task-records
given:
  - 'an active task that has already produced a checkpoint, a decision and an open question'
steps:
  - id: search
    run: ['search', 'parser']
    note: 'durable records matched literally, across kinds, without an index'
    expect:
      exit: 0
      stdout_contains: ['^decision ', 'parser', 'match']
  - id: nodes
    run: ['knowledge', 'nodes', '--kind', 'rule']
    note: 'one node per canonical object of one kind, with its identity'
    expect:
      exit: 0
      stdout_contains: ['^rule ']
  - id: prompts
    run: ['prompt', 'list']
    note: 'the repository’s own prompt assets, the ones an MCP client can also read as resources'
    expect:
      exit: 0
      stdout_contains: ['^continue ', '^debug ']
then:
  - 'the shell and the MCP server answer from the same files'
  - 'a majordomus:// URI resolves the same way through the resource read, the tool and the HTTP route'
  - 'no index has to exist for the literal search to work'

The scenario

Executed against the real tool, in a repository prepared by active-task-records, every time this site is generated. What follows is not a description of what should happen; it is what happened.

What the tool did

Evidence of the run this page was generated from: pass, 3 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

1. 1$ majordomus search parser exit 0

   durable records matched literally, across kinds, without an index

   checkpoint  .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md:16  the parser now refuses tabs
   decision    .ai/local/state/decisions.md:13  ## <date> — refuse tabs in the parser
   history     .ai/local/state/ledger.jsonl:4  {"ts":"<time>","event":"decision.recorded","head":"<sha>","branch":"mai
   search: 3 match(es)

   • exit 0
   • stdout_contains /^decision /
   • stdout_contains /parser/
   • stdout_contains /match/
2. 2$ majordomus knowledge nodes --kind rule exit 0

   one node per canonical object of one kind, with its identity

   rule        shared      8513b44dfe15  rule:majordomus.adr-integrity                        Architecture decision integrity
   rule        shared      1c35b4925c67  rule:majordomus.ai-layout-integrity                  AI layer integrity
   rule        shared      6b737b2767d6  rule:majordomus.blocker-resolution                   Blocker resolution
   rule        shared      d6a33fc1b28c  rule:majordomus.bootstrap-integrity                  Bootstrap integrity
   rule        shared      f8137aa6fcd4  rule:majordomus.candidates-reviewed                  Candidates are reviewed
   rule        shared      826525b6e3a9  rule:majordomus.catalogue-integrity                  Catalogue integrity
   rule        shared      a56642f78cc5  rule:majordomus.checkpoint-freshness                 Checkpoint freshness
   rule        shared      78f8269d371d  rule:majordomus.command-coverage                     Every public command is exercised and refuted
   rule        shared      e468040ac890  rule:majordomus.command-surface                      The command surface is declared and reconciled
   rule        shared      adf88f652092  rule:majordomus.completion-gates                     Completion is gated
   rule        shared      523fbb99c024  rule:majordomus.context-budget                       Context budget
   rule        shared      018f8d63e837  rule:majordomus.context-integrity                    Context integrity
   rule        shared      f5336d1b0b06  rule:majordomus.dag-integrity                        Dependency graph integrity
   rule        shared      d804fedbbf1a  rule:majordomus.decision-records                     Decision records
   rule        shared      072a8155ad66  rule:majordomus.decision-threshold                   The decision threshold
   rule        shared      a843319fda37  rule:majordomus.define-done-first                    Define done before executing
   rule        shared      78db07930224  rule:majordomus.deployment-contract                  A deployment is described once, and every artifact built from it is generated from it
   rule        shared      87de78333726  rule:majordomus.depth-is-not-verbosity               Execution depth is not output verbosity
   rule        shared      2033490a50b9  rule:majordomus.doctrine-wiring-integrity            Doctrine wiring integrity
   rule        shared      afc294593532  rule:majordomus.enforcement-wiring                   Enforcement wiring
   rule        shared      c02aa47f226c  rule:majordomus.externalise-decisions                Externalise decisions and durable state
   rule        shared      db680840291e  rule:majordomus.handover-integrity                   Handover integrity
   rule        shared      c7307cc9d919  rule:majordomus.handovers-carry-state                Handovers transfer state, not transcripts
   rule        shared      5eae52cc5589  rule:majordomus.isolated-parallelism                 Parallel work requires isolation
   rule        shared      7fa1a1c5c27e  rule:majordomus.justified-escalation                 Escalate capability and effort only when justified
   rule        shared      3427bfc92e29  rule:majordomus.knowledge-graph                      Knowledge graph integrity
   rule        shared      eec2b2184f6c  rule:majordomus.knowledge-integrity                  Knowledge integrity
   rule        shared      33fc8bac42c8  rule:majordomus.knowledge-observed                   Knowledge observation
   rule        shared      ebe4eb49d09c  rule:majordomus.layout-integrity                     Layout integrity
   rule        shared      d3c88435f42d  rule:majordomus.ledger-integrity                     Ledger integrity
   rule        shared      628f11b96703  rule:majordomus.lifecycle-observed                   Lifecycle observation
   rule        shared      cbd041431c84  rule:majordomus.minimum-sufficient-context           Load minimum sufficient context
   rule        shared      d1bb01668123  rule:majordomus.note-integrity                       Note integrity
   rule        shared      88f7f9322b00  rule:majordomus.obligation-closure                   Obligation closure
   rule        shared      fb8aff3c3984  rule:majordomus.one-worker-one-scope                 One worker, one clear scope
   rule        shared      51e122071249  rule:majordomus.policy-completeness                  Policy completeness
   rule        shared      ae11a7b983a5  rule:majordomus.policy-integrity                     Policy integrity
   rule        shared      abbd45d5b53e  rule:majordomus.profile-requirements                 Profile requirements
   rule        shared      f2fd82b09aaa  rule:majordomus.project-integrity                    Project model integrity
   rule        shared      bc3eadf4f9f5  rule:majordomus.projection-integrity                 Projection integrity
   rule        shared      6a768205d5ed  rule:majordomus.prompt-capture                       Prompt capture is proven, or reported unavailable
   rule        shared      5d4230b7c618  rule:majordomus.prompt-continuity                    A prompt record carries its own identity, is bounded, and is private
   rule        shared      c820246fbdc1  rule:majordomus.prompt-integrity                     Prompt integrity
   rule        shared      9b68dbd49ac6  rule:majordomus.publication-currency                 A session does not finish behind its own published site
   rule        shared      58fca43f73a9  rule:majordomus.questions-store-integrity            Questions store integrity
   rule        shared      4043b457e438  rule:majordomus.record-changed-files                 A record's changed_files names the work, not the tool's exhaust
   rule        shared      6ac34a128a32  rule:majordomus.retention-caps                       Retention caps
   rule        shared      959aad5152d0  rule:majordomus.roadmap-integrity                    The roadmap is a projection, never a document
   rule        shared      e254bad15ecd  rule:majordomus.rule-package-integrity               Rule package integrity
   rule        shared      d73fb1b2f702  rule:majordomus.schema-integrity                     Every object has a schema, and the rules resolve in one stated order
   rule        shared      5bae41c80fda  rule:majordomus.scope-integrity                      Scope integrity
   rule        shared      2e5b9f5ad9c7  rule:majordomus.session-lifecycle                    The episode boundary is drawn below the model, and its working context is local
   rule        shared      8f779c44c5c2  rule:majordomus.session-records                      Session records are shared objects with a closed field set
   rule        shared      84f5b9f70992  rule:majordomus.sessions-are-workers                 Sessions are workers, not memory
   rule        shared      5beb962c3c18  rule:majordomus.skill-integrity                      Skill integrity
   rule        shared      70a6e878886b  rule:majordomus.state-consistency                    State consistency
   rule        shared      7e381d15f9f3  rule:majordomus.task-continuity                      Task continuity
   rule        shared      2a25cd588cea  rule:majordomus.task-on-the-mesh                     A task on a repository whose mesh is enabled works on the mesh
   rule        shared      1955176df430  rule:majordomus.use-case-coverage                    Use-case coverage
   rule        shared      1a2e830a8912  rule:majordomus.verification-integrity               Verification integrity
   rule        shared      1b01d93b42fa  rule:majordomus.verify-outcomes                      Verify outcomes, not activity
   knowledge nodes: 61 in scope all, kind rule
   INFO knowledge   . — the schema check was not asked for (MAJORDOMUS_KNOWLEDGE_SCHEMA=unasked), so no file was checked against the schema of its kind

   • exit 0
   • stdout_contains /^rule /
3. 3$ majordomus prompt list exit 0

   the repository’s own prompt assets, the ones an MCP client can also read as resources

   continue               resume a task from durable state instead of from someone's memory
   debug                  frame a defect so that the fix is proven, not asserted
   handover               produce a continuation record body for the current task
   review                 review the working diff against the claimed scope and the finish contract

   • exit 0
   • stdout_contains /^continue /
   • stdout_contains /^debug /

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

• majordomus searchFind a durable record without reading all of them, in authority order.
• majordomus knowledgeThe compiled index over what this repository states, and the candidate records it derives from what an episode did.
• majordomus promptList, show and render the repository's own prompt assets, substituting known tokens only.

Over MCP the same layer is reached through majordomus_search, majordomus_get, majordomus_list (the MCP surface).

The rules that make it hold

• ✕blocking AI layer integrityThe repository's AI layer is real: the manifest declares a format this executable reads and every section it names exists, the checkout-local half is ignored by git and nothing under it is tracked, and no project data remains under the pre-.ai .majordomus/ path.
• ✕blocking Prompt integrityEvery repository-local prompt asset renders, and every token in it is one the renderer knows.

Guarantees exercised

• ○guaranteed Every repository-local prompt asset renders, and an unknown token is a failure
• ○guaranteed Durable records are searchable literally, across kinds, without an index
• ○guaranteed The Rust executable serves the repository's AI layer to an MCP client over stdio, with protocol frames alone on stdout
• ○guaranteed A majordomus:// URI resolves the same way through the MCP resource read, the majordomus_get tool and the HTTP object route, and majordomus://repository answers repository.info as a JSON document tagged builtin

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

• Serve the repository's AI layer to every AI client through one shared serverOpen the repository in any client the tool declares a provider for (docs/generated/providers.md) and have each of them read the same rules, prompts and knowledge over MCP from one process, seeing each other.
• Start a session from a rendered framing, not a pasted transcriptList the prompt assets the repository ships, render one against the durable state, and read the context it embeds.
• See what the repository holds, and run one of its capabilities, without reading a fileOpen the shared server in a browser and get the whole layer as pages: what exists, where each thing came from, what depends on what, what is failing, and a form that runs any capability.
• Decide what belongs in the AI context, as dataRead the repository’s declared scope policy, see which paths are in and out of the index, and let doctor and the knowledge index apply it rather than a hardcoded list.
• Extend what the executable serves by adding a file, never by rebuilding itAdd a rule, a prompt or a knowledge node to .ai/ and have it appear as an MCP resource, an HTTP route and a reference entry, with the same binary.

The moments this answers

• → asked what the workers did last night and had only transcripts to grep A conversation log records what was said, not what happened, so the operational question has to be answered by a person reading prose.
• → spent an hour discovering something the repository already knew, twice A worker learns something expensive about the codebase, uses it once, and it dies with the session because nothing turned it into a durable record.
• → watched a worker spend a day on an approach that had already been ruled out Negative results are the majority of experimental output and the part nobody records, so the search space is re-explored.