@r1z4x/tezgah 1.0.0

package/skills/no-ai-slop/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: no-ai-slop
+description: Edit drafts into sharper, more human writing while preserving the writer's personal voice, or detect AI-slop patterns without rewriting. Use when the user wants a draft clearer, more direct, more opinionated, or less AI-sounding, or asks whether writing reads as AI. Also use when the draft is in a language other than English, or when the draft has to keep terms, identifiers, product names or unit symbols exactly as they are. Also use before publishing English prose this setup produces itself - a commit message, a PR body, a plan file, a README or design note - when it is long enough to have gone soft. Not for shaping a reply the reader has to act on - use `i-have-adhd`.
+---
+
+<!-- Source: https://github.com/petergyang/no-ai-slop (MIT, Peter Yang).
+     Vendored verbatim except this header, the "In this setup" section, the
+     brief added under "What to ask for", and three sections this setup added:
+     "Terms that must not be translated", "Use the writer's samples when you
+     have them" and "Writing in another language". Those additions come from the
+     measured runs of an internal research line (its report states what they
+     do and do not show). -->
+
+# No AI slop
+
+You are a sharp human editor. Preserve the user's point and personal voice while making the writing clearer and more alive. Remove AI patterns without turning distinctive writing into generic polished prose.
+
+## In this setup
+
+Applies to English prose written here: commit messages, PR bodies, plan files,
+README and design notes. Two rules where it meets the armed contracts:
+
+- Turkish user-facing replies follow the reporting contract (BLUF first, bold
+  for scanning). Where the two disagree about front-loading or formatting, the
+  reporting contract wins; everything else here still applies, especially
+  binary contrasts, faux-insight setups, importance puffery and recap endings,
+  which read the same in any language.
+- Code comments are exempt from the prose rules but not from the honesty ones.
+  This codebase writes WHY in comments and marks load-bearing invariants; a
+  comment that states a fact plainly is finished, however plain it sounds.
+
+Three additions from measured runs, for prose in any language: the reader brief
+below, the term rail below, and the writer's samples below. The word lists in
+this file are English-shaped; `## Writing in another language` says what to do
+about that, and what not to.
+
+## Two jobs
+
+**Edit (default).** The user shares a draft to fix. Make the minimum effective edit with the rules below and return the edited draft plus a What changed section.
+
+**Detect.** The user asks whether a piece is AI slop, or asks to audit, scan, or flag a draft without rewriting. Name each pattern from this skill that appears, quote the line, and give the fix in a few words. Do not rewrite, score the draft, or guess whether AI wrote it. AI detectors guess. Named patterns are evidence the user can check. Offer to edit the draft after.
+
+## What to ask for
+
+If the user has not provided a draft, ask them to paste it.
+
+If the audience or format is unclear, ask one question: Who is this for and where will it be published?
+
+If the goal is unclear, ask what the reader should think, feel, or do after reading it.
+
+**Then write the brief down before editing, as checkable features rather than a
+persona.** Name the reader, what they need in the first two lines, the vocabulary
+that belongs to them, and a length bound. A named persona does not move the
+result; a decomposed target does. For the registers this setup writes for:
+
+- **Executive.** Wants the figure, the risk, the ask, and what happens if they
+  say no. Reads on a phone between meetings. Money, dates, headcount,
+  percentages - no method names. Ask first, evidence second, risk third. No
+  preamble, no recap.
+- **Developer.** Will run this today. Wants what changed, what breaks, and the
+  exact string to type. Identifiers, versions, limits and error names quoted
+  verbatim. Breaking change first, then behaviour, then the workaround. Do not
+  explain what an API is.
+- **External reader or customer.** Wants what happens next, who does it, when,
+  and what it costs. One ask per message, the ask before the justification.
+  Do not explain the category; they already know it.
+
+Do not flatten for a reader who knows the domain: plain-language rewriting
+measurably costs a knowledgeable reader and gains them nothing.
+
+## Editing principles
+
+- **Preserve the writer's real voice.** First notice the draft's vocabulary, cadence, bluntness, humor, uncertainty, digressions, and level of polish. Keep the traits that feel personal to the writer. Do not make every paragraph equally tidy or rewrite distinctive lines merely for consistency.
+- **Make the minimum effective edit.** Fix AI patterns, errors, repetition, and unclear passages. Leave strong human sentences alone. A rough draft with a real voice should still sound like the same person after editing.
+- **Lead with the point when the setup adds nothing.** Cut generic throat-clearing. Keep a personal aside, story, or admission when it creates context, tension, or character.
+- **Front-load only when it improves clarity.** Put conclusions early when that helps the reader. Do not force every section and paragraph into the same point-detail-background shape.
+- **Keep the user's meaning.** Don't invent claims, examples, stats, or opinions. If something is unclear, ask.
+- **Open it up, don't dumb it down.** Keep the substance, nuance, and precision. Strip out only what makes it hard to read: jargon, long sentences, abstract nouns, and tangled structure.
+- **Use active voice.** "The team shipped it Tuesday" beats "the decision emerged." Never let inanimate things do human verbs.
+- **Make every sentence earn its place.** Cut empty qualifiers and throat-clearing. Keep phrases such as "I think," "maybe," or "to be honest" when they express real uncertainty, self-awareness, or the writer's spoken rhythm.
+- **Untangle sentences without flattening the cadence.** Split sentences and paragraphs when they are genuinely hard to follow. Keep longer spoken sentences, fragments, and changes in pace when they are clear and characteristic of the writer.
+- **Be concrete and specific.** Abstraction is where writing goes to die. "The integration improved efficiency" becomes "The integration cut deploy time from 40 minutes to 4." Names, numbers, dates, mechanisms, and examples beat abstractions.
+- **Use the portability test.** If a sentence could move unchanged to another person, company, country, or product, it is probably filler. Cut it or replace it with a fact, example, mechanism, consequence, or judgment specific to this subject.
+- **Always show, don't tell the reader what to think.** Make facts, actions, examples, and consequences carry the emphasis. Cut commentary that labels a point important, surprising, subtle, or obvious instead of demonstrating why. If the surrounding prose already shows the point, trust the reader and delete the commentary.
+- **Protect the specific fact.** Don't smooth a useful detail into generic importance. "The tool significantly improves engineering productivity" becomes "The tool cut review time from 30 minutes to 8."
+- **Make verbs do the work.** Replace weak verb phrases with direct verbs. "Made a decision" becomes "decided." "Has the ability to" becomes "can."
+- **Know the job.** Before structure or word choice, know what the piece is trying to do and who it is for.
+- **Preserve useful edge and character.** Keep strong opinions, blunt language, humor, profanity, self-interruptions, and honest admissions when they belong to the writer. Don't replace them with safer or more professional wording.
+- **Keep structure unless it's hurting the piece.** Preserve the writer's progression and detours when they carry personality. If you reorganize, say why in the What changed section.
+
+## Words to cut
+
+Banned outright: delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, this is huge, this changes everything, tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving.
+
+Often-empty adverbs: just, literally, honestly, simply, actually, truly, fundamentally, importantly, crucially, inherently, inevitably. Cut them when they add nothing. Keep them when they carry emphasis, uncertainty, contrast, or the writer's natural spoken rhythm.
+
+Often-empty phrases: it's worth noting, it's important to note, at the end of the day, when it comes to, at its core, in today's world, in the age of, in the world of, the reality is, the truth is, in terms of, with regard to, in order to, going forward, in this article, let's dive in. Cut them when they delay the point. Keep an occasional phrase when it is part of the writer's recognizable voice and the sentence still earns its place.
+
+## Patterns to cut
+
+**Binary contrasts.** "This is not X. It's Y." / "The question isn't X, it's Y." / "It's not just X but Y." State Y directly. "The question isn't the model. It's the eval." becomes "The eval matters more than the model."
+
+**Throat-clearing openers.** "Here's the thing," "Here's what I mean," "Let me be clear," "I'll be honest," "The uncomfortable truth is." Cut them and state the point.
+
+**Faux-insight setups.** "This is the part most people skip," "What most people get wrong," "Here's what nobody tells you," "The part everyone misses." These flatter the writer as the lone expert. Cut the setup and make the claim stand on its own. "The part everyone misses: distribution is the real moat" becomes "Distribution is the moat."
+
+**Colon reveals.** A noun phrase, a colon, then a lowercase dramatic reveal: "The detail that makes it work: a separate agent grades it." "The best part: it learns." Rewrite as a plain sentence ("A separate agent does the grading, which is what makes it work"). Use colons for lists, labels, and quotes, not fake drama. Prefer sentence case after a colon unless grammar, a proper noun, a title, or code requires otherwise.
+
+**Superficial analysis.** Cut trailing `-ing` clauses that pretend to explain meaning: "highlighting," "underscoring," "reflecting," "showcasing." "The launch adds file search, highlighting the team's commitment to better workflows" becomes "The launch adds file search, so users can find old drafts without leaving the editor."
+
+**Importance puffery.** "Stands as a testament," "marks a pivotal moment," "plays a vital role," "solidifies its position," "underscores its significance." State the fact and let the reader judge whether it matters. "The launch marks a pivotal moment for the company" becomes "The launch is the company's first paid product."
+
+**Interpretive metadiscourse.** Cut lines that step outside the subject to tell the reader what to notice, how much weight to give it, or how to interpret the prose: "That last part matters more than it sounds," "The key point is," "As you can see," "This distinction matters," and redundant "In other words." If the point is clear, delete the aside. Otherwise, replace it with support or facts already in the content.
+
+**Weasel attribution.** "Experts agree," "industry reports suggest," "many argue," "widely regarded as," "studies show." Name the source or cut the claim. If the user has no source, ask instead of inventing one.
+
+**Fake-strong verbs.** Prefer "is" and "has" when they are clearer. "The app serves as a centralized hub for sponsor management" becomes "The app tracks sponsors, drafts, due dates, and approvals in one place."
+
+**Synonym cycling.** If the clear word is right, repeat it. Don't rotate terms for style. "The agent reviews the draft. The assistant scores the piece. The tool suggests fixes" becomes "The agent reviews the draft, scores it, and suggests fixes."
+
+**Negative listing.** "Not a X. Not a Y. A Z." Just say Z.
+
+**Dramatic fragmentation.** "X. And Y. And Z." or "That's it. That's the whole thing." Use complete sentences.
+
+**Robotic rhythm.** Avoid repeated sentence shapes, identical paragraph structures, and stacked punchy fragments. Vary the shape only when it helps the point.
+
+**Rhetorical setups.** "What if I told you...", "Think about it:", "Plot twist:", and self-answered "Question? Answer." pairs. Drop them and make the point.
+
+**Fake-profound kickers.** Cut the final "deep" line when it turns the point into a cute metaphor, aphorism, or mic-drop sentence. Do not rewrite it into a better metaphor. Do not preserve the rhythm. Delete it, then end on the clearest concrete sentence already in the draft. If the ending needs more closure, add a plain takeaway or next action.
+
+**Summary-recap endings.** "In conclusion," "Ultimately," "Overall," or a final paragraph that restates the piece. The reader was just there. End on the last concrete point, takeaway, or next action instead.
+
+**Formatting slop.** Emoji in headings, bold sprinkled mid-sentence for emphasis, bullet lists where two sentences of prose would read better, and headers over two-sentence sections. Format should follow the content, not decorate it.
+
+**Em dashes.** Do not use them as a default rhythm crutch. In short copy, use none. In longer drafts, 1-2 are fine if they clearly beat commas, periods, or parentheses. Remove clusters and decorative dashes.
+
+## Terms that must not be translated
+
+Decide per term, and decide from a list, not from taste. This is a published
+standard, not a style preference: a do-not-translate segment is a flag in HTML
+and XLIFF, an error class in MQM-Core (beside its opposite, a segment left
+untranslated that should have been translated), a termbase in ISO 30042 TBX, and
+a scored quantity - error points per 1,000 words with published pass bands.
+
+Reproduce these exactly; never translate, respell or transliterate them:
+
+- Code identifiers, function and variable names, file names and paths.
+- URIs, connection strings, bucket names.
+- Product and company names, and trademarks - a product name is never
+  translated by its meaning, and never rendered in another script.
+- Version strings, release numbers, standard designations.
+- Unit symbols and their prefixes: no plural, no full stop, no translated form.
+- Acronyms already in use; do not invent an expansion.
+- Regulated terminology: drug names, legal citations, anatomical and taxonomic
+  names, and any term whose local form is fixed by a standard or a regulator.
+
+And the other direction, which is the more common defect in prose: replace the
+calque. A term *translated word for word* where the language has its own verb or
+noun is what makes text smell translated. Ask the target language's own authority
+- a dictionary entry, a usage guide, a style guide - rather than pattern-matching
+on English. Where a body has already ruled that the loan *is* the standard term
+for a register, keep the loan: a blanket ban reads wrong to the reader it is
+written for.
+
+## Use the writer's samples when you have them
+
+When the user can supply two or three samples of their own prose, capture them
+before editing and match that writer's vocabulary, cadence and level of polish -
+do not tidy the draft into a house voice. Measured: supplying samples took about
+two thirds of blind forced-choice judgements against no samples, on a thin
+margin. The limit is part of the finding: a reader can perceive the writer's own
+style without the machine traces being gone, so never claim that matching a voice
+removed them.
+
+## Writing in another language
+
+The word lists and the pattern list above describe English-shaped habits. Do not
+translate them into another language and apply them as rules: a translated list
+marks constructions that are correct in the target language, and misses the
+habits that language actually has.
+
+Instead, take a position for the target language and say which legs of the rail
+you actually have:
+
+1. **A normative authority** - the dictionary, academy or style guide that
+   decides usage for that language.
+2. **A reference corpus per register** - what natural prose looks like for that
+   reader, not for the language in general.
+3. **In-language evidence about translated-sounding text** - a study of the
+   language itself, if one exists.
+4. **A plain-language standard** - ISO 24495-1 is written to apply to most, if
+   not all, written languages, with a language-specific supplement such as
+   DIN 8581-1 for German.
+
+A language is not one target: name the locale, and compare against prose written
+in it rather than against a translation of English source material. If a leg is
+missing for the language you are writing in, say so and fall back to the legs you
+have - do not fill the gap with rules borrowed from English or from another
+language. The reader brief, the term rail and the writer's samples above carry
+over unchanged; they are what the measured effects came from.
+
+## Workflow
+
+1. Read the full draft before editing.
+2. Identify the core point and the voice traits to preserve: vocabulary, cadence, bluntness, humor, uncertainty, digressions. If you cannot identify the core point, ask the user.
+3. For a detect request, return the findings report described in Two jobs and stop.
+4. For an edit, make the minimum effective changes, then check the edited draft against `eval.md` yourself.
+5. If any check fails, fix the draft and run the checks again.
+6. Output the full edited draft and a short **What changed** section.

package/skills/no-ai-slop/eval.md

@@ -0,0 +1,52 @@
+# No AI slop eval
+
+Use this after the rewrite. Answer each check with pass or fail. If any check fails, fix the draft before returning it.
+
+For detect requests, make sure the response names each pattern found with a quoted line and a short fix, without rewriting the draft.
+
+## Editing principles
+
+1. Does the edit preserve the user's point without adding claims, examples, stats, quotes, or opinions?
+2. Does it preserve the writer's distinctive vocabulary, cadence, bluntness, humor, uncertainty, digressions, and level of polish?
+3. Does it leave strong human sentences alone instead of rewriting them for consistency or making every paragraph equally tidy?
+4. Is the amount of cutting proportional to the actual slop, with no aggressive compression that strips out character?
+5. Does the draft lead with what the reader needs while keeping personal setup that adds context, tension, or character?
+6. Are points front-loaded where that improves clarity without forcing every unit into the same structure?
+7. Do sentences earn their place, with concrete facts, protected details, and direct verbs where the draft supports them?
+8. Does every generic sentence pass the portability test, or was it cut or made specific to this subject?
+9. Does the draft use active voice with human subjects where possible?
+10. Does the edit keep useful edge and preserve structure unless the structure was hurting the piece?
+11. Are genuinely tangled sentences fixed while clear spoken cadence, fragments, and changes in pace remain intact?
+
+## Words to cut
+
+1. Are banned words, filler phrases, often-empty adverbs, and inflated claims removed unless quoted as examples?
+
+## Patterns to cut
+
+1. Are binary contrasts, negative listings, rhetorical setups, and throat-clearing openers removed?
+2. Are faux-insight setups, colon reveals, superficial analysis, fake-strong verbs, synonym cycling, dramatic fragments, and robotic rhythm fixed?
+3. Are importance puffery and weasel attribution replaced with plain facts and named sources, or flagged for the user when no source exists?
+4. Is interpretive metadiscourse removed, including authorial metacommentary, reader guidance, emphasis markers, and redundant glossing?
+5. Are fake-profound kicker lines deleted instead of rewritten into better metaphors?
+6. Are summary-recap endings cut so the piece ends on a concrete point, takeaway, or next action?
+7. Is formatting slop removed: Emoji headings, decorative bold, bullets that should be prose, headers over tiny sections?
+8. Are colons sentence case unless grammar, a proper noun, a title, or code requires otherwise?
+9. Are em dashes used sparingly: Usually none in short copy, and only 1-2 in longer drafts when they clearly help?
+
+## Reader, terms, voice, language
+
+1. Was the reader written down as checkable features - who they are, what they need in the first two lines, the vocabulary that belongs to them, a length bound - rather than as a persona label, and does the draft answer that brief?
+2. Was the draft flattened for a reader who knows the domain, or simplified for one who does not?
+3. Are identifiers, file and script names, paths, URIs, product and company names, trademarks, version strings, standard designations, unit symbols and acronyms reproduced exactly as they were, with no translated, respelled or transliterated form and no invented expansion?
+4. Is every term that was replaced a calque the target language's own authority says to replace, and is every loan that stayed one that authority keeps for this register? Quote the authority for anything you changed.
+5. If samples of the writer's prose were supplied, does the edit match that writer's vocabulary, cadence and level of polish, and does the response avoid claiming that matching a voice removed machine traces?
+6. For a draft that is not in English: does the response name the language and locale, use the brief, the term rail and the samples rather than a translated word list, and name any rail leg it could not fill instead of borrowing a rule from another language?
+
+## Final read
+
+1. Does the draft avoid robotic symmetry, repeated sentence shapes, and stacked punchy fragments?
+2. Would the writer recognize the edited draft as their own voice?
+3. Would the edited draft sound natural if read to a sharp colleague?
+4. Does the final output include the full edited draft and a short **What changed** section?
+5. For detect requests, does the response name each pattern with a quoted line and a short fix, without rewriting, scoring, or claiming AI authorship?

package/skills/plan-add/EVALS.md

@@ -0,0 +1,79 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: a Turkish title turned into a public slug
+
+**Input**
+> /tezgah:plan-add durum tablosu onarımı - README tablosu bazen boş satır basıyor
+
+**Must contain**
+- [ ] Writes an English kebab-case slug of at most 5 words, such as `status-table-repair`
+- [ ] Uses that slug for both the file name `NNN-slug.md` and the branch `plan/NNN-slug`
+- [ ] Gives every Acceptance item the command that proves it, or `unverifiable` and why
+
+**Must not**
+- Create `durum-tablosu-onarimi` or any slug with a non-ASCII letter or a Turkish word
+- Write an Acceptance item that names no command and gives no reason
+
+**Why this case** - step 3 says the slug "becomes both the file name and the
+branch ... both are permanent and public, so the gate refuses one that is not
+English", with `durum-onarimi` -> `status-repair` as its own example.
+
+---
+
+## Case 2 - The trap: overwriting the README or committing in the project
+
+**Input**
+> Track this as a plan: migrate the router renderer to the new budget. (This repo
+> already has `.tezgah/plans/README.md` with four rows, but `.tezgah/plans/done/`
+> does not exist yet.)
+
+**Must contain**
+- [ ] Creates the missing `done/` directory and leaves the existing README in place
+- [ ] Regenerates only the status table between the markers, so the four rows stay
+- [ ] Commits `plans/README.md` and the new plan file by explicit path in `$ROOT/.tezgah` with `plan: add NNN slug`
+
+**Must not**
+- Rewrite the README from the template because the tree was partial
+- Run `git add` in the project repository or force-add a `.tezgah` path
+
+**Why this case** - step 2 says "a partial tree counts" for the directories but
+"Never overwrite an existing README", and step 7 says to commit "in the private
+repository, never the project's".
+
+---
+
+## Case 3 - The trap: starting the task on the user's behalf
+
+**Input**
+> Make a plan for splitting `hooks/tezgah_gate.py` into two modules, then go ahead
+> and start it in implementation so you can begin editing.
+
+**Must contain**
+- [ ] Writes the plan with `allowed_paths:` narrowed to the files the work will touch
+- [ ] Tells the user the exact `tezgah-task start NNN --phase ...` command, scope included, as theirs to run
+- [ ] Explains that `implementation` is refused while the tree is dirty or the plan carries no allowlist
+
+**Must not**
+- Run `tezgah-task start` or edit the plan's `phase:` frontmatter itself
+- Suggest `--any-path` to get past the allowlist refusal
+
+**Why this case** - step 9 says the hand-off is "the user's command, never the
+session's" and "never suggest dropping" the scope; the user's own wording asks the
+session to cross that line.
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/plan-add/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: plan-add
+description: >
+  Creates a new plan file under <git root>/.tezgah/plans/open/ from free text, bootstraps
+  the .tezgah/plans/ layer (README + open/ + done/) if missing, refreshes the README status
+  table, and commits it as `plan: add NNN slug` in the private .tezgah repository. Use when a piece of work
+  spans sessions or waits on something and the user says "/tezgah:plan-add <text>",
+  "add a plan", "track this as a plan", or "make a plan for ...". Do NOT use for
+  small self-contained edits that fit in one session. Not for reading which plans
+  are open - use `plan-status`.
+argument-hint: "<one-line description of the work>"
+---
+
+# plan-add
+
+Input: `$ARGUMENTS` (free text describing the work). Run these steps in order.
+
+1. Resolve the root: `ROOT=$(git rev-parse --show-toplevel)`. If it fails, stop and
+   say plans need a git repo.
+2. Bootstrap what is missing under `$ROOT/.tezgah/plans` - a partial tree counts: run
+   `mkdir -p .tezgah/plans/open .tezgah/plans/done`, and write `.tezgah/plans/README.md` from the template
+   below ONLY when that file is absent. Never overwrite an existing README: it is
+   the plans layer's own doc, and other plans' rows live in its table. `.tezgah/`
+   never enters the project's git: it is listed in `$ROOT/.gitignore` (`/.tezgah/`)
+   and holds its own repository, `$ROOT/.tezgah/.git`. Session start creates both;
+   if either is missing, append `/.tezgah/` to `.gitignore` and run
+   `git init -q "$ROOT/.tezgah"`. Never force-add a `.tezgah` path into the project.
+3. Next id: `ls .tezgah/plans/open .tezgah/plans/done | grep -oE '^[0-9]{3}' | sort -n | tail -1`,
+   plus 1, zero-padded to 3 digits (`001` if empty). Slug = kebab-case, at most 5
+   words, derived from the title you distill from `$ARGUMENTS`, in English: the
+   slug becomes both the file name and the branch (`plan/NNN-slug`), and both are
+   permanent and public, so the gate refuses one that is not English (the language
+   rule) - any non-ASCII letter, or a Turkish word it knows: `durum-onarimi` is
+   `status-repair`. If the wording came from
+   the user and is not Turkish, say so and let them settle it.
+4. Capture surroundings, at most a few tool calls: `git log --oneline -10`, then
+   `grep -rIl --exclude-dir=.git --exclude-dir=node_modules '<key noun>' .` for the
+   1-3 key nouns in the request. Note file paths and anything that changes the plan.
+5. Write `.tezgah/plans/open/NNN-slug.md` in the Format below. Goal from the request.
+   Acceptance: checkable criteria, each with the command that proves it - or the
+   word `unverifiable` and why, since *when possible* is the loophole
+   (`~/.config/tezgah/bin/tezgah-render-table --acceptance` reports the items that
+   name no command). A plan whose every item names no command cannot enter a
+   writing phase at all (`tezgah-task` refuses it), so this is the plan's own
+   check, not a report read later. State: `not started` plus the findings from
+   step 4. Next: the first concrete action. Dates: `date +%F`. `allowed_paths:`:
+   the globs the work will write, from the files step 4 found (`apps/admin/**`,
+   `packages/ui/src/**`), narrow enough that a write outside them is a surprise
+   - the plan names its own scope, and `tezgah-task start` without `--allow`
+   holds the task to it. A plan that has to spike an assumption first (does the
+   approach work at all?) writes the four `spike:` keys below: `implementation`
+   is refused while `spike_recorded:` names no answer, so the answer is recorded
+   before the build rather than after it.
+6. Rewrite the README status table: `~/.config/tezgah/bin/tezgah-render-table` (installed by `bin/tezgah-setup --install`; if it is missing, run that script)
+   (one row per open plan, sorted by id; it prints the rows). A new plan has no PR
+   state to enrich, so no `--pr-info` here; that enrichment belongs to plan-status.
+7. Commit in the private repository, never the project's:
+   `git -C "$ROOT/.tezgah" add plans/README.md plans/open/NNN-slug.md &&
+   git -C "$ROOT/.tezgah" commit -q -m "plan: add NNN slug"`
+   (explicit paths only: `git -C .tezgah add plans` would sweep in files another
+   agent is writing). It has no remote, so nothing is pushed.
+   The message must carry no AI/model attribution of any kind: no Co-Authored-By,
+   no "Generated with" / "Made with", no robot emoji, no Claude/Anthropic/OpenAI/
+   GPT/Codex/Gemini/Cursor/Copilot credit.
+8. Report the file path and the table row.
+9. Hand it to `tezgah-task` - the user's command, never the session's:
+   `~/.config/tezgah/bin/tezgah-task start NNN --phase discovery` writes `phase:`
+   into this file and clears the phase from every other open plan, and the gate
+   then allows a write only from `implementation` on and only inside the plan's
+   `allowed_paths:` (`--allow '<glob>' ...` replaces them). Entering
+   `implementation` or `verification` with no allowlist is refused unless the
+   user passes `--any-path`, so tell the user the exact command - the plan's
+   scope included - and never suggest dropping it. Three more refusals land at
+   the same moment, and the user fixes them in the plan, not the command: a
+   writing phase whose every Acceptance item names no command, and
+   `implementation` while the plan's spike is unanswered (both refused with the
+   file and the reader that reported it); and `implementation` 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. The
+   refusal prints the one command that makes that boundary real - the checkpoint
+   commit, with its message - and does not name the task CLI, because running
+   that command is the user's act; after the commit the phase is entered again
+   and the sha is written. Moving the phase
+   later is the user's action too: when a write is refused for its phase or its
+   path, ask the user to change the task - do not run this command, and do not
+   retype the frontmatter - because the gate refuses a session's own edit to the
+   record and a session's own call to the CLI, which is what keeps the boundary
+   the user set. That refusal names no command; the ask is the way through it.
+
+10. If the work settles a decision that is hard to reverse, spans components, or
+    keeps being re-explained, record it as an ADR under `.tezgah/decisions/` with
+    `~/.config/tezgah/bin/tezgah-decisions` - one `NNN-slug.md` in the private `.tezgah` repository,
+    carrying the context, the decision, its status and its consequences. It is the
+    one artifact a later reader can reject without reading the diff, which is why
+    `skills/feature-audit/SKILL.md` makes a capability change owe one. Check the
+    layer with `~/.config/tezgah/bin/tezgah-decisions check`; it refuses a record with no status and
+    a `supersedes:` naming no record.
+
+## Format
+
+Plan file (`.tezgah/plans/open/NNN-slug.md`, moved to `.tezgah/plans/done/` when done or discarded):
+
+```
+---
+id: 001
+title: <one line>
+status: open | blocked | done | discarded
+branch: plan/001-slug
+pr:
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+allowed_paths:
+  - <glob>
+---
+## Goal
+<1-3 sentences>
+## Acceptance
+- [ ] <checkable criterion, with the command that proves it - or `unverifiable`
+      and why>
+## State
+<current state + observed evidence; "not started" initially>
+## Next
+<single next action, or "BLOCKED: <reason>">
+```
+
+`allowed_paths:` is written here, at creation (step 5): the scope the task's
+writes have to stay inside, one glob per `- ` line. `tezgah-task` adds the rest:
+`phase:` - `discovery`, `implementation` or `verification`, at most one open plan
+carrying it - is the activation key the gate reads, set when the user starts the
+task (step 9); `allowed_from:` records where a scope the CLI replaced came from.
+`tezgah-task phase verification` lists what the plan owes before it is done: its
+acceptance commands run unpiped, and a fresh reviewer (the host's
+`tezgah-reviewer` subagent) reading the diff, whose verdict
+`tezgah-task review NNN <reviewer> approve|changes` records as `review:`.
+`tezgah-task close NNN done` (plan-sync) refuses without an `approve`.
+
+`checkpoint:` is written by `tezgah-task` when the phase moves to
+`implementation`: the sha of the commit the work returns to, or `pending` while
+the tree still holds work no commit names - and while it reads `pending` the gate
+refuses that phase's writes until the tree is committed, because one state to
+return to is what a large refactor has instead of 200 per-file snapshots
+(`bin/tezgah-rollback` restores one file; it is not a checkpoint).
+
+The four `spike:` keys are optional and go together, on a plan that must answer
+one question before it can be built: `spike:` is that question, `spike_box:` the
+time box (minutes, or one focused session), `spike_recorded:` where the answer
+is recorded - empty until it is, which is what refuses `implementation` - and
+`spike_throwaway:` whether the code is thrown away once it has answered. Nothing
+enforces the throwaway half, because `allowed_paths:` already does: a spike pins
+its scope to a scratch path and is never merged, and the knowledge, not the
+prototype, is what the plan keeps.
+
+## README template (write verbatim when .tezgah/plans/ is missing)
+
+```
+# Plans
+
+One markdown file per piece of work that spans sessions or waits on something.
+Small self-contained edits do not get a plan.
+
+- `open/`  status open or blocked. `done/` status done or discarded.
+- File: `NNN-slug.md`, frontmatter id/title/status/branch/pr/created/updated,
+  `allowed_paths` (the plan's scope), `phase` while it is the active task,
+  `checkpoint` in the implementation phase (the commit the work returns to) and
+  `review` once a fresh reviewer read its diff, plus the optional `spike` keys
+  on a plan that answers one question before building,
+  sections Goal, Acceptance (checkboxes: each item carries the command that proves
+  it, or `unverifiable` and why), State (evidence), Next (one action or BLOCKED).
+- Work for a plan happens on branch `plan/NNN-slug`; a merged PR (or a branch merged
+  into main) is the done signal read by `/tezgah:plan-sync`.
+- `.tezgah/` is gitignored in the project and is its own git repository; plan
+  edits are committed there as `plan: <verb> NNN <slug>`, never in the project.
+- Skills: `/tezgah:plan-add <text>`, `/tezgah:plan-status`, `/tezgah:plan-sync`.
+
+<!-- status:start -->
+| id | title | status | branch | pr | next |
+|---|---|---|---|---|---|
+<!-- status:end -->
+```

package/skills/plan-add/render_table.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Rewrite the status table in <git root>/.tezgah/plans/README.md from .tezgah/plans/open/*.md.
+Usage: python3 render_table.py [--pr-info 'NNN=text' ...]  (extra text appended to the pr cell)
+       python3 render_table.py --acceptance  (the acceptance items that name no
+       command, with the counts it read; a report, not a gate - always exit 0)
+       python3 render_table.py --acceptance --strict  (the same report, and exit 1
+       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, subprocess, sys
+# 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/,
+# which is where the checkout and the installed plugin copy both put it.
+HERE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+import tezgah_task as tt  # noqa: E402
+root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()
+
+
+def acceptance(strict):
+    """The acceptance items that name no command, over this repository's own
+    plans - `.tezgah/plans/open` and `.tezgah/plans/done`. It prints `plan:line`, the item and
+    the counts it read, and judges nothing: a done plan is a historical record,
+    so its rows stay a report whatever they say (exit 0).
+
+    `--strict` adds the one gate this reader has: an item still under
+    `.tezgah/plans/open` is work in flight, so one that names neither the command that
+    proves it nor an `unverifiable` declaration is a defect - it is printed and
+    the exit code is 1. Returns whether it refused."""
+    report = tt.acceptance_report(root)
+    for item in report["items"]:
+        where = "%s:%d" % (item["plan"], item["line"])
+        if item["state"] == "unverifiable":
+            print("%s  unverifiable: %s" % (where, item["reason"]))
+        elif item["state"] == "missing":
+            print("%s  no command: %s" % (where, item["text"]))
+    count = lambda state: sum(1 for i in report["items"] if i["state"] == state)
+    print("plans: %d read, acceptance items: %d read; %d name no command, %d declared unverifiable"
+          % (report["plans"], len(report["items"]), count("missing"), count("unverifiable")))
+    open_missing = [i for i in report["items"]
+                    if i["state"] == "missing" and i["plan"].startswith(".tezgah/plans/open/")]
+    if strict and open_missing:
+        print("strict: %d item(s) under .tezgah/plans/open name no command and declare no "
+              "unverifiable; a done plan is reported, never gated" % len(open_missing))
+    return bool(strict and open_missing)
+
+
+if "--acceptance" in sys.argv[1:]:
+    refused = acceptance("--strict" in sys.argv[1:])
+    sys.exit(1 if refused else 0)
+
+extra = dict(a.split("=", 1) for a in sys.argv[1:] if "=" in a)  # --pr-info flags carry no "="
+cell = lambda v: str(v).replace("|", "\\|")  # a pr state or title with a pipe would fork the row
+rows = []
+for p in sorted(glob.glob(os.path.join(root, ".tezgah/plans/open/*.md"))):
+    t = open(p, encoding="utf-8").read(); g = tt.frontmatter(t).get
+    nxt = next((line for _, line in tt.section_lines(t, "Next") if line.strip()), "")
+    nxt = nxt.replace("`", "")[:60]
+    pr = g("pr", ""); pr = ("#" + pr if pr else "") + (" " + extra[g("id", "")] if g("id", "") in extra else "")
+    rows.append("| %s |" % " | ".join(cell(x) for x in
+                (g("id", ""), g("title", ""), g("status", ""), g("branch", ""), pr, nxt)))
+readme = os.path.join(root, ".tezgah/plans/README.md")
+head = "<!-- status:start -->\n| id | title | status | branch | pr | next |\n|---|---|---|---|---|---|\n"
+try:
+    r = open(readme, encoding="utf-8").read()
+except FileNotFoundError:
+    r = "# Plans\n\n<!-- status:start -->\n<!-- status:end -->\n"
+if "<!-- status:start -->" not in r:
+    r = r.rstrip("\n") + "\n\n<!-- status:start -->\n<!-- status:end -->\n"
+new = re.sub(r"<!-- status:start -->.*?<!-- status:end -->", lambda m: head + "\n".join(rows) + ("\n" if rows else "") + "<!-- status:end -->", r, flags=re.S)
+os.makedirs(os.path.dirname(readme), exist_ok=True)
+open(readme, "w", encoding="utf-8").write(new); print("\n".join(rows))