@nac3/forge-cli 1.26.0 → 1.28.0

package/docs/doctrine/urazuke.md

@@ -1,221 +1,221 @@
-# Urazuke -- the evidence method, as Forge runs it
-
-Urazuke (github.com/pkuschnirof/urazuke) is the method behind every project
-Forge builds or maintains: 24 ordered steps in four stretches, each with an
-exact prompt, the inputs the owner prepares, the artifacts the agent leaves
-in the repository, and a completion check the owner does WITHOUT reading
-code. An existing system built without it goes through eight normalisation
-stations (N0..N7) first and enters the loop at step 5.
-
-## What is mechanical (not prose)
-
-- The project's workflow is `urazuke` (no code) or `urazuke-legacy` (code
-  without the method's artifacts). Every canonical task carries its step.
-- The CURRENT step's prompt is injected into your system prompt every turn,
-  with the state of its checks (section "URAZUKE -- peldano NN"). Act on
-  that prompt as if the owner had pasted it. Do not skip ahead.
-- A canonical task closes ONLY when `evaluateStep()` is GREEN: the files
-  the step names exist, are not stubs, say what they must; the sizing
-  record is admissible (G9); the plan items carry a spec; the evidence
-  receipts exist. `yujin.pending.close` refuses a red step. An override
-  needs the OWNER's written `force_reason` AND its `force_kind` (kept in
-  history, counted per motive -- see "A forced close carries a TYPE");
-  never pass either on your own initiative.
-- Evidence is a RECEIPT Forge records (command, ref, exit code, counts),
-  never your summary. "Tests pass" without a receipt is a claim.
-- A LONG run leaves its receipt the same way. `yujin.evidence.run` blocks
-  the turn only while the run fits the blocking window (10 min, lowered with
-  `limits.claude_cli_silence_ms`); over that, or with `background: true`, it
-  is launched detached and returns a HANDLE. That is not a degraded mode:
-  the receipt is written by whoever runs, not by whoever waits. Read it with
-  `yujin.evidence.list` when the task finishes (`yujin.task.status({id})`
-  for the progress). Do NOT relaunch a run that already has a handle.
-- And the corollary for any invocation that dies waiting: a verb call that
-  comes back UNANSWERED (E_VERB_CALL_UNANSWERED) did not necessarily fail.
-  Before redoing the work, LOOK FOR THE TRACE -- `yujin.evidence.list` for a
-  receipt, `yujin.task.list` for a task. Two closes were reported as
-  "believed" over a receipt that existed on disk the whole time.
-
-## When does a project EXPECT a ladder?
-
-Written here because the condition must be findable, not inferred from the
-source (the owner's condition on F-06, 2026-11-01): "if tomorrow a project
-should have a ladder and does not leave that trace, the notice does not
-come out and we are where we started. The condition has to be WRITTEN
-where someone would look for it."
-
-The switch being ON means **the method is available**, not **you are
-walking it**. It is ON by default in Forge developer, so injecting the
-step block -- or warning that it is missing -- in every project with the
-switch on would charge ~700 characters of system prompt per turn to
-everyone who does not use the method.
-
-So Forge warns ("enabled and NOT arriving") only when the project leaves a
-TRACE that it expects a ladder. Exactly three traces count, any one of
-them is enough (`expectsLadder` in `src/chat/urazuke_section.ts`):
-
-1. **A Urazuke workflow instance exists** for the project, open or closed
-   (`findUrazukeInstance`). This is the normal trace: `yf urazuke start` /
-   `yujin.urazuke.start` leaves it.
-2. **The frozen copy of the gate definition** is on disk
-   (`.forge/urazuke/gates.json`, PND-165): the project pinned a version of
-   the method, so it is using it.
-3. **The method's artifacts are in the repository**: all three of
-   `docs/WORKING_AGREEMENT.md`, `docs/SEMANTIC_TREE.md` and `docs/GATES.md`
-   exist and are not stubs (`hasMethodArtifacts` in
-   `src/urazuke/probes.ts`).
-
-With none of the three, the turn records `reason: 'not_in_use'` and stays
-silent. That reason is itself the trace: it is in the result of
-`buildUrazukeSection`, so "the notice did not come out" can always be
-answered with WHICH condition failed. If you want the ladder in a project
-that has none of the three, open it -- `yujin.urazuke.start` -- and the
-step prompt arrives on the next turn.
-
-## A forced close carries a TYPE, and the type is counted
-
-M-02, decided by the owner on 2026-11-01. A plan item ships only with its
-receipts, and some items have no red to produce at all (documentation,
-configuration). The answer is NOT a kind of pending that authorises
-itself -- nothing can guarantee a code item will not be declared
-"documentation" -- it is an honest forced close that is COUNTABLE:
-
-- `force_reason` (the owner's prose, min 15 chars) is still mandatory, and
-- `force_kind` is mandatory with it, from a CLOSED catalogue
-  (`src/urazuke/overrides.ts`; `yf pending close --force-kind`, or
-  `force_kind` on `yujin.pending.close`). A free-text type turns the
-  counter into a cloud of synonyms, which is not counting.
-
-The condition that makes this worth having, in the owner's words: "the
-typed motive has to be a NUMBER in the report. You have to be able to ask
-how many closes were forced by `documentacion_sin_rojo_posible` and get an
-answer. If the type exists and nobody counts it, it is the same hole with
-a better name -- and worse, because it sounds solved."
-
-So the override is stored as DATA on the item's history entry
-(`history[].override = {gate, kind, missing}`), and
-`docs/RETROSPECTIVE_<date>.md` prints one row per motive and one per gate
-bypassed. Overrides recorded before this change are still counted, in
-their own `sin tipo` row: discounting them would have made the total DROP
-on the day of the fix, which is the worst way to measure a debt.
-
-## The catalogue's file names are PROTOCOL
-
-Decided by the owner on 2026-11-01 (M-03, measured by the Urazuke
-experiment), as a rule of the contract and not as an error message:
-
-**The file names the step catalogue asks for are protocol and are NOT
-translated. The CONTENT goes in the project's language.**
-
-So a step that names `docs/ARCHITECTURE.md` is satisfied by a file at
-exactly that path, whose prose may be entirely in Spanish. A
-`docs/ARQUITECTURA.md` with the identical, correct content counts as
-ABSENT -- and the gate now says so, with that reason, every time an
-artifact is missing (`ARTIFACT_NAMES_ARE_PROTOCOL` in
-`src/urazuke/gate.ts`), whether or not a similar-looking neighbour is
-found next to it.
-
-Why not a per-language alias table, which was the other option: **an alias
-table is a second source of truth, and a second source of truth
-desynchronises** -- the defect this project already has on record three
-times. (Plus the price on the Forge side: 232 artifact names to maintain in
-two languages.) It is the same line the `language-sovereignty` doctrine
-draws for verb ids and code identifiers: translate the EXPERIENCE, never
-the protocol.
-
-What was unacceptable before this was never the requirement. It was the
-SILENCE: a file with the right content next to it, counted as absent, with
-no written reason.
-
-## The five statuses, and why `closed` is NOT `green`
-
-A step carries ONE of five statuses, and two of them are easy to confuse --
-the confusion cost a report that said 0 of 24 when three steps were closed
-(F-07, measured by the Urazuke experiment, 2026-11-01):
-
-| status       | meaning                                                      |
-|--------------|--------------------------------------------------------------|
-| `closed`     | the canonical task of this step IS CLOSED. Consolidated progress. The BEST state a step can be in. |
-| `green`      | the gate passes and the task is STILL OPEN: it CAN be closed, nobody closed it yet. |
-| `red`        | a check is missing. It does not close.                       |
-| `owner`      | nothing mechanical to check; the owner signs it.             |
-| `unmeasured` | the definition in force needs an evaluator this installation cannot measure. It does NOT close and it is NOT green. |
-
-The two rules that follow:
-
-1. **`closed` and `green` are disjoint.** A closed step is reported as
-   `closed`, never as `green`. So **counting `green` to measure progress
-   LOSES every closed step** -- the best ones. Progress is `closed + green`
-   (`done_or_ready`), and a summary prints BOTH numbers, never one.
-2. **Nobody counts statuses on their own.** `summarizeLadder()` in
-   `src/urazuke/current.ts` is the only counter; the verb, the CLI, the
-   retrospective and the cyclic report all read it. A second, independent
-   count is exactly the inference the method warns against: it is how the
-   distinction gets lost again, in one consumer, silently.
-
-## How to work inside it
-
-1. Read the URAZUKE section: red checks are what is missing. Produce the
-   artifact at the path named, with real content, or ask the owner for the
-   input that is theirs (`antes de enviar`). Never invent an owner input.
-2. When the section says GREEN, close the task with `yujin.pending.close`
-   (full expediente) and the next step's prompt arrives on the next turn.
-3. `yujin.urazuke.status` shows the whole ladder; `yujin.urazuke.step`
-   shows any step in full (prompts, inputs, artifacts, checklist).
-4. The plan is the pendings: each item needs `spec` (acceptance "given /
-   when / then" + `how_verified`) before it is implemented (step 5).
-5. No deadlines, ever: the method fixes the order and the gates, not the
-   calendar. Speed is a consequence, not the objective.
-
-## The profiles axis: three evaluators, and where their data lives
-
-Added 2026-11-01 (Pieza 6, D-044). The published definition requires these
-three on the three anchors of the construction loop, and until that day this
-installation could not measure any of them -- so adopting the published
-definition froze three permanently unmeasurable steps.
-
-| evaluator | step | what it measures |
-|---|---|---|
-| `pendings_profiles` | 5 | every open plan item that touches a screen declares its convergence group, the profiles that have it, and ONE acceptance criterion per profile |
-| `profile_matrix` | 8 | the matrix is consistent, the navigation is DERIVED from it, and each profile's e2e reaches exactly its row |
-| `manual_cases_per_profile` | 10 | every manual case ran once per affected profile, derived from the matrix |
-
-The data, and the one rule that explains every choice -- **the matrix is the
-producer**:
-
-- `docs/PROFILE_MATRIX.md` carries the four columns of Annex H B2 and
-  nothing else: functionality, home, profiles, entry point. The table is
-  found by HEADER, so the column order is free.
-- `.forge/profile-navigation.json` is the generated navigation, and it
-  declares a fingerprint. The evaluator **recomputes** that fingerprint from
-  the matrix and compares; it never reads the declared one and compares it
-  with itself, which would pass any file. The fingerprint is
-  self-describing (algorithm, encoding, canonical form, covers, excludes) --
-  one that cannot be reproduced from outside is not evidence.
-- `.forge/profile-reachability.json` lists, per profile, what the e2e
-  **reached** (not what it attempted) and the id of its receipt. The
-  evaluator contrasts that id against the receipt registry: an artifact
-  whose receipt the registry does not have is prose.
-- the two directions of "neither less nor more" fail DIFFERENTLY and never
-  merge into one red: reaching **less** than the row is a MISSING piece
-  (construction incomplete); reaching **more** is an AUTHORIZATION defect,
-  high severity by written definition. If the message does not name the
-  class, the reader under-rates it.
-- the per-profile pending fields live in `PendingSpec` **in the registry**,
-  not in `docs/PENDING.md` (owner's decision, 2026-11-01): a gate cannot
-  measure prose, `pendings_spec` already measures there, and two sources for
-  the same datum age in opposite directions. The document is generated from
-  the registry or cites it. Write them with
-  `yf pending add --touches-screen --convergence-group ... --row-profile ...
-  --accept-for perfil=criterio`.
-- `touches_screen` is a THREE-state field: absent means "not declared" and
-  the evaluator reports it as such -- never as "does not touch". Not looking
-  is not the same as nothing being there.
-- the manual case ledger carries `functionality` (the link the method's
-  "derived from the matrix" implies): `yf urazuke rules sign <rule> passed
-  --by <name> --profile <id> --functionality "<row>"`. A case with a single
-  profile does NOT count as executed when its row has more.
-
-To measure what adopting the published definition would cost BEFORE
-adopting it: `yf urazuke rules show --published` (read only, writes
-nothing, never blocks) and `yf urazuke gates pull`.
+# Urazuke -- the evidence method, as Forge runs it
+
+Urazuke (github.com/pkuschnirof/urazuke) is the method behind every project
+Forge builds or maintains: 24 ordered steps in four stretches, each with an
+exact prompt, the inputs the owner prepares, the artifacts the agent leaves
+in the repository, and a completion check the owner does WITHOUT reading
+code. An existing system built without it goes through eight normalisation
+stations (N0..N7) first and enters the loop at step 5.
+
+## What is mechanical (not prose)
+
+- The project's workflow is `urazuke` (no code) or `urazuke-legacy` (code
+  without the method's artifacts). Every canonical task carries its step.
+- The CURRENT step's prompt is injected into your system prompt every turn,
+  with the state of its checks (section "URAZUKE -- peldano NN"). Act on
+  that prompt as if the owner had pasted it. Do not skip ahead.
+- A canonical task closes ONLY when `evaluateStep()` is GREEN: the files
+  the step names exist, are not stubs, say what they must; the sizing
+  record is admissible (G9); the plan items carry a spec; the evidence
+  receipts exist. `yujin.pending.close` refuses a red step. An override
+  needs the OWNER's written `force_reason` AND its `force_kind` (kept in
+  history, counted per motive -- see "A forced close carries a TYPE");
+  never pass either on your own initiative.
+- Evidence is a RECEIPT Forge records (command, ref, exit code, counts),
+  never your summary. "Tests pass" without a receipt is a claim.
+- A LONG run leaves its receipt the same way. `yujin.evidence.run` blocks
+  the turn only while the run fits the blocking window (10 min, lowered with
+  `limits.claude_cli_silence_ms`); over that, or with `background: true`, it
+  is launched detached and returns a HANDLE. That is not a degraded mode:
+  the receipt is written by whoever runs, not by whoever waits. Read it with
+  `yujin.evidence.list` when the task finishes (`yujin.task.status({id})`
+  for the progress). Do NOT relaunch a run that already has a handle.
+- And the corollary for any invocation that dies waiting: a verb call that
+  comes back UNANSWERED (E_VERB_CALL_UNANSWERED) did not necessarily fail.
+  Before redoing the work, LOOK FOR THE TRACE -- `yujin.evidence.list` for a
+  receipt, `yujin.task.list` for a task. Two closes were reported as
+  "believed" over a receipt that existed on disk the whole time.
+
+## When does a project EXPECT a ladder?
+
+Written here because the condition must be findable, not inferred from the
+source (the owner's condition on F-06, 2026-11-01): "if tomorrow a project
+should have a ladder and does not leave that trace, the notice does not
+come out and we are where we started. The condition has to be WRITTEN
+where someone would look for it."
+
+The switch being ON means **the method is available**, not **you are
+walking it**. It is ON by default in Forge developer, so injecting the
+step block -- or warning that it is missing -- in every project with the
+switch on would charge ~700 characters of system prompt per turn to
+everyone who does not use the method.
+
+So Forge warns ("enabled and NOT arriving") only when the project leaves a
+TRACE that it expects a ladder. Exactly three traces count, any one of
+them is enough (`expectsLadder` in `src/chat/urazuke_section.ts`):
+
+1. **A Urazuke workflow instance exists** for the project, open or closed
+   (`findUrazukeInstance`). This is the normal trace: `yf urazuke start` /
+   `yujin.urazuke.start` leaves it.
+2. **The frozen copy of the gate definition** is on disk
+   (`.forge/urazuke/gates.json`, PND-165): the project pinned a version of
+   the method, so it is using it.
+3. **The method's artifacts are in the repository**: all three of
+   `docs/WORKING_AGREEMENT.md`, `docs/SEMANTIC_TREE.md` and `docs/GATES.md`
+   exist and are not stubs (`hasMethodArtifacts` in
+   `src/urazuke/probes.ts`).
+
+With none of the three, the turn records `reason: 'not_in_use'` and stays
+silent. That reason is itself the trace: it is in the result of
+`buildUrazukeSection`, so "the notice did not come out" can always be
+answered with WHICH condition failed. If you want the ladder in a project
+that has none of the three, open it -- `yujin.urazuke.start` -- and the
+step prompt arrives on the next turn.
+
+## A forced close carries a TYPE, and the type is counted
+
+M-02, decided by the owner on 2026-11-01. A plan item ships only with its
+receipts, and some items have no red to produce at all (documentation,
+configuration). The answer is NOT a kind of pending that authorises
+itself -- nothing can guarantee a code item will not be declared
+"documentation" -- it is an honest forced close that is COUNTABLE:
+
+- `force_reason` (the owner's prose, min 15 chars) is still mandatory, and
+- `force_kind` is mandatory with it, from a CLOSED catalogue
+  (`src/urazuke/overrides.ts`; `yf pending close --force-kind`, or
+  `force_kind` on `yujin.pending.close`). A free-text type turns the
+  counter into a cloud of synonyms, which is not counting.
+
+The condition that makes this worth having, in the owner's words: "the
+typed motive has to be a NUMBER in the report. You have to be able to ask
+how many closes were forced by `documentacion_sin_rojo_posible` and get an
+answer. If the type exists and nobody counts it, it is the same hole with
+a better name -- and worse, because it sounds solved."
+
+So the override is stored as DATA on the item's history entry
+(`history[].override = {gate, kind, missing}`), and
+`docs/RETROSPECTIVE_<date>.md` prints one row per motive and one per gate
+bypassed. Overrides recorded before this change are still counted, in
+their own `sin tipo` row: discounting them would have made the total DROP
+on the day of the fix, which is the worst way to measure a debt.
+
+## The catalogue's file names are PROTOCOL
+
+Decided by the owner on 2026-11-01 (M-03, measured by the Urazuke
+experiment), as a rule of the contract and not as an error message:
+
+**The file names the step catalogue asks for are protocol and are NOT
+translated. The CONTENT goes in the project's language.**
+
+So a step that names `docs/ARCHITECTURE.md` is satisfied by a file at
+exactly that path, whose prose may be entirely in Spanish. A
+`docs/ARQUITECTURA.md` with the identical, correct content counts as
+ABSENT -- and the gate now says so, with that reason, every time an
+artifact is missing (`ARTIFACT_NAMES_ARE_PROTOCOL` in
+`src/urazuke/gate.ts`), whether or not a similar-looking neighbour is
+found next to it.
+
+Why not a per-language alias table, which was the other option: **an alias
+table is a second source of truth, and a second source of truth
+desynchronises** -- the defect this project already has on record three
+times. (Plus the price on the Forge side: 232 artifact names to maintain in
+two languages.) It is the same line the `language-sovereignty` doctrine
+draws for verb ids and code identifiers: translate the EXPERIENCE, never
+the protocol.
+
+What was unacceptable before this was never the requirement. It was the
+SILENCE: a file with the right content next to it, counted as absent, with
+no written reason.
+
+## The five statuses, and why `closed` is NOT `green`
+
+A step carries ONE of five statuses, and two of them are easy to confuse --
+the confusion cost a report that said 0 of 24 when three steps were closed
+(F-07, measured by the Urazuke experiment, 2026-11-01):
+
+| status       | meaning                                                      |
+|--------------|--------------------------------------------------------------|
+| `closed`     | the canonical task of this step IS CLOSED. Consolidated progress. The BEST state a step can be in. |
+| `green`      | the gate passes and the task is STILL OPEN: it CAN be closed, nobody closed it yet. |
+| `red`        | a check is missing. It does not close.                       |
+| `owner`      | nothing mechanical to check; the owner signs it.             |
+| `unmeasured` | the definition in force needs an evaluator this installation cannot measure. It does NOT close and it is NOT green. |
+
+The two rules that follow:
+
+1. **`closed` and `green` are disjoint.** A closed step is reported as
+   `closed`, never as `green`. So **counting `green` to measure progress
+   LOSES every closed step** -- the best ones. Progress is `closed + green`
+   (`done_or_ready`), and a summary prints BOTH numbers, never one.
+2. **Nobody counts statuses on their own.** `summarizeLadder()` in
+   `src/urazuke/current.ts` is the only counter; the verb, the CLI, the
+   retrospective and the cyclic report all read it. A second, independent
+   count is exactly the inference the method warns against: it is how the
+   distinction gets lost again, in one consumer, silently.
+
+## How to work inside it
+
+1. Read the URAZUKE section: red checks are what is missing. Produce the
+   artifact at the path named, with real content, or ask the owner for the
+   input that is theirs (`antes de enviar`). Never invent an owner input.
+2. When the section says GREEN, close the task with `yujin.pending.close`
+   (full expediente) and the next step's prompt arrives on the next turn.
+3. `yujin.urazuke.status` shows the whole ladder; `yujin.urazuke.step`
+   shows any step in full (prompts, inputs, artifacts, checklist).
+4. The plan is the pendings: each item needs `spec` (acceptance "given /
+   when / then" + `how_verified`) before it is implemented (step 5).
+5. No deadlines, ever: the method fixes the order and the gates, not the
+   calendar. Speed is a consequence, not the objective.
+
+## The profiles axis: three evaluators, and where their data lives
+
+Added 2026-11-01 (Pieza 6, D-044). The published definition requires these
+three on the three anchors of the construction loop, and until that day this
+installation could not measure any of them -- so adopting the published
+definition froze three permanently unmeasurable steps.
+
+| evaluator | step | what it measures |
+|---|---|---|
+| `pendings_profiles` | 5 | every open plan item that touches a screen declares its convergence group, the profiles that have it, and ONE acceptance criterion per profile |
+| `profile_matrix` | 8 | the matrix is consistent, the navigation is DERIVED from it, and each profile's e2e reaches exactly its row |
+| `manual_cases_per_profile` | 10 | every manual case ran once per affected profile, derived from the matrix |
+
+The data, and the one rule that explains every choice -- **the matrix is the
+producer**:
+
+- `docs/PROFILE_MATRIX.md` carries the four columns of Annex H B2 and
+  nothing else: functionality, home, profiles, entry point. The table is
+  found by HEADER, so the column order is free.
+- `.forge/profile-navigation.json` is the generated navigation, and it
+  declares a fingerprint. The evaluator **recomputes** that fingerprint from
+  the matrix and compares; it never reads the declared one and compares it
+  with itself, which would pass any file. The fingerprint is
+  self-describing (algorithm, encoding, canonical form, covers, excludes) --
+  one that cannot be reproduced from outside is not evidence.
+- `.forge/profile-reachability.json` lists, per profile, what the e2e
+  **reached** (not what it attempted) and the id of its receipt. The
+  evaluator contrasts that id against the receipt registry: an artifact
+  whose receipt the registry does not have is prose.
+- the two directions of "neither less nor more" fail DIFFERENTLY and never
+  merge into one red: reaching **less** than the row is a MISSING piece
+  (construction incomplete); reaching **more** is an AUTHORIZATION defect,
+  high severity by written definition. If the message does not name the
+  class, the reader under-rates it.
+- the per-profile pending fields live in `PendingSpec` **in the registry**,
+  not in `docs/PENDING.md` (owner's decision, 2026-11-01): a gate cannot
+  measure prose, `pendings_spec` already measures there, and two sources for
+  the same datum age in opposite directions. The document is generated from
+  the registry or cites it. Write them with
+  `yf pending add --touches-screen --convergence-group ... --row-profile ...
+  --accept-for perfil=criterio`.
+- `touches_screen` is a THREE-state field: absent means "not declared" and
+  the evaluator reports it as such -- never as "does not touch". Not looking
+  is not the same as nothing being there.
+- the manual case ledger carries `functionality` (the link the method's
+  "derived from the matrix" implies): `yf urazuke rules sign <rule> passed
+  --by <name> --profile <id> --functionality "<row>"`. A case with a single
+  profile does NOT count as executed when its row has more.
+
+To measure what adopting the published definition would cost BEFORE
+adopting it: `yf urazuke rules show --published` (read only, writes
+nothing, never blocks) and `yf urazuke gates pull`.