# Register Limitation

> Register a known gap in the limitation register — file the issue in the private tracker, write the LIMITATION(registre#n) marker, or ledger a dark-launched feature. Use when the register gates fail, or when you are about to document why something is incomplete.

- Skill: `jfarcand/register-limitation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jfarcand/register-limitation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jfarcand/register-limitation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jfarcand (https://skillmd.com/u/jfarcand)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jfarcand/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](https://github.com/dravr-ai/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`.

```bash
grep tracker registre.toml
```

| | |
|---|---|
| Tracker | whatever `registre.toml` says |
| Labels | `limitation` + this repo's name (`iphone-mirroir-mcp`) |
| Title | `[mirroir-mcp] <short statement of the gap>` — always project-prefixed |

**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

```bash
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:

```rust
// 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`):

```yaml
  - 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

```bash
./.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.