Register Limitation

Register a Limitation

When this fires

Any of these, without exception:

• The register gates failed — "unregistered deferral/confession prose", "malformed LIMITATION marker", a file over the 500-line cap, or an inline clippy allow outside the declared list.
• You are about to write a comment explaining why something is incomplete, restricted, or deferred.
• You are shipping a feature disarmed (flag off, shadow mode, log-only phase).
• You found a gap while reading code and are not fixing it in this change.

The gates are the Apache-2.0 llm-registre tool, vendored as the .registre submodule and run by Tier 1 of runner/scripts/ci/pre-push-validate.sh and by CI (limitation-register.yml).

Step 0 — try to not need this

The register exists so honest gaps become tracked obligations, not so gaps become easy to ship. If you can implement the real thing now, do that instead. Registering is the fallback, and it costs a permanent entry someone has to close later. (A file over the cap or a stray inline allow is never registered — extract the helper or fix the lint.)

Where issues go

Read registre.toml at the repo root — its tracker key names this repo's register. Never assume; registers are per project. For mirroir that is jfarcand/mirroir-carnet.

grep tracker registre.toml

Never file on the code repo itself. It is PUBLIC, and a limitation issue states precisely where a capability or defence is incomplete — a roadmap when the code is open. Issue bodies may hold reasoning and residual risk; the code comment stays thin.

Step 1 — file the issue

TRACKER=$(sed -n 's/^tracker[[:space:]]*=[[:space:]]*"\(.*\)"/\1/p' registre.toml)

gh issue create -R "$TRACKER" \
  --title "[mirroir-mcp] Short statement of the gap" \
  --label limitation --label iphone-mirroir-mcp \
  --body "Where it is (file + symbol). What is incomplete. What the correct fix looks like."

Step 2 — write the marker

On the comment line that names the limited item:

// LIMITATION(registre#1): device-only step kinds (launch, home, shake,
// reset_app, set_network, measure, condition) have no replay dispatch arm.

Rules that make a marker valid rather than decorative:

• The literal is registre#<number> — the bare word, never the tracker repo name. The tracker is configuration (registre.toml); the marker never changes when it moves.
• Name the limited item on the marker line (the symbol, variant, or tool). A marker that says only "this is incomplete" is unsearchable.
• The marker exempts its own line from the prose ban, not the file. A second unmarked deferral sentence on the next line still fails.

Step 3 — if the feature ships disarmed, ledger it too

Add to feature-phases.yaml (fixed shape — the review workflow parses it with awk):

  - name: kebab-case-feature-name
    surface: Sources/mirroir-mcp/TheFlag.swift
    current: what ships today, i.e. the disarmed state
    advance_when: the criterion that arms the next phase
    review_by: 2026-09-30

The weekly "Monitor: Feature Phase Review" workflow opens a feature-phase issue in the tracker once review_by passes, so phase 1 cannot silently become forever. Keep values free of ": " and " #".

Step 4 — verify

./.registre/limitation-gates.sh Sources runner/src npm scripts website/src

Expect all five gates green. Tier 1 of runner/scripts/ci/pre-push-validate.sh runs the same command before every push.

Closing an entry

Fix the gap, delete the marker in the same change, close the issue. A stale marker still exempts prose from the gates, so exhausted markers are debt of their own.

What the register does not cover

These gates are per-change: they stop new debt at authoring time and cannot reach the standing stock of defects that live between diffs — a handler nothing reaches, an override nothing reads, two components each locally correct and jointly wrong. Those come out of periodic adversarial cold-reads and get filed here like anything else. A green gate means no new unregistered debt, not a clean codebase.