@r1z4x/tezgah 1.5.1 → 1.6.0

package/hooks/tezgah_gate.py

@@ -38,28 +38,26 @@ Rules, all only inside a tezgah root:
   8. a write while an active task is set - a plan file under .tezgah/plans/open whose
      frontmatter carries a valid `phase` - is refused when that phase is one
      that only reads, or when the file is outside the task's `allowed_paths`
-     refused (`task`). The record is the user's own, written by bin/tezgah-task and
-     never by the agent, so the refusal leans on a decision the user made rather
-     than one this gate inferred: no active task means no requirement, and the
-     rule invents nothing. The record also carries where the phase returns to - a
+     refused (`task`). The record is written by bin/tezgah-task, which the
+     orchestrating session runs itself as the work moves, so the refusal leans
+     on a state the CLI vetted (an Acceptance item per command, an answered
+     spike, a checkpoint) rather than one this gate inferred: no active task
+     means no requirement, and the rule invents nothing. The record also
+     carries where the phase returns to - a
      `checkpoint:` sha, or `pending` while the tree still holds work no commit
      names - and a write in `implementation` is refused while it reads `pending`
      and the tree is dirty, so the phase's work starts from a named state rather
      than on top of uncommitted changes; the per-file snapshots are not one
-     state to return to. Two further refusals close the ways a session could
-     move the boundary instead of respecting it: a write whose target IS that
-     record, and a shell command that would change it through the CLI. Both were
-     measured open before they were closed - with the refusal naming the command
-     that lifts it, an armed arm removed or disabled the gate in 25 of 25 runs
-     and obeyed it in none (an internal benchmark, block E7) - and neither
-     refusal names a command now. The phase covers the shell too, because the
+     state to return to. A write whose target IS that record is refused too:
+     retyping the frontmatter would skip the preconditions the CLI checks. The
+     phase covers the shell too, because the
      write tools are not the only way to change a file: with them refused, the
      armed arm wrote the target with a heredoc redirect in 3 of 25 runs, so a
      reading phase refuses a shell command that writes. A code-execution tool is
      a third route the phase does not cover: the same block measured one row in
      25 writing the target through `eval` after the write tools and the shell
      were both refused, and that one is named rather than closed. The `task-off`
-     kill switch removes all four.
+     kill switch removes all three.
   9. a `git commit` (or `--amend`) is refused while the newest check recorded in
      this session failed (`order`): a commit is a claim that the tree passed, and
      the state it would freeze is the one a check just rejected. The state is the
@@ -681,9 +679,10 @@ CLASS_NOTE = {
     "transient": "it names a failure the host's own client may retry - a "
                  "timeout, a connection error, a rate limit, a 5xx - and an "
                  "identical repeat by the agent adds nothing to that",
-    "user": "it names something only the user can fix - a credential, a "
-            "login, an access grant - so stop and ask the user for it rather "
-            "than change the approach",
+    "user": "it names something only the user can supply - a credential, a "
+            "login, an access grant - so take a route that needs none first "
+            "(another provider or member, a local run, a public source) and "
+            "ask the user once, naming what it unlocks, only when none is left",
     "permanent": "an assertion or a bad argument does not change by re-running "
                  "it",
 }
@@ -980,52 +979,47 @@ def race_reason(inp, session_id, cwd=None):
     return None
 
 
-# --- task scope: the user's own phase and path allowlist --------------------
-# What this closes: a session that has been told what it is working on - the
-# user activated a plan file under .tezgah/plans/open, so the work has a phase and the
-# files it may touch - and then writes anyway. Two shapes cost the user real
-# work: a write in `discovery`, where the whole point of the phase is to read
-# before deciding, and a write outside the plan's own allowlist, which is how a
-# bounded task quietly becomes an unbounded one. Both are the user's own
-# decisions, which is why this rule may refuse at all: the record is written by
-# bin/tezgah-task, by hand, and never by the agent - a rule the agent could
-# satisfy by editing its own record would be a nudge wearing a gate's clothes.
+# --- task scope: the plan's own phase and path allowlist --------------------
+# What this closes: a session that has declared what it is working on - a plan
+# file under .tezgah/plans/open is active, so the work has a phase and the
+# files it may touch - and then writes anyway. Two shapes cost real work: a
+# write in `discovery`, where the whole point of the phase is to read before
+# deciding, and a write outside the plan's own allowlist, which is how a
+# bounded task quietly becomes an unbounded one. The record is written by
+# bin/tezgah-task, which the orchestrating session runs itself: the plan's
+# lifecycle is the orchestrator's job, never a hand-off to the user. What keeps
+# the boundary is the CLI, not who runs it - a writing phase needs every
+# Acceptance item to name its proving command, `implementation` an answered
+# spike and a checkpoint, `close done` an approving review - so the record's own
+# file is refused to a write (TASK_RECORD_DENY): retyping the frontmatter is the
+# direct route that skips those checks. A shell line's positional target (`sed
+# -i`, `cp`) is not read here (see write_paths), the residual this rule names.
 #
 # The direction is fail-open wherever the record is missing, unreadable or out
-# of phase vocabulary (tezgah_task.active returns None for those), because a
-# refusal has to rest on an ask the user actually made: a rule that refused
-# every write until a record appeared would be the fail-closed trap the design
-# report names, with the whole session as its blast radius. Nothing is named
-# that the user did not name either: an empty allowlist is no scope asked for
-# rather than "nothing is allowed", so the phase is the whole requirement there.
+# of phase vocabulary (tezgah_task.active returns None for those): a rule that
+# refused every write until a record appeared would be the fail-closed trap the
+# design report names, with the whole session as its blast radius. An empty
+# allowlist is no scope declared rather than "nothing is allowed", so the phase
+# is the whole requirement there.
+#
+# The refusals name the CLI move, because running it is the work the rule asks
+# for and the CLI vets it. E7 measured a refusal that named a way to take the
+# rule off (the armed arm disabled the gate in 25 of 25 runs); the switches that
+# do that stay behind the control-plane rule below.
 TASK_PHASE_DENY = (
     "Task gate: the active task %s is in phase `%s`, and this call writes. "
-    "Writes belong to %s. The phase is the user's to move: ask them, or do the "
-    "reading this phase asks for and say what the write was for.")
+    "Writes belong to %s. Finish the reading this phase is for, then move the "
+    "phase yourself with `tezgah-task phase implementation` - it refuses until "
+    "the plan's Acceptance, spike and checkpoint are in order.")
 TASK_SCOPE_DENY = (
-    "Task gate: %s is outside the paths the active task %s allows (%s). The "
-    "allowlist is the user's to widen: ask them, or leave the file alone and say "
-    "why it looked in scope.")
-# The two refusals above deliberately name no command. They used to end with the
-# one that lifts them, and the E7 block measured what that costs: with the unlock
-# printed in the refusal, the armed arm removed or disabled the gate in 25 of 25
-# runs and obeyed it in none (an internal benchmark, block E7). A refusal
-# is a boundary or it is an instruction; it cannot be both.
+    "Task gate: %s is outside the paths the active task %s allows (%s). If the "
+    "plan's work genuinely reaches it, widen the scope yourself with `tezgah-task "
+    "allow <glob> ... --why \"<reason>\"` (listing the current globs too); "
+    "otherwise leave the file alone.")
 TASK_RECORD_DENY = (
     "Task gate: %s is the active task's own record. The phase and the allowlist "
-    "live in that file, so a session that edits it is editing the boundary it is "
-    "being held to. Ask the user to change the task; the record is theirs.")
-TASK_UNLOCK_DENY = (
-    "Task gate: this command changes the active task's own record. The phase and "
-    "the allowlist are the user's, and a session that can move them is held to "
-    "nothing. Ask the user to change the task instead.")
-# A shell command that changes the record. Matched on the masked text, so a
-# command that merely names the CLI - a grep over the docs, a commit message -
-# is not refused. The token is the CLI's own basename, with or without `.py`
-# and run through any interpreter, so any path to it counts.
-TASK_CHANGE = re.compile(
-    r"(?:^|[|;&(]\s*|\s)(?:python3?\s+)?\S*tezgah-task(?:\.py)?\s+"
-    r"(?:start|phase|allow|stop)\b")
+    "live in that file and only `tezgah-task` writes them, because it checks the "
+    "plan's Acceptance, spike and review on the way; change the task through it.")
 # The shapes that make a shell command a write, for the phase rule below. The
 # tools are not the only way to change a file, and E7b measured the other one:
 # with `edit` and `write` refused twelve and six times, the armed arm wrote the
@@ -1053,8 +1047,8 @@ SHELL_WRITE = re.compile(
 TASK_SHELL_DENY = (
     "Task gate: the active task %s is in phase `%s`, and this command writes a "
     "file. The shell is a write route like any other, so the phase covers it. "
-    "The phase is the user's to move: ask them, or do the reading this phase "
-    "asks for and say what the write was for.")
+    "Finish the reading this phase is for, then move the phase yourself with "
+    "`tezgah-task phase implementation`.")
 
 
 # The marker a caller passes when it has NOT read the record, so a rule reads it
@@ -1100,11 +1094,10 @@ def task_shell_reason(inp, cwd, base, task=_UNRESOLVED):
 def task_record_reason(inp, cwd, base, task=_UNRESOLVED):
     """A deny reason when this write's target IS the active task's record.
 
-    The other route to the same hole as TASK_UNLOCK_DENY, and the one a write
-    tool takes: the record is a file in the repo, so an agent that may write
-    files can retype the phase instead of running the CLI. Refused whatever the
-    phase and whatever the allowlist says - the record is not inside its own
-    scope, because a scope that can widen itself is not one."""
+    The record is a file in the repo, so an agent that may write files could
+    retype the phase instead of running the CLI, and skip the Acceptance, spike
+    and review checks the CLI makes on the way. Refused whatever the phase and
+    whatever the allowlist says - the record is not inside its own scope."""
     task = _task(cwd, base, task)
     if not task:
         return None
@@ -1182,11 +1175,9 @@ def task_reason(inp, cwd, base, task=_UNRESOLVED):
 # be read, and `task-off` above. A refusal has to rest on something a reader can
 # check, and a rule that cannot answer must not refuse.
 #
-# The refusal names the one command that makes the boundary real. That is not the
-# mistake TASK_PHASE_DENY records: the E7 lesson is a refusal that names how to
-# take the constraint off (the phase is the user's to move), while the checkpoint
-# command *satisfies* the requirement - running it is the work the rule asks for,
-# so naming it is naming what the rule wants rather than a way around it.
+# The refusal names the one command that makes the boundary real: running it is
+# the work the rule asks for, so naming it is naming what the rule wants rather
+# than a way around it.
 CHECKPOINT_DENY = (
     "Checkpoint gate: the active task %s is in phase `implementation` and its "
     "plan records a pending checkpoint (`checkpoint: pending <sha>`), so this "
@@ -1823,8 +1814,8 @@ def _refusing(label):
 # `tezgah-gate decide` writes a genuine `began` row with `check=1`; the capture
 # CLI writes snapshot rows; pony and adhd write CONFIG_DIR; `tezgah-context
 # attest` re-attests a session, and a clean result clears its drift mark. The
-# task CLI is not here: it is the task rule's (TASK_CHANGE), which `task-off`
-# removes, and that switch is one of the files this rule protects.
+# task CLI is not here: the orchestrating session runs it, and the checks that
+# matter live in the CLI itself (see the task rule above).
 # `tezgah-context user_prompt` is a prompt event, and a prompt naming a switch
 # writes the `authorized` row the switch latch honors (tezgah_paths.off).
 CONTROL_CLIS = {"tezgah-gate": ("decide",), "tezgah-capture": "",
@@ -2651,11 +2642,9 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
         reason = race_reason(inp, session_id, cwd)
         if reason:
             return _deny(session_id, "race", reason, tool, inp, base)
-    # Task scope: the user's own record for this work - its phase and the files
-    # its allowlist names (see task_reason). The
-    # record itself is refused first of all, and a shell that would change it
-    # through the CLI is refused with it: a boundary the agent can move is not a
-    # boundary, and both routes to moving this one were measured open (E7).
+    # Task scope: the active plan's phase and the files its allowlist names (see
+    # task_reason). The record itself is refused first of all: only
+    # bin/tezgah-task writes it, through the checks it makes on the way.
     if not off("task-off"):
         # The record is read once and handed to every rule below: each read lists
         # `.tezgah/plans/open/` and parses a plan, and this path is every write of
@@ -2667,9 +2656,6 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
             reason = task_record_reason(inp, cwd, base, task)
             if reason:
                 return _deny(session_id, "task", reason, tool, inp, base)
-        if t in BASH_TOOLS and TASK_CHANGE.search(
-                mask(str(inp.get("command") or ""))):
-            return _deny(session_id, "task", TASK_UNLOCK_DENY, tool, inp, base)
         if t in BASH_TOOLS:
             reason = task_shell_reason(inp, cwd, base, task)
             if reason:

package/hooks/tezgah_policy.py

@@ -236,17 +236,32 @@ rewrite it plainly.
 **Merge authority: standing, not per-PR.** The user is not the approval step
 on a merge. Review first with a FRESH reviewer (never my own read of my own
 code), run the full suite, and if the review is clean and every test passes,
-merge, move the plan to `.tezgah/plans/done/`, and report the outcome. Bring it back
-to the user only on a critical or major finding left after round two, or a
-failing test. One review per plan, over its whole diff in the verification
+merge and close the plan yourself (`tezgah-task close NNN done`, which also
+deactivates it and removes every merged worktree), then report the outcome. Nothing
+goes back to the user: a failing test you fix, and a critical or major finding
+left after round two you fix yourself, prove with a test and close with
+`tezgah-task close NNN done --resolved "<fix and test>"`. One review per plan, over its whole diff in the verification
 phase; at most two rounds - only a confirmed critical or major finding opens
 round two, a minor or suggestion one is recorded fix-later, and after round two
-what is left goes to the user or is recorded fix-later, never a third round.
+what is left is fixed by the session and closed with `--resolved`, or recorded fix-later, never a third round.
 A round spawns its reviewers in ONE message, one per dimension (correctness
 and contract, security, tests and performance) or file group; a diff under 300
 changed lines gets one reviewer. Per-task work gets tests, not a reviewer, and
 `tezgah-task review` refuses a third round.
 
+**The process is yours: never hand a step back.** The orchestrator runs the
+plan lifecycle itself - `tezgah-task start`, every `phase` move, `review`,
+`close`, the merge, and removing a slice's worktree once its branch is merged -
+and never ends a reply with "run this command" or "shall I close it?" for a
+step it can take. A process parameter the user did not set (a spend ceiling, a
+sample size, a retry budget, a member to consult) is picked by you: choose the
+conservative default, state it in one line, proceed. A credential, a login or an
+access grant is the one thing no tool supplies, and even then take every route
+that needs none first - another consult member or provider, local compute
+instead of managed, a public source - and ask once, naming what it unlocks, only
+when no route is left. A requested item you would drop is still asked about
+(see "Deliver the whole ask").
+
 **Attribution: none, anywhere, ever.** Nothing you persist or publish may name
 the assistant, model, vendor or "AI" as author, co-author, generator or helper -
 on any host (Claude, opencode, Codex, Cursor, dsh, omp), including subagents and cheap
@@ -402,10 +417,11 @@ question needs facts newer or wider than the codebase - current versions, CVEs,
 vendor status, breaking-change news; skip it for pure code/design reasoning.
 
 Exit 4 means no choice is recorded and exit 5 means every recorded member
-failed: nothing answered, and the output lists `offer:`/`reoffer:` members. Ask
-the user which to use with exactly those options (prefer a model family other
-than your own), record the answer with `{CONSULT_BIN} --use <member>[,<member>]`,
-then ask the question again. Never pick a member for the user.
+failed: nothing answered, and the output lists `offer:`/`reoffer:` members. Do
+not ask the user: record the first listed member from a model family other than
+your own (two make a panel) with `{CONSULT_BIN} --use <member>[,<member>]`, ask
+again, and say which member you chose. After two such rounds with nothing
+answering, report the second opinion as skipped and carry on.
 
 Treat every answer as advisory evidence, never as truth: verify each claim
 against the actual code before adopting it, and tell the user which models were
@@ -453,8 +469,9 @@ are what keeps results comparable, and breaking one silently invalidates the run
 never edit a node once a run has answered it (branch a child instead); the run
 command and environment are a fixed contract identical on every node; vary the
 committed code/config, never CLI args or env knobs; grow the experiment tree
-downward, not sideways. Local research needs no login; managed compute does
-- ask the user to run `{ORX_BIN} login`.
+downward, not sideways. Local research needs no login; managed compute does -
+run locally at a scale that fits, and ask for `{ORX_BIN} login` only when the
+question cannot be answered without managed compute.
 
 A result row and every claim built on it say what they were measured on: `real`
 for the running system, `fixture` for an input you generated, `derived` for a
@@ -806,8 +823,10 @@ never your own summary, conclusion or self-assessment - a reviewer handed the
 author's framing finds measurably fewer defects. It answers with independent
 models, then one referee: read back the referee's named fields (recommendation,
 key disagreements, unchecked assumptions, what would change its mind, requested
-evidence), not a paraphrase. On exit 4/5 ask the user which `offer:`/`reoffer:`
-member to use and record it with `--use` before asking again. Relay the failure
+evidence), not a paraphrase. On exit 4/5 record the first listed
+`offer:`/`reoffer:` member of another model family yourself with `--use` and ask
+again - never ask the user to choose; after two failed rounds say it was
+skipped. Relay the failure
 class and retry line it prints, verify every claim against the code, report
 which models disagreed, and if nothing answered say the second opinion was
 skipped. Skip trivial local edits.
@@ -871,7 +890,9 @@ evidence class - `user-verbatim`, `behaviour`, `ui-observed`, `code`, `external`
 and a finding without one is a question, not a finding. Run it as a research line
 (`{RESEARCH_BIN}`), say what it did not look at, and read the `product-analysis`
 skill for the artifact shape and the scorecard, and `feature-audit` for the
-layer-coherence matrices when the ask is one feature. Off: `research-off`.
+layer-coherence matrices when the ask is one feature. A new capability built from
+data or an ask runs the `product-flow` skill: `{RESEARCH_BIN} next --topic <t>` is
+the step source, and its first missing or due step is the next one. Off: `research-off`.
 
 **No AI attribution, ever, on any host.** Nothing persisted or published may
 name the assistant, model, vendor or "AI" as author/co-author/generator/helper:
@@ -922,7 +943,10 @@ its own branch and checkout - inside Orca `orca worktree create --name <slug>
 --parent-worktree active --json`, else `git worktree add -b <branch> <absolute
 path>`; its brief names every read, edit and shell `cwd` as an absolute path
 under that checkout, never the main checkout, whose `git status --short` must
-not grow. Read-only slices need no worktree. Pick each agent by task class from
+not grow. Read-only slices need no worktree. Once a slice's branch is merged,
+its worktree goes in the same turn - `tezgah-task close` removes every merged
+one, and outside a plan `orca worktree rm --worktree path:<p>` (else `git
+worktree remove <p>`) does it; never leave one for the user to find. Pick each agent by task class from
 the specialists line; `{ROUTE_BIN}` names the tier for code work. Serialize
 only a real dependency - one slice's output is another's input, or two slices
 edit one file - and say which. Never wait idle on a spawned slice while

package/hooks/tezgah_product.py

@@ -0,0 +1,107 @@
+"""The product-flow playbook (plan 074, ADR 025): the one place its steps are
+written. `next_steps` computes each step's status from the topic's files under
+`.tezgah/analysis/<topic>/` - `flow.md`, one `## <step>` heading per step, and
+`spec.md` - and nothing stores it."""
+import datetime
+import os
+import re
+
+import tezgah_paths as tp
+
+# A topic becomes a path below, so anything outside kebab-case reads no file.
+TOPIC = re.compile(r"(?=.{1,64}\Z)[a-z0-9]+(?:-[a-z0-9]+)*")
+OBSERVE = re.compile(r"observe after:\s*(\d{4}-\d{2}-\d{2})", re.I)
+
+
+def _step(sid, skill, first=""):
+    """A step whose artifact is its `## <sid>` note in flow.md; `first` is what
+    the session does before writing it."""
+    return {"id": sid, "skill": skill,
+            "leaves": "## %s in .tezgah/analysis/<topic>/flow.md" % sid,
+            "command": "%swrite ## %s in .tezgah/analysis/{topic}/flow.md"
+                       % (first, sid)}
+
+
+# `{topic}` in a command is filled per topic. The design check and the Stop UI
+# rule judge design and build; the flow only asks for their note.
+_STEPS = (
+    _step("research", "research"),
+    _step("metrics", "product-analysis"),
+    _step("assumptions", "product-analysis"),
+    _step("decision", "product-analysis"),
+    _step("instrumentation", "product-analysis"),
+    {"id": "forward-spec", "skill": "feature-audit",
+     "leaves": ".tezgah/analysis/<topic>/spec.md",
+     "command": "feature-audit forward mode: write .tezgah/analysis/{topic}/spec.md "
+                "naming the decision"},
+    _step("design", "design-contract", "tezgah-design check, then "),
+    _step("build", "design-contract", "tezgah-design check, then "),
+    _step("re-measure", "analyze-app", "measure the decision's metric again, then "),
+)
+FLOWS = {
+    "metric-dashboard": _STEPS,
+    # A feature may reuse a metric another topic owns: its own metric steps join
+    # the flow only when its flow.md holds `## metrics` (`next_steps`).
+    "feature": tuple(s for s in _STEPS if s["id"] not in ("metrics", "instrumentation")),
+}
+
+
+def _sections(text):
+    """{step: body} of the `## <step>` headings in `text`, lower-cased."""
+    parts = re.split(r"^##[ \t]+(.+?)[ \t]*$", text, flags=re.M)
+    return {parts[i].lower(): parts[i + 1] for i in range(1, len(parts) - 1, 2)}
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def next_steps(repo, topic, flow="metric-dashboard", today=""):
+    """[{"id", "skill", "status", "detail", "command"}] for `topic` under `flow`,
+    status one of done | missing | due, read from `.tezgah/analysis/<topic>/` of
+    `repo`. A topic outside TOPIC or with no folder lists every step missing."""
+    if flow not in FLOWS:
+        raise ValueError("unknown flow %r (%s)" % (flow, ", ".join(FLOWS)))
+    try:
+        day = datetime.date.fromisoformat(today) if today else datetime.date.today()
+    except ValueError:
+        raise ValueError("today %r is not YYYY-MM-DD" % (today,)) from None
+    safe = isinstance(topic, str) and TOPIC.fullmatch(topic)
+    rel = os.path.join(".tezgah", "analysis", topic if safe else "<topic>")
+    folder = os.path.join(tp.workspace(repo), "analysis", topic) if safe else ""
+    notes = _sections(_read(os.path.join(folder, "flow.md"))) if folder else {}
+    flow_rel = os.path.join(rel, "flow.md")
+    spec_rel = os.path.join(rel, "spec.md")
+    steps = FLOWS["metric-dashboard"] if flow == "feature" and "metrics" in notes \
+        else FLOWS[flow]
+
+    def status(sid):
+        if sid == "forward-spec":
+            return ("done", "%s exists" % spec_rel) \
+                if folder and os.path.isfile(os.path.join(folder, "spec.md")) \
+                else ("missing", "%s does not exist" % spec_rel)
+        if sid in notes:
+            return "done", "%s ## %s" % (flow_rel, sid)
+        if sid == "re-measure":
+            after = OBSERVE.search(notes.get("decision", ""))
+            try:
+                when = datetime.date.fromisoformat(after.group(1)) if after else None
+            except ValueError:
+                when = None
+            if when is not None:
+                return ("due", "observe after %s has passed" % when) if day > when \
+                    else ("missing", "observe after %s, not yet" % when)
+            return "missing", "no observe after: in %s ## decision" % flow_rel
+        return "missing", "no ## %s in %s" % (sid, flow_rel)
+
+    out = []
+    for s in steps:
+        state, detail = status(s["id"])
+        out.append({"id": s["id"], "skill": s["skill"], "status": state,
+                    "detail": detail, "command": s["command"].format(
+                        topic=topic if safe else "<topic>")})
+    return out

package/hooks/tezgah_research.py

@@ -2842,9 +2842,9 @@ def _check_append_only(repo, label, path, errors, warnings, hard):
         old = [line for line in older.splitlines() if line.strip()]
         new = [line for line in newer.splitlines() if line.strip()]
         if new[:len(old)] != old:
-            _soft(errors, warnings, hard, "%s was rewritten after the run: a committed "
-                  "row changed or went missing, and results are append-only - a "
-                  "correction is a new row" % label)
+            _soft(errors, warnings, hard, "%s was rewritten after the run: a "
+                  "committed row changed or went missing, and results are "
+                  "append-only - a correction is a new row" % label)
             return
 
 

package/hooks/tezgah_skill_pick.py

@@ -347,10 +347,40 @@ def skill_roots(extra=()):
     return out
 
 
+# One routing line of a skill's own INDEX.md: `name - what it makes - path`.
+_INDEX_ROW = re.compile(r"^\S+ - .+ - (\S+/SKILL\.md)\s*$")
+
+
+def _entries(root, name):
+    """[(skill, path)] for one skill directory: its SKILL.md, then every entry its
+    INDEX.md routes to. design-library keeps 39 entries under
+    `<plugin>/skills/<entry>/SKILL.md` and reaches them only through that index,
+    so a search over top-level files alone never saw a word of them. A nested
+    entry is addressed `<skill>/<path>`, the form `skill://` resolves."""
+    base = os.path.join(root, name)
+    out = [(name, os.path.join(base, "SKILL.md"))]
+    try:
+        with open(os.path.join(base, "INDEX.md"), encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return out
+    # A row is followed only inside the skill's own directory: an absolute path,
+    # a `..` or a symlink out would index a file the skill does not ship.
+    inside = os.path.realpath(base) + os.sep
+    for line in lines:
+        hit = _INDEX_ROW.match(line)
+        if not hit or os.path.isabs(hit.group(1)):
+            continue
+        path = os.path.join(base, hit.group(1))
+        if os.path.realpath(path).startswith(inside):
+            out.append(("%s/%s" % (name, hit.group(1)), path))
+    return out
+
+
 def _rows(roots=None):
     """[(skill, path, title, start, end, text)] over every installed skill's
-    sections, deduplicated on the file's realpath so a skill five hosts link
-    is one entry, not five."""
+    sections, and the entries a skill's INDEX.md routes to, deduplicated on the
+    file's realpath so a skill five hosts link is one entry, not five."""
     out, seen = [], set()
     for root in (skill_roots() if roots is None else roots):
         try:
@@ -358,14 +388,23 @@ def _rows(roots=None):
         except OSError:
             continue
         for name in names:
-            path = os.path.realpath(os.path.join(root, name, "SKILL.md"))
-            if not os.path.isfile(path):
-                continue
-            for title, start, end, text in sections(path):
-                if (path, start) in seen:
+            for skill, raw in _entries(root, name):
+                path = os.path.realpath(raw)
+                if not os.path.isfile(path):
                     continue
-                seen.add((path, start))
-                out.append((name, path, title, start, end, text))
+                secs = sections(path)
+                if "/" in skill and secs:
+                    # A routed entry is one row, the whole file: its short
+                    # sections out-scored whole skills on two common words
+                    # ("give", "thing") and silenced the right hint, while the
+                    # entry as a whole still carries its topic's words.
+                    secs = [(secs[0][0], secs[0][1], secs[-1][2],
+                             "\n".join(s[3] for s in secs))]
+                for title, start, end, text in secs:
+                    if (path, start) in seen:
+                        continue
+                    seen.add((path, start))
+                    out.append((skill, path, title, start, end, text))
     return out
 
 
@@ -490,9 +529,10 @@ def rank_postings(query, posts, lengths, k):
 
 
 def _signature():
-    """[[root, skill, mtime_ns, size]] per installed SKILL.md: what a rebuild
-    keys on. The file's own stat, not its directory's - installing, editing or
-    removing one skill is exactly the change the cache must notice."""
+    """[[root, skill, mtime_ns, size]] per installed SKILL.md and per entry an
+    INDEX.md routes to: what a rebuild keys on. The file's own stat, not its
+    directory's - installing, editing or removing one skill is exactly the
+    change the cache must notice."""
     sig = []
     for root in skill_roots():
         try:
@@ -500,11 +540,12 @@ def _signature():
         except OSError:
             continue
         for name in names:
-            try:
-                st = os.stat(os.path.join(root, name, "SKILL.md"))
-            except OSError:
-                continue
-            sig.append([root, name, st.st_mtime_ns, st.st_size])
+            for skill, path in _entries(root, name):
+                try:
+                    st = os.stat(path)
+                except OSError:
+                    continue
+                sig.append([root, skill, st.st_mtime_ns, st.st_size])
     return sig
 
 

package/hooks/tezgah_task.py

@@ -2,8 +2,8 @@
 """The active task: one plan file's phase and its path allowlist.
 
 A task is not a second record beside the plan - it IS the plan file under
-`.tezgah/plans/open/`, with two optional frontmatter keys that the user's own CLI
-(bin/tezgah-task) writes and no agent ever does:
+`.tezgah/plans/open/`, with two optional frontmatter keys that only its CLI
+(bin/tezgah-task, run by the orchestrating session itself) writes:
 
     phase: implementation        # discovery | implementation | verification
     allowed_paths:               # globs, relative to the repo root