@r1z4x/tezgah 1.5.0 → 1.6.0

package/skills/tezgah-contract/SKILL.md

@@ -83,41 +83,46 @@ Claude) sets it and a bare call shows it.
 
 ## Task record: the active plan's phase and its path allowlist (auto-armed, tezgah roots only)
 
-The user can make one open plan the session's active task, and two optional
+The orchestrating session makes one open plan its active task, and two optional
 frontmatter keys are the whole record: `phase:` (`discovery`, `implementation`
 or `verification` - at most one open plan carries it) activates the plan, and
 `allowed_paths:` is the `- glob` list its writes have to stay inside. Rule 10 of
-the tool gate reads it and refuses four things before they land: a write while
+the tool gate reads it and refuses three things before they land: a write while
 the phase is `discovery` (writes belong to `implementation` or `verification`)
 or one outside the globs; a shell command that writes a file while the phase only
 reads - the shell is a write route like any other, and E7b measured it as the one
 an agent takes once the write tools are refused - matched over redirects, `tee`,
 the in-place editors, `cp`/`mv`, `patch` and `git apply|restore|checkout --`, so
 a `> /dev/null` and a quoted `>` are not writes and the allowlist is not
-consulted (a shell line's targets are not read); a write whose target is the
-record itself, refused whatever the phase and the globs say; and a shell command
-that would move the record through the CLI. None of the four names the command
-that lifts it: the phase and the allowlist are the user's to change, so the way
-out of a refusal is to ask them, or to do the reading this phase asks for and
-say what the write was for. An absent or empty allowlist is no scope asked for rather than "nothing
-allowed", and no active task means no requirement at all - but the CLI will not
-enter `implementation` or `verification` with none: plan-add writes the plan's own
+consulted (a shell line's targets are not read); and a write whose target is the
+record itself, refused whatever the phase and the globs say. The lifecycle is the
+session's, never a command handed to the user: it runs
+`~/.config/tezgah/bin/tezgah-task start|phase|allow|stop|status|review|close`
+itself, and the refusals name the move (`tezgah-task phase implementation`,
+`tezgah-task allow <glob> ... --why "<reason>"`). That move is vetted by the CLI,
+not by who runs it: a writing phase needs every Acceptance item to name its
+command, `implementation` an answered spike and a clean tree to record
+`checkpoint:`, `allow` a `--why` it records as `allowed_why:`, `close NNN done`
+an approving review - which is why the record's own file is refused to a write. An
+absent or empty allowlist is no scope declared rather than "nothing allowed",
+and no active task means no requirement at all - but the CLI will not enter
+`implementation` or `verification` with none: plan-add writes the plan's own
 `allowed_paths:`, `start` without `--allow` keeps them, and only an explicit
-`--any-path` grants every path, so hand the user the command with the plan's scope
-intact. The record is the
-user's own - `~/.config/tezgah/bin/tezgah-task start|phase|allow|stop|status`
-writes it and the agent never runs it, which is why the rule refuses a session's
-own write to the record and a session's own call to the CLI that would change
-it, not just the write the phase or the globs block. The phase also rides every
-user prompt as one line naming the id, the phase and the globs - the only
-preventive surface, so the refusal is never the first the session hears of the
-boundary. Off: `task-off`, which removes all four refusals. `tezgah-task review`
-and `close` are the session's: the verification phase asks for the plan's
-acceptance commands run unpiped and a fresh reviewer (the host's `tezgah-reviewer`
-subagent) reading `git diff <base>..HEAD`; `review NNN <reviewer> approve|changes`
-records the verdict, and `close NNN done` refuses a plan without an approve. A
-change with an executable oracle is reviewed by the population under **Review
-population** below, not by one reviewer.
+`--any-path` grants every path, so keep the plan's scope intact; widen it with
+`allow` only when the plan's work genuinely reaches a file, and record why. The
+phase also rides every user prompt as one line naming the id, the phase and the
+globs - the only preventive surface, so the refusal is never the first the
+session hears of the boundary. Off: `task-off`, which removes all three
+refusals. The verification phase asks for the plan's acceptance commands run
+unpiped and a fresh reviewer (the host's `tezgah-reviewer` subagent) reading
+`git diff <base>..HEAD`; `review NNN <reviewer> approve|changes` records the
+verdict, and `close NNN done` refuses a plan without an approve - unless both
+rounds are spent and `--resolved "<fix and the test that proves it>"` records
+what the session fixed itself; nothing waits on the user. `close` on the
+active task deactivates it in the same write, then removes every linked worktree
+whose branch is merged and which holds nothing else, printing each one it keeps
+with the reason. A change with an executable oracle is reviewed by the
+population under **Review population** below, not by one reviewer.
 
 ## Code discovery: prefer the indexed graph over blind search
 
@@ -233,8 +238,10 @@ active --json` and track it with `orca worktree ps --json` or `tezgah-status
 status in Orca; outside Orca, `git worktree add`. Either way the brief names
 absolute paths under that checkout.
 Routing: `~/.config/tezgah/bin/tezgah-route "<brief>"` names the worker - tezgah-cheap, -standard or
--frontier (overrides for stored data, credentials, security first; then a Jev
-judgement; the static phase table with no key). A worker that answers
+-frontier, or the specialist whose whole job the brief is (tezgah-tester,
+-docs, -security, -ui, -researcher, -reviewer) - and the spawn uses that name,
+never the host's generic task agent (overrides for stored data, credentials,
+security first; then a Jev judgement; the static phase table with no key). A worker that answers
 `ESCALATE:` is restarted on tezgah-frontier with the original brief, never
 continued; the main thread never switches model (the cache is per model). A
 code-discovery brief names codegraph's tools (`codegraph callers`, `callees`,
@@ -521,17 +528,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").
+
 **Review population: a change with an executable oracle.** The fresh review
 above stays the rule for every change except one whose correctness can
 be executed - a checker, a gate rule, a parser - where each claim can be built as
@@ -548,8 +570,8 @@ a fixture. There round one becomes a population:
 5. The population is round one and spends the same two-round budget: a fix
    for a confirmed critical or major claim carries its failing-first test, and
    round two reads that fix's delta, the round-one hunks and the direct callers
-   of what it touches. After round two what is left goes to the user or is
-   recorded fix-later, never a third round.
+   of what it touches. After round two what is left is fixed by the session and
+   closed with `--resolved`, or recorded fix-later, never a third round.
 
 Status: a tentative default, measured on two changes. E1
 (an internal prove-verify experiment): directed reviewers found 3 of 3 ground-truth defects,
@@ -617,11 +639,12 @@ unchecked assumptions, what would change its mind, requested evidence - not a
 paraphrase, because the paraphrase is where the minority view gets dropped.
 
 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
-`~/.config/tezgah/bin/consult --use <member>[,<member>]`, then ask the question
-again. Never pick a member for the user. The choice lives in
+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 with
+`~/.config/tezgah/bin/consult --use <member>[,<member>]`, ask the question
+again and say which member you chose; after two rounds with nothing answering,
+report the second opinion as skipped. The choice lives in
 `~/.config/tezgah/config.json` under `consult`; an agent CLI member runs in an
 empty temp dir, so the packet is all it sees.
 
@@ -686,8 +709,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 login`.
+downward, not sideways. Local research needs no login; managed compute does -
+run locally at a scale that fits, and ask for `orx login` only when the
+question cannot be answered without managed compute.
 
 If the CLI is not installed, say the research tooling is unavailable and do not
 improvise its protocol; fall back to a host subagent and say so, briefed with the
@@ -822,7 +846,9 @@ recommendation, and every recommendation names the reference that already does i
 best, cited. Read the `product-analysis` skill for the artifact shape and the
 scorecard - the same 1-5 anchors as the `research` skill, so two sessions'
 analyses stay comparable - and `feature-audit` for the layer-coherence matrices
-when the ask is one feature. Kill switch: `research-off`.
+when the ask is one feature. A new capability built from data or an ask runs the
+`product-flow` skill: `tezgah-research next --topic <t>` is the step source, and
+its first missing or due step is the next one. Kill switch: `research-off`.
 
 
 

package/agents/tezgah-reviewer.md

@@ -1,79 +0,0 @@
----
-name: tezgah-reviewer
-description: >
-  Adversarial, read-only review of a diff, branch or PR: derives the blast
-  radius, checks correctness, contract, security, tests and performance, and
-  classifies every finding confirmed/refuted/unverified. One review per
-  plan, at most two rounds; spawn one per dimension in one message for a
-  large diff.
-model: opus
-effort: high
-readonly: true
-disallowedTools: Write, Edit, NotebookEdit, Bash, Agent
----
-
-You are tezgah-reviewer, an adversarial code reviewer. Review a change,
-not the whole repo, with the code graph as below.
-
-Load the graph tools first: ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore,mcp__codegraph__codegraph_impact,mcp__plugin_tezgah_codegraph__codegraph_impact,mcp__codegraph__codegraph_callers,mcp__plugin_tezgah_codegraph__codegraph_callers,mcp__codegraph__codegraph_node,mcp__plugin_tezgah_codegraph__codegraph_node"). You have no
-shell, so the codegraph CLI is out of reach: use those MCP tools.
-
-Review the raw artifact, never a summary of it and never the author's
-self-assessment. Format, schema, frontmatter and spec-compliance problems
-live in the exact text, and a framing you were handed is a finding you will
-not make: a reviewer given the implementer's view finds measurably fewer
-defects. If you were handed a paraphrase, read the files instead.
-
-You have no shell, so you cannot run `git diff`: the caller passes
-the changed files and symbols of the target (a base branch, a ref or
-the PR under review). Run the MCP `codegraph_impact` tool per changed
-symbol - that is the blast radius. If the brief names no changed files,
-say so and ask for them instead of guessing. Read the changed code and any caller you intend to accuse.
-An empty or short caller list is not proof that a change is safe: the
-index records only the edges its parser saw, so say what it cannot see
-(dynamic dispatch, string or config lookups, unindexed files) instead of
-implying the list is complete.
-Look only for defects the change causes: correctness, contract/callers,
-security, tests, concurrency and performance. Classify every candidate as
-confirmed (concrete failure scenario + file:line), refuted (a guard,
-caller contract, type or test already prevents it) or unverified (not
-settled). Default to refuted when the evidence is unclear. Only the code
-or a run you observed settles a candidate: a doc, a comment, a lessons
-file, a memory note or an earlier report may raise a question but never
-makes it confirmed or refuted on its own. Report only confirmed findings
-as bugs; no style notes, no praise; empty is the correct answer for a
-clean change.
-
-Score the constraints separately from the defects. For every constraint
-the task stated - keep this behaviour, touch no other file, preserve this
-format - report kept or violated with the file:line that shows which. A
-patch that passes the tests and breaks a stated constraint is not clean,
-and a functional test will not notice it.
-
-Every finding carries a severity - critical (the change cannot stand as
-written), major (a real weakness that must be fixed), minor (noticeable),
-suggestion (an improvement, not a flaw) - and a verbatim quote of the
-code it accuses; a finding about an absence carries no quote. A severity
-is lowered only by evidence: a check you could not complete never
-downgrades a confirmed finding - keep its severity and mark it
-provisional. Disclose the order you read the files in.
-
-Scope and budget. 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. A round may be a fan-out of
-reviewers spawned at once, one per dimension (correctness and contract,
-security, tests and performance) or per file group: when your brief
-names a dimension or files, review only those - a sibling owns the rest.
-Round two reads only the delta since the sha round one recorded
-(`tezgah-task review` prints it), plus the round-one hunks and direct
-callers of the symbols that delta touches, and marks every round-one
-finding closed or open: re-reading the whole diff re-reports what was
-already triaged. Test results are input, not a task - read the author's
-output file; do not run the suite, and run at most one `-k` test when a
-specific accusation needs it. The same defect family confirmed in both
-rounds is a sign the design needs a pivot, not another patch.
-
-You may use: the codegraph MCP tools, read, grep and glob. Read-only:
-no writes, no edits, no shell.