Adopt a repository that already has its own rules

Install the supervisory layer into a repository with a hand-written CLAUDE.md, without the tool taking ownership of a file somebody else wrote.

described Getting started and adoptionbasicmaintainerwrites state

Situation

The repository already has a governance root — a CLAUDE.md, an AGENTS.md, a contributing guide people actually follow. A tool that regenerates that file wholesale would overwrite months of authored judgement, so the usual answer is to not adopt the tool at all.

What you run

init: writes .ai/ and refuses if an installation is already there
update: renders the projection into the region between the markers, leaving the rest of the file alone
doctor: proves the projection matches its own stamp and the declared enforcement is actually invoked

Scenario

setup: authored-governance
given:
  - 'a hand-written CLAUDE.md people follow, committed'
  - 'Majordomus installed, the policy projecting CLAUDE.md in region mode'
  - 'the two enforcements wired as git hooks'
steps:
  - id: refuse-overwrite
    run: ['init']
    note: 'a second init never overwrites a layer that is there'
    expect:
      exit: 15
      stdout_contains: ['already exists']
  - id: render-the-region
    run: ['update']
    note: 'the generated region is appended inside the authored file and stamped; the authored text is untouched'
    expect:
      exit: 0
      stdout_contains: ['^create CLAUDE.md$']
      files_contain:
        - path: CLAUDE.md
          pattern: 'Hand-written governance'
        - path: CLAUDE.md
          pattern: '^<!-- majordomus:begin [0-9a-f]{12} [0-9a-f]{16} -->$'
  - id: prove-it-holds
    run: ['doctor']
    note: 'the projection matches its stamp and the declared enforcement is invoked by the hooks'
    expect:
      exit: 0
      stdout_contains: ['^OK   projection', 'doctor: 0 failure']
then:
  - 'the authored text is byte for byte what it was'
  - 'the region carries the policy hash and its own content hash'
  - 'doctor is green because the hooks exist and call the tool'

Outcome

The authored text stays authoritative and the generated section sits inside it, stamped like any other projection. An edit outside the markers is never drift; an edit inside them is caught.

No scenario yet

This use case is described, not proved: it names its commands and rules, and nothing executes it. It cannot be more than described until a scenario is added.

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.

The rules that make it hold

Guarantees exercised

Related use cases

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