@r1z4x/tezgah 1.11.0 → 1.14.0

package/hosts/qwen/hook.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Qwen Code lifecycle hook. Reads Qwen's JSON on stdin and answers in Qwen's own
+output shape, onto the shared tezgah core (hooks/).
+
+Qwen Code 0.21.13 fires SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
+PostToolUseFailure, SubagentStart, SubagentStop and Stop here
+(`bin/tezgah-setup::QWEN_HOOK_EVENTS`); anything else is ignored. Inert outside
+the roots.
+
+The always-on core is the managed block in `~/.qwen/QWEN.md`, which Qwen loads
+into every session, so SessionStart repeats it only when that block is missing.
+PreToolUse translates Qwen's runtime tool ids into the gate's vocabulary and
+denies with `hookSpecificOutput.permissionDecision` on exit 0 - never exit 2,
+whose stderr channel carries no reason the ledger and the probe can read. Qwen
+fires PostToolUse for a successful call and PostToolUseFailure for a failed one
+(a shell exit Qwen counts as an error, `isShellExitError`), so the event is the
+call's outcome. Stop blocks a done/tested claim with no successful check behind
+it, judged on `last_assistant_message`, the same rule Claude's Stop hook enforces
+(hooks/tezgah_integrity.py). The status line is `tezgah-statusline --qwen`, Qwen's
+`ui.statusLine` command, so no event here carries it.
+"""
+import json
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
+sys.path.insert(0, os.path.join(ROOT, "hooks"))
+from tezgah_guard import attest_session, import_failed, safe  # noqa: E402
+try:
+    from tezgah_context import command_text, context_for, record, shell_kind  # noqa: E402
+    from tezgah_gate import cross_project_note, decision, graph_advice  # noqa: E402
+    from tezgah_integrity import (  # noqa: E402
+        SUBAGENT_CHANNEL, bind_session, note, note_tool, ran_nothing, report_bytes,
+        stop_reason, untrusted_source)
+    from tezgah_paths import HOST_DIRS, off, root_for  # noqa: E402
+    from tezgah_taste import write_note  # noqa: E402
+    from tezgah_untrusted import marks  # noqa: E402
+except Exception as exc:
+    import_failed(exc)
+
+# Qwen's runtime tool ids (the `ToolNames` table in the 0.21.13 bundle) -> the
+# shared gate's vocabulary. `replace` is the edit tool's id in older builds; the
+# 0.21.13 bundle has none, and an unknown id passes the gate untouched. MCP tools
+# arrive as `mcp__<server>__<tool>`, the shared shape, and pass through.
+# `monitor` runs a shell command too (Qwen's headless deny list pairs it with
+# SHELL), and `notebook_edit` writes an .ipynb (review of plan 138).
+GATE_TOOLS = {
+    "run_shell_command": "Bash",
+    "monitor": "Bash",
+    "write_file": "Write",
+    "edit": "Edit",
+    "replace": "Edit",
+    "notebook_edit": "NotebookEdit",
+    "agent": "Task",
+    "grep_search": "Grep",
+}
+
+
+def gate_name(name):
+    """The tool name the gate denies under and the ledger row records.
+
+    `call_id` hashes the name it is handed, so both halves map through here: a
+    PostToolUse row under the raw id would never match the PreToolUse call and
+    the loop guard would never deny (`hosts/codex/hook.py::gate_name`)."""
+    return GATE_TOOLS.get(name, name)
+
+
+def classify(payload):
+    """The used-tool kind for a tool payload, or None."""
+    name = payload.get("tool_name", "") or ""
+    if name.startswith("mcp__") and "codegraph" in name:
+        return "graph"
+    if name == "agent":
+        return "orch"
+    if name == "run_shell_command":
+        return shell_kind(command_text(payload.get("tool_input")))
+    return None
+
+
+def subagent_id(payload):
+    """The subagent id Qwen adds to a hook input run inside a subagent, else None."""
+    aid = payload.get("agent_id")
+    return aid if isinstance(aid, str) and aid else None
+
+
+def rules_carry_core():
+    """True when `QWEN.md` in Qwen's home holds tezgah-setup's managed block."""
+    try:
+        with open(os.path.join(HOST_DIRS["qwen"], "QWEN.md"), encoding="utf-8") as fh:
+            return "<!-- tezgah:start" in fh.read()
+    except OSError:
+        return False
+
+
+def result_size(result):
+    """The result's top-level length, the Claude-family writer's measure; a value
+    with no length counts as non-empty and only a missing result is None."""
+    if isinstance(result, (str, bytes, bytearray, list, tuple, dict, set, frozenset)):
+        return len(result)
+    return 1 if result is not None else None
+
+
+def inp_of(payload):
+    inp = payload.get("tool_input")
+    return inp if isinstance(inp, dict) else {}
+
+
+def post_tool(payload, cwd, session_id, failed):
+    """The ledger row for one finished call, and the notice for the model."""
+    tool = gate_name(payload.get("tool_name", ""))
+    inp = inp_of(payload)
+    # a `monitor` PostToolUse fires when the watch starts ("Monitor started"),
+    # long before its command ends: it records a run, never a pass (review of
+    # plan 138, round 2); a failed start still arrives as PostToolUseFailure
+    if payload.get("tool_name") == "monitor" and failed is False:
+        failed = None
+    safe(session_id, record, session_id, classify(payload))
+    if not root_for(cwd):
+        return None
+    result = payload.get("tool_response")
+    # read before this call's row lands: `source` is the taint's own mark
+    got = safe(session_id, marks, tool, inp, session_id, result)
+    source, notice = got or (None, None)
+    safe(session_id, note_tool, session_id, tool, inp, failed=failed,
+         interrupted=bool(failed and payload.get("is_interrupt") is True),
+         source=source, cwd=cwd,
+         out_bytes=(report_bytes(result)
+                    if untrusted_source(tool, inp) == SUBAGENT_CHANNEL
+                    else result_size(result)),
+         empty_run=ran_nothing(result), agent=subagent_id(payload))
+    advice = safe(session_id, graph_advice, tool, inp, cwd, "qwen")
+    taste = cross = None
+    if not failed:
+        taste = safe(session_id, write_note, session_id, inp, cwd, tool)
+        cross = safe(session_id, cross_project_note, session_id, tool, inp, cwd)
+    return "\n".join(p for p in (notice, advice, taste, cross) if p)
+
+
+def context(event, text):
+    return {"hookSpecificOutput": {"hookEventName": event,
+                                   "additionalContext": text}} if text else {}
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return
+    if not isinstance(payload, dict):
+        return
+    event = payload.get("hook_event_name") or ""
+    cwd = payload.get("cwd") or os.getcwd()
+    session_id = payload.get("session_id")
+    safe(session_id, bind_session, session_id, payload.get("parent"))  # the switch latch
+    out = {}
+    if event == "PreToolUse":
+        reason = safe(session_id, decision, gate_name(payload.get("tool_name", "")),
+                      inp_of(payload), cwd, session_id, agent=subagent_id(payload))
+        if reason:
+            out = {"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }}
+    elif event in ("PostToolUse", "PostToolUseFailure"):
+        out = context(event, post_tool(payload, cwd, session_id,
+                                       event == "PostToolUseFailure"))
+    elif event == "SessionStart":
+        safe(session_id, attest_session, "qwen", session_id, cwd)
+        out = context(event, safe(session_id, context_for, "session_start", cwd,
+                                  payload, with_core=not rules_carry_core()))
+    elif event == "UserPromptSubmit":
+        out = context(event, safe(session_id, context_for, "user_prompt", cwd, payload))
+    elif event == "SubagentStart":
+        safe(session_id, record, session_id, "orch")
+        kind = payload.get("agent_type")
+        if subagent_id(payload) and isinstance(kind, str) and root_for(cwd):
+            safe(session_id, note, session_id, "subagent_start", kind,
+                 agent=subagent_id(payload))
+        # the delegate is a fresh context: Qwen documents additionalContext here
+        # as the subagent's initial context
+        out = context(event, safe(session_id, context_for, "subagent_start", cwd,
+                                  payload))
+    elif event == "SubagentStop":
+        # a subagent's end is judged record-only (ADR 011): one `subagent_end`
+        # row from its last message, never a block
+        safe(session_id, record, session_id, "orch")
+        if not off("verify-off") and root_for(cwd):
+            safe(session_id, stop_reason, payload.get("last_assistant_message") or "",
+                 session_id, cwd=cwd, subagent=True)
+    elif event == "Stop":
+        # Qwen's Stop carries `last_assistant_message` and `stop_hook_active`,
+        # and takes {"decision": "block", "reason": ...}. The reply after a block
+        # is judged again and refused at most once more (tezgah_integrity).
+        if not off("verify-off") and root_for(cwd):
+            reason = safe(session_id, stop_reason,
+                          payload.get("last_assistant_message"), session_id,
+                          cwd=cwd, after_block=bool(payload.get("stop_hook_active")),
+                          mode=payload.get("permission_mode"))
+            if reason:
+                out = {"decision": "block", "reason": reason}
+    if out:
+        print(json.dumps(out))
+
+
+main()

package/output-styles/tezgah.md

@@ -38,7 +38,7 @@ first; write what was cut only when you consciously cut something the user asked
 for, in at most three lines. In force from the first turn; levels
 lite|full|ultra are set with `~/.config/tezgah/bin/tezgah-pony` and ride the per-turn reminder when
 not `full`; read the full `ponytail` skill from the router for the level table
-and examples. Off: "stop ponytail".
+and examples. Off: "stop ponytail", `ponytail-auto.off` or `.no-ponytail`.
 
 **Output shape: ADHD-friendly.** The answer or the next action is on the first
 line - a command, path, snippet or the decision itself, never context or the
@@ -47,7 +47,10 @@ bounded action per step, and while it is in flight its position is restated in
 one line - the todo list is that source, never re-narrate the plan. End with the
 approval questions the Ask policy (below) leaves, or with nothing when none is
 left; a step you can take yourself is taken, never handed
-over. Finish the issue in hand before raising a second one; an error states
+over, and in the host's plan mode, where nothing can run, the plan is the
+deliverable: its approval is the question that turn asks and nothing is
+reported as done or tested.
+Finish the issue in hand before raising a second one; an error states
 location, cause and fix with no drama, naming a cause only when the evidence
 identifies it (else what is known and what would confirm it); after a change say
 what now works. A list shows at most five items, ranked, the rest kept in
@@ -112,15 +115,17 @@ lines: item - blocker - evidence - what unblocks it. No blockers: no heading.
 Work and process - the order, "shall I go on", a check, a plan, a consult
 member, a spend within `spend_cap`, a local merge of the session's branch,
 removing its worktree - are taken and stated in one line, never asked; a taste
-or intent fork goes in the batch with a default taken this turn, but building a
-plan this turn wrote waits for the answer. An outward step
+or intent fork goes in the batch with a default taken this turn, but the
+never-default items below wait for the answer. An outward step
 on the user's own remote (push, PR, release, their package) runs on a grant
 ("push without asking", "I approve", "bana sormadan pushla", "onay veriyorum"), else is asked once. Never on a
 default - ask and wait for an answer naming action and target: a force push,
 deleting what the session did not make, production, a credential, a third
-party, a spend over the cap. The batch: one "Approval questions"/"Onay için sorular" heading, waiting
+party, a spend over the cap, building a plan this turn wrote, picking a
+recommended variant, a way around a tezgah refusal, another session's work. The batch: one "Approval questions"/"Onay için sorular" heading, waiting
 items first, each numbered item with "Recommended:"/"Öneri:" its default; an ask tool
-sets a recommended option.
+sets a recommended option. No fresh subagent, no review verdict: say so and
+ask. Contest a finding only with a file:line; never lower a severity.
 **Say what a number was measured on.** A figure produced by a fixture - a temp
 HOME, a generated repository, a stand-in, a hand-written sample - is evidence
 about the code path, never a property of the running system, and it is reported

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.11.0",
-  "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
+  "version": "1.14.0",
+  "description": "One shared working contract for every AI coding assistant you run, across fourteen hosts: omp, Claude Code, Codex, Cursor, opencode, dsh, Qwen Code, Factory Droid, Command Code, GitHub Copilot CLI, Gemini CLI, Antigravity CLI, Goose and Amp.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,7 +23,10 @@
     "MANIFEST",
     "CHANGELOG.md",
     "LICENSE",
-    "packaging/"
+    "NOTICE",
+    "third_party/",
+    "packaging/",
+    "!**/__pycache__"
   ],
   "engines": {
     "node": ">=18"

package/packaging/build.sh

@@ -79,12 +79,12 @@ def version():
 
 
 def changelog_version():
-    """The newest release heading: the second source `plugin_version()` reads."""
+    """The newest `## [x.y.z]` heading, as `RELEASE` in hooks/tezgah_context.py."""
     try:
         with open(os.path.join(ROOT, "CHANGELOG.md")) as fh:
-            for line in fh:
-                if line.startswith("## ["):
-                    return line[4:].split("]")[0].strip()
+            for v in (ln[4:].split("]")[0] for ln in fh if ln.startswith("## [")):
+                if v.count(".") == 2 and all(p.isdigit() for p in v.split(".")):
+                    return v
     except OSError:
         pass
     return ""

package/packaging/install.sh

@@ -26,6 +26,17 @@ while [ $# -gt 0 ]; do case $1 in
     *) echo "tezgah: unknown option $1" >&2; exit 2 ;;
 esac; done
 
+# Python 3.10+ is the floor (README; CI tests nothing older): refused here, by
+# the version found, before anything is fetched.
+py=$(command -v python3 2>/dev/null) || { echo "tezgah: needs Python 3.10 or newer, and no python3 is on PATH" >&2; exit 1; }
+pyver=$("$py" --version 2>&1 | sed -n 's/^Python \([0-9][0-9]*\.[0-9][0-9.]*\).*/\1/p')
+pymajor=0; pyminor=0
+if [ -n "$pyver" ]; then pymajor=${pyver%%.*}; pyminor=${pyver#*.}; pyminor=${pyminor%%.*}; fi
+if [ "$pymajor" -lt 3 ] || { [ "$pymajor" -eq 3 ] && [ "$pyminor" -lt 10 ]; }; then
+    echo "tezgah: needs Python 3.10 or newer; $py is ${pyver:-of unknown version}" >&2
+    exit 1
+fi
+
 # The default upgrade.sh resolves: the installer is reached through the tree it picks.
 PREFIX=${PREFIX_ARG:-${TEZGAH_PREFIX:-${XDG_DATA_HOME:-$HOME/.local/share}/tezgah}}
 finish() { [ -z "$work" ] || rm -rf "$work"; }

package/packaging/upgrade.sh

@@ -41,6 +41,9 @@ die() {
     exit 1
 }
 
+# First: a missing curl would otherwise read as a fetch failure blaming a token.
+for t in curl tar; do command -v "$t" >/dev/null 2>&1 || die "$t is required (README: Install)"; done
+
 # A private repository answers 404 to `releases/download/...` from a session without
 # a token (measured 2026-10-17, with the token as URL userinfo and as a header
 # alike), while the REST asset endpoint returns the blob for `Accept:

package/skills/ai-research/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude AI Research Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/design-contract/SKILL.md

@@ -33,8 +33,8 @@ file, so it costs nothing until it is used.
 the machine half and the only part `check` reads, and the header is what a person
 opens. Field names and prose stay English.
 
-- `source` - where the floor came from: `css-custom-properties`, `tailwind-config`
-  or `theme-json` when it was read out of the repository, `derived` when it could
+- `source` - where the floor came from: `css-custom-properties`, `tailwind-config`,
+  `theme-json` or `theme-module` when it was read out of the repository, `derived` when it could
   not be and someone chose it. An empty `source` is refused: a floor nobody can
   trace is not a floor.
 - `tokens.colors` - the colour roles, as role name to hex. A measured colour that
@@ -160,18 +160,25 @@ Read the repository's own token source. In this order, and nothing else:
    role, named by the property (the `color-`/`c-` prefix and a trailing `-color`
    are dropped); one named `space`, `spacing`, `unit`, `rhythm` and the like
    states the unit; `font-size`/`text-size`/`fs` properties are the type scale.
-2. **A Tailwind config** - `tailwind.config.{js,cjs,mjs,ts,json}`, its `colors`,
-   `spacing` and `fontSize` blocks. `unit`/`base` in `spacing` states the unit;
-   otherwise the greatest common divisor of the scale the config declares is it.
+2. **A Tailwind config** - every `tailwind.config.{js,cjs,mjs,ts,json}` in the tree (a monorepo
+   has one per app), its `colors`, `spacing` and `fontSize` blocks. A nested colour scale is
+   flattened to the class name Tailwind generates (`brand: {500: ...}` is `brand-500`, `DEFAULT`
+   is `brand`); a name two configs give different values keeps both (`ink@apps/b/...`). `unit`/
+   `base` in `spacing` states a config's unit, otherwise the greatest common divisor of its
+   scale does, and the floor's unit is the one every config's unit is a multiple of.
 3. **A tokens/theme JSON** - `theme.json`, `tokens.json` or `design-tokens.json`,
    its `colors`/`palette`, `spacing` and `fontSize` keys, found at any depth.
+4. **A JS/TS theme module** - `theme`, `tokens`, `colors`, `colours` or `palette` `.ts/.js/.mjs`,
+   the floor a React Native or Expo app keeps in code: every top-level `const` object's colour
+   literals (`palette-ink`, `light-text`), the `spacing` object's numbers (unitless is px/dp), and
+   every `fontSize:` number.
 
 ```sh
 ~/.config/tezgah/bin/tezgah-design derive --repo .          # writes .tezgah/design-contract.md
 ~/.config/tezgah/bin/tezgah-design derive --repo . --json   # the same, machine-readable
 ```
 
-`derive` writes nothing and exits 2 when the repository has none of the three, and it never
+`derive` writes nothing and exits 2 when the repository has none of the four, and it never
 overwrites a contract that already exists - that file carries the component inventory someone
 filled in, so a re-derive over changed tokens is a hand edit or a deliberate removal first. It
 does not invent a palette, a type scale or a unit either: a repository with no design system gets
@@ -185,6 +192,20 @@ the artifact says so in its header: the `component-inventory` rule is inert unti
 `{name, kind}` per component. A measurement names a component; only a person knows which ones the
 repository owns, so list them in the turn that writes a new one.
 
+`derive --suggest` is the starting list, never the inventory: it prints one candidate per
+component file (a `.tsx/.jsx/.vue/.svelte/.astro/.swift/.kt/.dart` file under a
+`components`/`widgets`/`ui` directory; tests, stories, mocks, a `.kt`/`.swift` file under `theme/` and Swift `+`
+extensions aside; `Button.ios.tsx` is `Button`), minus the names the contract already lists. `kind`
+is filled only where the name's last word says it, matched whole (`IconButton` is `interactive`,
+`StatCard` is `data`, `FeedbackForm` is `null`), and `null` elsewhere. It writes nothing, exits 2
+when there is no candidate, and exits 2 naming the contract when it cannot read it. Copy the rows
+the repository owns into `components`, check every guessed kind and set every `null` one:
+
+```sh
+~/.config/tezgah/bin/tezgah-design derive --suggest --repo .          # table + pasteable rows
+~/.config/tezgah/bin/tezgah-design derive --suggest --repo . --json   # {ok, candidates: [{name, kind, path}]}
+```
+
 ## The check
 
 ```sh

package/skills/design-library/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MC Dean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/harness/SKILL.md

@@ -66,6 +66,8 @@ is reported as such, and an empty list beside it is not evidence of absence.
 
 `graph-review` splits findings into `confirmed` (no refuter refuted it), `refuted` (do not report as bugs),
 and `unverified` (hit the cap, or every refuter failed - label them as such). Never promote a refuted or unverified finding.
+Before the cap, findings with the same file, line and title merge into one. The merge keeps the higher severity
+and lists every raising lens in `dimensions`; `caps.deduplicated` counts the merges.
 
 `graph-review` is one review round, not a loop: inside a plan it is round one or round two of the
 plan's single review (two rounds at most, `~/.config/tezgah/bin/tezgah-task review` refuses a third), never one run per

package/skills/i-have-adhd/SKILL.md

@@ -102,7 +102,10 @@ If something is left that only the reader can do - a decision, a credential or
 grant, consent for a step that cannot be undone - name that ONE step, small
 enough to start now. Several such decisions go in one numbered approval batch,
 each with a recommended default, and the work proceeds on the defaults (the
-tezgah contract's Ask policy). A step you can take yourself is not a next step:
+tezgah contract's Ask policy) - except a class-F item (choosing a variant or
+option a research, analysis or review recommends, a way around a tezgah
+refusal, deciding about another session's work), which waits for the answer.
+A step you can take yourself is not a next step:
 take it, and never end on asking whether to. When nothing is left, end on what
 now works.
 
@@ -110,6 +113,12 @@ Bad: "Hope that helps. Let me know if you want to dig deeper."
 Bad: "Next: run `npm test` and paste the first failing line." (you can run it)
 Good: "Blockers: the push to `main` - IRREVERSIBLE - `git push origin main` waits - your yes." (tr: "Engeller", GERİ ALINAMAZ)
 
+In the host's plan mode nothing can run. There the plan is the deliverable:
+the approval is the one step that is the reader's, every other step waits for
+it, and nothing is reported as done or tested, because nothing ran. The Stop
+rule reads the mode from the host and holds both ends of that
+(`hooks/tezgah_integrity.py::read_only_turn`).
+
 ### 5. Suppress tangents
 
 A second issue waits until the first is finished, then arrives as its own

package/skills/plan-add/SKILL.md

@@ -97,7 +97,11 @@ Input: `$ARGUMENTS` (free text describing the work). Run these steps in order.
    is refused while the tree is dirty, because the phase starts by recording
    `checkpoint:` - the commit the work returns to - and uncommitted work has none
    to record. Make the checkpoint commit it prints, then run the phase move
-   again and the sha is written. Move the phase yourself as the work reaches it
+   again and the sha is written. Before `implementation`, spawn one
+   tezgah-reviewer in plan-readiness mode over the plan file. Fix each major
+   finding in the plan, or ask the owner when only the owner can decide, then
+   move the phase. A plan of one small task may skip this review; say so in
+   one line. Move the phase yourself as the work reaches it
    (`~/.config/tezgah/bin/tezgah-task phase implementation`, then `verification`); when a write is
    refused for its path and the plan's work genuinely reaches that file, widen
    the scope with `~/.config/tezgah/bin/tezgah-task allow <glob> ... --why "<reason>"`, which records the reason. Never retype the record:

package/skills/plan-add/render_table.py

@@ -7,6 +7,13 @@ Usage: python3 render_table.py [--pr-info 'NNN=text' ...]  (extra text appended
        when an item still under .tezgah/plans/open names no command either)
 Creates .tezgah/plans/README.md, or appends the marker block to it, when either is missing."""
 import glob, os, re, sys
+if sys.argv[1:2] in (["-h"], ["--help"]):
+    print(__doc__)
+    sys.exit(0)
+_bad = [a for a in sys.argv[1:] if a.startswith("-") and a not in ("--pr-info", "--acceptance", "--strict")]
+if _bad:
+    print("render_table: unknown flag %s\n%s" % (_bad[0], __doc__.split("\n")[1]), file=sys.stderr)
+    sys.exit(2)
 # The one reader of a plan file lives in the module that owns the record, so the
 # table and the acceptance report cannot disagree about what a plan says. Three
 # dirnames up from skills/plan-add/render_table.py is the tree that holds hooks/,

package/skills/pm-frameworks/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pawel Huryn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/research/SKILL.md

@@ -653,18 +653,27 @@ opened under):
 | `criteria.json` | `question`, `baseline_variant` (V0, the status quo or current design) and `criteria[]`, each with `id` (`K1`), `name`, `kind` (`measured` or `judged`), `direction` (`max`, `min` or `pass`), optional `threshold` and `guardrail` |
 | `variants.jsonl` | one row per variant: `id`, `title`, `artifact` (a path in the line or the repository, `git:<branch>` or `orx:<expId>`), `status` (`produced` or `dropped` with `drop_reason`), and `line` when it is an older line's deliverable |
 | `comparison.jsonl` | one row per cell: `variant`, `criterion`, `value` with its `source`, or `not_checked` with the reason; `rater` on a judged cell. Append with `~/.config/tezgah/bin/tezgah-research compare <slug> <id>` (one JSON object on stdin), which refuses what `check` refuses |
-| `decision.md` | `chosen: V2`, one line per rejected id naming the criterion id that ruled it out, and `flip:` - the result that would reverse the choice |
+| `decision.md` | `recommended: V2` (the line's pick), one line per rejected id naming the criterion id that ruled it out, and `flip:` - the result that would reverse the choice; `chosen:` and `owner:` only once the owner picks |
 
 `check` refuses: fewer produced variants than the deliverable takes; two produced
 files with the same content (a renamed copy is not an alternative); `criteria.json`
 not committed before the first `comparison.jsonl` commit; a comparison row changed
 after it was committed; a missing cell once `decision.md` exists or the line is
-delivering; a `chosen` that is not a produced variant, a rejected variant with no
-criterion, no `flip:`; and a chosen variant another one beats or ties on every
-numeric criterion. A judged cell with fewer than two raters warns (`--strict`
-refuses). A design or plan (and an analysis on a line before rules 5) with no
-`decisions/` warns while the line runs, is refused once it delivers, and keeps
-the line open.
+delivering; a pick (`chosen:`, else `recommended:`) that is not a produced
+variant, a rejected variant with no criterion, no `flip:`; and a picked variant
+another one beats or ties on every numeric criterion. A judged cell with fewer
+than two raters warns (`--strict` refuses). A design or plan (and an analysis on
+a line before rules 5) with no `decisions/` warns while the line runs, is refused
+once it delivers, and keeps the line open.
+
+The line recommends; the owner chooses. Choosing a variant or option a research,
+analysis or review recommends is the owner's call, so a rules-9 line writes
+`recommended:` and never `chosen:` itself - a `chosen:` with no `owner:` line
+fails `check`. Report the recommendation and wait for the answer; building it
+waits too. When the owner answers, record their words:
+`~/.config/tezgah/bin/tezgah-research choose <slug> <decision> <variant> --ack
+"<the owner's words>"` writes `chosen:` and `owner:`, on an open or a done line.
+`conclude` names each recommendation still waiting for the owner.
 
 When the variants are code or config, they are sibling orx nodes under one head
 node (orx cardinal rule 4: fan within a round, then descend onto the winner), and
@@ -681,8 +690,12 @@ into `state.json` `closed` and `log.md`, seals its experiments' file hashes
 way, and an edit after the seal fails `check`. The no-slug `check` reads a done
 line by its seal alone and counts it on one line; its other errors show in
 `check <slug>` and `check --all-lines`. `init --allow-open` is refused
-while an open line has `check` errors. A line moves to another checkout with
-`import`, never as a copy: a copy loses the order proof.
+while an open line has `check` errors, other than a criterion whose verdict is
+still `pending` (a line in flight). A line another session is running is not this
+session's to fix or close: when a refusal names one, stop and ask the owner -
+never a way around a tezgah refusal (another folder, a hidden dir). A hidden dir
+under `research/` is not a line: `check` and `status` fail it. A line moves to
+another checkout with `import`, never as a copy: a copy loses the order proof.
 
 Finally, a `## Patterns` bullet names what it generalises from - a claim id, a
 `literature/` note or a run - because a pattern is the one finding a reader carries