anchors escalate

Open the issue for a change needed in the plan or the spec.

You found out that the plan or the spec needs to change — by incoherence (the
text contradicts itself) or by GAP (the plan is coherent and did not cover something).

Whoever found it interprets the impact, and the interpretation chooses the exit:

  --for-user   you ASSERT that the change impacts the DIRECTION of the project.
                   There is more than one defensible answer, and choosing between
                   them changes what the product does. The issue is born with
                   'anchors:needs-user' and the claim does not hand over the card
                   while the decision has not come out.

  --unsure     you DO NOT KNOW whether it impacts. It is born just like
                   '--for-user', and the card says the first question is the
                   framing: if it does not impact, whoever reads it returns it to
                   the queue instead of deciding.

  (default)        it does not impact the direction. It becomes an ordinary card:
                   born in 'to-do', enters the queue, an agent takes it. It stops
                   nobody.

WHY TWO EXITS FOR WHAT STOPS THE CARD: whoever reads 30 open decisions needs to
know what each one asks for. "Decide between A and B" and "check whether this is
yours" are different jobs, and mixing them makes the second cost as much as the first.

HOW TO CHOOSE. The question is not "am I sure?" — it is "is there more than one
defensible answer, and does choosing between them change what the product DOES?".

  Impacts the direction          Does not impact
  ---------------------          ---------------
  which value the app offers     the rule is right and the gate that enforces it is missing
  whether the UI shows X or Y    the text contradicts itself and one of the sides is the right one
  what counts as proof           the waiver came out and the ruler did not come in
  changing something in production   the path written on the card is wrong

If the exit is "fix what is wrong" and nobody would defend the current state,
it is an ordinary card: there is no choice to make, only work.

  --bug        what is wrong is the PIPELINE or the TOOL, not the plan: a seeded
                   workflow computes the wrong thing, an 'anchors' command picks the
                   wrong card, a gate misreads a file. Nothing to decide — but the fix
                   lives where no agent in the queue edits ('.github/workflows/anchors-*',
                   Anchors itself), so it is born with 'anchors:bug' and the claim does
                   not hand it out. It is NOT a decision: do not use '--for-user' for it.
  --blocking   with '--bug': your card cannot go on until the bug is fixed. The card
                   waits for it ('anchors:blocked-by-<n>'); without it, the card goes on.
  --upstream   with '--bug', when what is wrong is ANCHORS ITSELF (a command, a gate, the
                   map, a file Anchors seeds) and not this project's configuration: it
                   is also reported at github.com/co2-lab/anchors, so the fix reaches
                   every project. An open issue with the same title gets a comment
                   instead of a second issue. That repository is PUBLIC: write the
                   reason in Anchors' terms — the command, the gate, a minimal case —
                   never this project's code, names or data; the report carries neither
                   '--about' nor the card. In local mode, it is the only thing done.

AND IF YOU DO NOT KNOW, use '--unsure' instead of '--for-user'. The cost of
escalating for safety does not show up for whoever escalates: each card in
'needs-user' waits for a person, and one person decides more slowly than N agents
escalate. Measured in a real project: 11 escalations in an hour, and a triage
concluded that the 23 open ones were SEVEN decisions. Saying "I do not know" is
more honest — and cheaper to read — than asserting an impact you did not measure.

Do not use it for what is trivial AND is in the file you are already editing: there,
fix it and record the revision ('{CODIGO}-R0001: what changed and why'). Opening a
card to change one word is bureaucracy.

Usage

anchors escalate <reason> [flags]

Flags

Flag	Default	What it does
--about		the plan or spec where the incoherence is
--blocking		with –bug: your card cannot go on until the bug is fixed, and it waits for it
--bug		the PIPELINE or the TOOL is wrong (a seeded workflow, an anchors command, a gate): not a decision
--card		card number where the need was discovered
--for-user		you ASSERT the change impacts the project’s DIRECTION: it becomes a decision and stops the card
--reviewing-pr		the PR you were reviewing: the card comes out of its Refs/Closes, without you searching
--root	.	project root
--unsure		you DO NOT KNOW whether it impacts the direction: it stops the card, and the first question is the framing
--upstream		with –bug: the bug is in Anchors itself — also report it at co2-lab/anchors (public: no project code, names or data)

The work queue — family

Commands of the same family — what tells each apart:

Command	What it does
anchors next	Pull and claim the next item from the queue (the worker calls this)
anchors queue	List live tasks (the work the watcher queued)
anchors work	Emit the work prompt of a stage (spec|code|feature|test|review) for a target
anchors done	Close claimed task(s) (moves to the .anchors/done/ history)
anchors drop	Discard a task from the queue without completing it (removes; does not archive)
anchors reclaim	Return to the queue the tasks stuck in claimed (dead worker)
anchors deliver	Record the delivery of a stage — the review trigger
anchors decided	Release the card escalate --for-user stopped, once the decision is made
anchors discard	Take off the board the card that no longer makes sense, without deleting it
anchors unblock	Open the work card that unblocks a card stuck in needs-user
anchors escalate	Open the issue for a change needed in the plan or the spec
anchors report-bug	Report a bug in Anchors itself at github.com/co2-lab/anchors
anchors synthesize	Two PRs conflicting in CONTENT become a synthesis card
anchors watch	The background watcher: sees changes and QUEUES work
anchors monitor	Watch the project’s long processes: one line when one starts, stalls, dies or ends
anchors flow	Operate the work flows (the puzzle of actions and results)
anchors board	The project board — published by the pipeline, or served live