@event4u/agent-config 16.2.0 → 16.4.0

package/dist/agent-src/skills/git-workflow/references/commit-subject.md

@@ -0,0 +1,205 @@
+# The ticket, the commit subject and the branch name
+
+Detail for [`git-workflow`](../SKILL.md) and
+[`conventional-commits-writing`](../../conventional-commits-writing/SKILL.md).
+The one place that says how a ticket is read out of a branch name, where it goes
+in a commit subject, which convention is in force, and how a branch name is
+rendered. `/commit`, `/commit:in-chunks`, `/fix:commit-messages`,
+`/create-pr:description-only`, `/worktree:create` and the `jira-integration`
+skill defer here.
+
+The rules are code: `agent-config git:convention` runs them, and the commands
+call it. This page is what a command reads **when the verb cannot run** — no
+`agent-config` on `PATH`, or exit `2` for a usage or unknown-verb error. Then
+apply the generated block below by reading, say once that the verb was
+unavailable, and never invent a grammar the block does not show. Exit `2` with
+`no subjects on stdin — the verb ran` is not that case: the verb ran and
+received nothing, so pipe the subjects again rather than falling back.
+
+## Reading the ticket
+
+`agent-config git:convention ticket [BRANCH] [--keys "<line>"]` — the current
+branch when `BRANCH` is omitted. It prints `ticket <ID>` or `ticket none`, then
+every candidate with its status:
+
+- **Every match counts**, in order, wherever it sits (`feat/DEV-1234/...`,
+  `DEV-1234-device-export`, `fix/DEV-1234-quantity` → `DEV-1234`). The match
+  never depends on `git.branch_pattern`, so a branch named before the pattern was
+  set still yields its ticket. The first candidate with status `ticket` wins.
+- **`standard-name`** — a key in the denylist (`UTF-8`, `ISO-8601`, `SHA-256`,
+  `CVE-2026-12345`, `CWE-79`) is never a ticket, with or without a card:
+  `fix/CVE-2026-12345-patch` yields none.
+- **`version-like`** — without a card, a protocol or language name followed
+  by a one-digit number (`HTTP-2`, `PHP-8`; the list is the `version-like names`
+  row below) is a major version, not a ticket: `feat/HTTP-2-support` yields
+  none. Two or more digits (`PHP-12`) read as a ticket, and a card that lists
+  the key keeps it a ticket.
+- **Case** — without a card only an upper-case key is detected, so
+  `feat/dev-12-export` yields none. With `--keys`, a key written in any case is
+  matched against the card and reported upper-cased (`dev-12` → `DEV-12`).
+- **`unknown-key`** — `--keys` takes the `ticket_keys` line of the approved
+  convention card (`agents/memory/curated/conventions/approved/commit-subject.md`,
+  see the [`conventional-commits-writing`](../../conventional-commits-writing/SKILL.md)
+  skill § 4), as the caller reads it. A candidate whose key is not on it is
+  asked about by `/commit` — a yes adds the key to the card — and omitted by
+  `/commit:in-chunks`. Without a card the grammar, the denylist and the
+  version-like names decide alone.
+- **`proposal`** — without `--keys`, a commitlint config's `issuePrefixes` are
+  printed as a proposed `ticket_keys` line. Offer it; the verb writes nothing.
+
+## Placing the ticket
+
+| `git.commit_format` | With a ticket | Without a ticket |
+|---|---|---|
+| `ticket-scope` (default) | `feat(DEV-1234): add export filter` | `feat: add export filter` — never `feat(): …` |
+| `ticket-conventional` | `DEV-1234 feat(exporter): add export filter` | `feat(exporter): add export filter` |
+
+Under `ticket-conventional` **a ticket is never in the scope** — not as the
+scope, not inside a compound one (`feat(api,DEV-1234)` fails). The scope names
+the system area (`api/audio`, `ci`), only where it adds clarity.
+
+**Under an approved family** (the card's `dominant_family`) the ticket is
+optional, as under `ticket-conventional`: with a ticket it stands in the
+family's leading position (`[DEV-1234] Add export filter`), without one the
+subject is the family's form without the ticket part (`Add export filter`), and
+a ticket anywhere else fails. A branch without a ticket is therefore never a
+stop under a card.
+
+Git's own `fixup!`, `squash!`, `amend!` and `Revert "…"` subjects are valid under
+both `git.commit_format` values and under every family: git writes them itself,
+so the same rule holds everywhere a subject is checked.
+
+**Area scope under `/commit:in-chunks`.** Several commits on one branch carry the
+same ticket in front of each; the scope is chosen per commit from the area that
+commit touches, and dropped where no single area fits. A chunk never inherits
+another chunk's scope.
+
+## Which convention is in force
+
+`agent-config git:convention subject` reads subjects on stdin, one per line, and
+resolves the convention in this order — the first that applies decides:
+
+1. **A declaration** — `git.commit_format` in `.git-convention.yml` (either
+   value; ADR-283), or a developer settings file value other than the template
+   default. The rule is one for both values: `settings:sync` writes the
+   template default into every project file, so a default there cannot be told
+   apart from an insert and never outranks an approved card, whichever value
+   the default is; today that makes `ticket-conventional` the only developer
+   value that counts.
+2. **An approved measurement** — the card's `dominant_family`.
+3. **The default** — Conventional Commits (`ticket-scope`).
+
+When the third case decides — no declaration and no approved card — and the
+repository has no commitlint config, `subject` and `show` add the line `no convention established — run git:convention measure`
+(`convention_established: false` under `--json`); the exit is unchanged.
+A commitlint config is the repository's own subject validator, so it
+establishes the convention: no such line, and `measure` says the config governs.
+`agent-config git:convention measure [--limit N] [--family F] [--json]` then reads
+the history of the default branch — the one the server names, else
+`refs/remotes/origin/HEAD`; with neither it samples nothing, exits 1 and says so
+(`trunk_unresolved` under `--json`) rather than guess one. It proposes a subject family when one clears the `measure bar` row
+of the block below, otherwise names the two strongest; it proposes a
+`branch_pattern` from the remote branch names, or `no clear pattern`; and it
+shows the observed update style, which is never adopted. Where the chosen family
+maps to a `git.commit_format` value or a pattern was proposed, it prints the
+ready-to-commit content of `.git-convention.yml` (`commit_format`,
+`branch_pattern`, never `update_strategy`); the verb writes nothing. A human
+creates and commits that file, or, on the user's yes this turn,
+`agent-config git:convention init --yes [--commit-format F] [--branch-pattern P]`
+creates it once — never over an existing carrier, never `update_strategy`, and
+uncommitted (ADR-283 § Creation). `/commit` asks the user once and writes the answer
+to the approved card.
+
+A repository validator — a `commit-msg` hook, a commitlint config (any of its
+config files, or a `commitlint` key in the package manifest) — does not decide, and
+the verb never guesses what it accepts: a hook's existence says nothing about
+what it checks, and a config is only known by running it. Each one found adds a
+`note:` line (and a `notes` entry under `--json`) saying it also runs at commit
+time and may be stricter; the exit is the verdict of the order above alone. A
+hook counts only where git will run it — the path git resolves, so
+`core.hooksPath` is respected and `.husky/commit-msg` counts only when
+`core.hooksPath` points at `.husky`. When the validator rejects a commit the
+verb passed, the rejection is the answer: fix the subject or settle the two in
+`.git-convention.yml`.
+
+A format that cannot be read (`malformed`, `invalid`, `discarded`), or an
+approved family with no grammar, exits `1` with the line that says why; it is
+never read as the default.
+Exit `1` also lists each failing subject with the rule it broke. Exit `2` is a
+usage error; an empty stdin is one, and says `the verb ran`. How a family is measured and approved is the
+[`conventional-commits-writing`](../../conventional-commits-writing/SKILL.md)
+skill's procedure; this page only consumes its card.
+
+## A title that becomes a commit
+
+Where the forge squash-merges — the method `/pr:merge` § 9 reads — the pull
+request title becomes the commit subject on the base, so `/create-pr:description-only`
+§ 3 builds it as a subject in the convention in force and checks it through
+`git:convention subject`, for `ticket-scope` as well as for `ticket-conventional`.
+Under any other merge method the title stays `DEV-1234: summary`.
+
+## Rendering a branch name
+
+`agent-config git:convention branch --slug <slug> [--type <type>] [--ticket <ID>]`
+renders `git.branch_pattern` (default `{type}/{slug}`) and prints the name:
+
+- an empty placeholder drops with the separator after it, or the one before it
+  when it is last (`{ticket}-{slug}` without a ticket → `<slug>`);
+- a ticket the pattern has no slot for prefixes the slug
+  (`{type}/{slug}` → `feat/DEV-1234-export`);
+- a literal character of the pattern is never rewritten, and a value outside
+  `[A-Za-z0-9._-]` is refused (exit `1`), not repaired.
+
+A guideline that shows another shape, such as `{type}/{ticket-id}/{short-description}`,
+describes a team habit; the name the agent creates follows the declared pattern.
+
+## The grammar
+
+<!-- BEGIN GENERATED: git-convention-grammar -->
+<!-- Written by `./scripts-run src/scripts/generate_git_convention_grammar` from `src/scripts/_lib/git_convention_grammar.ts` and `src/scripts/_lib/git_convention_measure.ts`; edit the modules, never this block. -->
+
+```
+ticket                                 [A-Z][A-Z0-9]+-[0-9]+
+ticket in text                         (?<![A-Za-z0-9])[A-Z][A-Z0-9]+-[0-9]+(?![0-9])
+standard names                         UTF ISO SHA RFC CVE CWE GHSA
+version-like names                     HTTP HTTPS TLS SSL OAUTH PHP PYTHON JAVA JDK NODE ES HTML CSS (one-digit number, no card)
+format ticket-scope                    ^(feat|fix|chore|docs|refactor|test|perf|style|build|ci|revert)(\([^)]+\))?!?: .+
+format ticket-conventional             ^([A-Z][A-Z0-9]+-[0-9]+ )?(feat|fix|chore|docs|refactor|test|perf|style|build|ci|revert)(\([^)]+\))?!?: .+
+family conventional                    ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?!?: 
+family ticket-conventional             ^[A-Z][A-Z0-9]+-[0-9]+ (build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?!?: 
+family ticket-prefix                   ^\[[A-Z][A-Z0-9]+-[0-9]+\][: ]|^[A-Z][A-Z0-9]+-[0-9]+[: ]
+family gitmoji                         ^:[a-z0-9_+-]+:[[:space:]]|^[^ -~[:cntrl:][:space:]]
+family imperative-plain                ^[A-Z][a-z]+[[:space:]].*[^.]$
+family ticket-prefix, no ticket        ^\S.* (no ticket elsewhere in the subject)
+family ticket-conventional, no ticket  ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?!?:  (no ticket elsewhere in the subject)
+any format or family                   ^((fixup|squash|amend)! .+|Revert ".+")$ (git's own subjects)
+measure sample                         newest 200 non-merge commits since 24 months ago, or regardless of age when that window yields fewer than 30; bots, automation subjects, commits over 500 files dropped
+measure bar                            n >= 30; >= 80 % capped at 20 per author per half (3+ authors), else >= 90 % uncapped; both halves agree
+measure migration                      the newer half, or the newest 30 commits, clearing the bar on another family than the dominant one: "migrating to <family>", and that family is proposed
+measure branches                       >= 10 remote branch names, top shape >= 80 %
+```
+
+Formats are JavaScript / PCRE syntax; families are POSIX extended, matched in
+order, first hit wins. Under `format ticket-conventional` and `family
+ticket-conventional` a ticket anywhere inside the scope fails, and a standard
+name in the ticket position fails. A ticket is found in a branch or scope only as
+a whole token (`ticket in text`). Without a card, a version-like name — one of
+the keys above with a one-digit number, such as `HTTP-2` or `PHP-8` — is not a
+ticket; `HTTP2-1` still has the ticket shape. A convention card's `ticket_keys`
+settles both, and matches a key written in lower case; without a card a
+lower-case key is never detected.
+<!-- END GENERATED: git-convention-grammar -->
+
+## Patterns that are not this grammar
+
+- **Suggester metadata.** The `trigger_context:` frontmatter of
+  `src/domains/engineering-base/implement-ticket/command.md` and
+  `src/domains/product-basic/estimate-ticket/command.md`, and the same literal in
+  `src/scripts/migrate_command_suggestions.ts`, match a bare-key ticket in a
+  prompt to decide when a command is suggested. They keep their own pattern:
+  changing it changes when a command is offered.
+- **The suggester's matcher.** `src/scripts/command_suggester/match.ts` carries
+  the ticket grammar above; a test pins the two equal.
+- **A project key in a ticket body.** `src/scripts/refine_ticket_detect.ts` reads
+  a project key out of ticket text, not a branch, and is intentionally
+  independent.

package/dist/agent-src/skills/iconography/SKILL.md

@@ -42,7 +42,7 @@ execution:
    is the anti-pattern [`icon-consistency`](../../rules/icon-consistency.md)
    § What this gates names by name. Stop at the first rung that answers.
    1. **A brand token or brand guide that names an icon set** — authoritative,
-      stop here ([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).
+      stop here (`brand-source-of-truth`).
    2. **The set already in use in this project** — detected at the Inspect step
       of the Iconography floor below. One icon system per project; a second
       visual language is the defect, not a preference.

package/dist/agent-src/skills/jira-integration/SKILL.md

@@ -54,7 +54,7 @@ fix/DEV-5678/null-pointer         →  DEV-5678
 hotfix/DEV-999/critical-fix       →  DEV-999
 ```
 
-Pattern: `[A-Z]+-[0-9]+` anywhere in the branch name.
+Read it with `agent-config git:convention ticket` — [`commit-subject`](../git-workflow/references/commit-subject.md) § Reading the ticket.
 
 Use `git branch --show-current` to detect, then fetch the ticket:
 
@@ -147,8 +147,8 @@ POST /issue/DEV-1234/transitions
 ## Linking to PRs
 
 When creating PRs, include the Jira ticket in:
-- **Branch name:** `feat/DEV-1234/description`
-- **PR title:** `feat(DEV-1234): description`
+- **Branch name and PR title:** rendered by `agent-config git:convention branch` and
+  built per [`commit-subject`](../git-workflow/references/commit-subject.md)
 - **PR description:** Link to the ticket
 
 ## Related

package/dist/agent-src/skills/js-library-packaging/SKILL.md

@@ -17,7 +17,7 @@ packs:
 > A React or TypeScript consumer receives this skill through `engineering-base`, which both
 > of those packs require.
 
-The JavaScript twin of [`composer-packages`](../composer-packages/SKILL.md). A component is
+The JavaScript twin of `composer-packages`. A component is
 a file; a **library** is a package with a public surface, and that surface is declared in
 `package.json` rather than inferred. Most of the failures below are silent at author time
 and loud at the consumer's — which is why the surface is read, not assumed.
@@ -167,7 +167,7 @@ declared cost — never here.
 
 ## See also
 
-- [`composer-packages`](../composer-packages/SKILL.md) — the PHP twin; same surface discipline, different manifest.
+- `composer-packages` — the PHP twin; same surface discipline, different manifest.
 - [`standards-from-config`](../standards-from-config/SKILL.md) — the Class-A rule the § Release branch follows.
 - [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md) — the `!` marker a release tool reads.
 - [`ui-component-architect`](../ui-component-architect/SKILL.md) — the component inside the library; this skill is the package around it.

package/dist/agent-src/skills/merge-conflicts/SKILL.md

@@ -222,10 +222,16 @@ git add .
 
 | Approach | When to use |
 |---|---|
-| `git merge main` | Default — preserves history, safer for shared branches |
-| `git rebase main` | Only when explicitly asked — rewrites history, cleaner log |
-
-**Never rebase without explicit permission** (per `no-commit` rule).
+| `git merge main` | Default (`git.update_strategy: merge`) — preserves history, safer for shared branches |
+| `git rebase origin/main` | `git.update_strategy: rebase` picks it — rewrites history, linear log |
+
+The setting picks the operation; it never authorises it. A rebase of a branch
+that is already pushed still needs the user's answer this turn, per
+[`git-history-discipline`](../../rules/git-history-discipline.md) § When rewrite is
+allowed — an explicit ask, an unrevoked standing instruction, or a `pull
+--rebase` the user started. Under `rebase` conflicts surface per commit, and the protocol — permission,
+stops, recovery ref, the equivalence report afterwards — is
+[`git-workflow` › branch-update](../git-workflow/references/branch-update.md).
 
 ## Output format
 

package/dist/agent-src/skills/monorepo-workspace/SKILL.md

@@ -104,7 +104,7 @@ for `workspace:`-linked packages.
 
 State plainly that the listing came from manifests rather than the runner — an
 inferred target list can miss runner-inferred targets. This is the posture
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) already takes for the shadcn
+`react-shadcn-ui` already takes for the shadcn
 CLI; the stop condition is `missing-tool-handling` (never install it silently,
 never fake the output).
 

package/dist/agent-src/skills/po-discovery/SKILL.md

@@ -81,7 +81,7 @@ not name an implementation**. Use Given / When / Then or a numbered
 list. Reject ACs that hide assumptions ("works correctly", "is fast
 enough") — replace with measurable thresholds or strike them.
 
-**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): when the raw input includes a screenshot / mockup alongside the story text, check the sources against each other and surface any conflict as a `gap` / open question — never resolve it silently. Watch for: story text contradicting an attached screenshot; the AC contradicting the description; a clearly-needed behavior the input never states (weekend/holiday shift, empty/error state). Batch them into one clarifying question. Taxonomy: [`cross-source-consistency-mechanics`](../../guidelines/agent-infra/cross-source-consistency-mechanics.md).
+**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md)): when the raw input includes a screenshot / mockup alongside the story text, check the sources against each other and surface any conflict as a `gap` / open question — never resolve it silently. Watch for: story text contradicting an attached screenshot; the AC contradicting the description; a clearly-needed behavior the input never states (weekend/holiday shift, empty/error state). Batch them into one clarifying question. Taxonomy: [`cross-source-consistency-mechanics`](../../guidelines/agent-infra/cross-source-consistency-mechanics.md).
 
 ### 5. Surface non-functional gaps
 

package/dist/agent-src/skills/quality-tools/SKILL.md

@@ -27,6 +27,8 @@ Use this skill whenever running or configuring code quality tools:
 
 - **PHP**: PHPStan (static analysis), Rector (automated refactoring), ECS (coding standards)
 - **JS/TS**: Biome (linting + formatting), TypeScript compiler (type checking), Jest/Vitest (tests)
+- **Python**: Ruff (linting + formatting), mypy (type checking), pytest (tests)
+- **Go**: `gofmt`, `go vet`, optionally golangci-lint, `go test`
 
 ## Modes
 
@@ -39,8 +41,16 @@ stack calls for.
 |---|---|---|
 | PHP (`.php` changed) | [`references/php-tools.md`](references/php-tools.md) | Tool detection, PHPStan / ECS / Rector commands and flags, combined pipeline, config files, baseline policy, PHPStan error handling, testing framework, git-aware execution |
 | JS/TS (`.js` / `.ts` / `.tsx` changed) | [`references/js-ts-tools.md`](references/js-ts-tools.md) | Detection, Biome, TypeScript type checking, Jest / Vitest, the JS/TS workflow sequence |
+| Python (`.py` changed, or `pyproject.toml`) | [`references/python-tools.md`](references/python-tools.md) | Detection from `pyproject.toml`, Ruff, mypy, pytest, the workflow sequence, virtualenv and `setup.cfg` gotchas |
+| Go (`.go` changed, or `go.mod`) | [`references/go-tools.md`](references/go-tools.md) | `gofmt`, `go vet`, golangci-lint where present, `go test`, the workflow sequence, vendor and build-tag gotchas |
 
-Both stacks changed → load both mode bodies and run both pipelines.
+More than one stack changed → load each mode body and run each pipeline.
+
+**The resolver decides which row applies, not the file extension alone.**
+`resolve_toolchain` returns the ecosystems it found and the quality commands
+per ecosystem; the rows above name what those commands are. A TypeScript
+repository resolves the ecosystem `js`, never `typescript` — the pack name and
+the ecosystem label are different vocabularies.
 
 ## Execution policy — on demand only, never proactive
 

package/dist/agent-src/skills/quality-tools/references/go-tools.md

@@ -0,0 +1,76 @@
+# quality-tools — Go quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill. Load this file when
+> the mode table in SKILL.md routes here. The cross-mode material — execution
+> policy, environment, output discipline — stays in SKILL.md and is NOT
+> repeated here.
+
+# Go Quality Tools
+
+## Detection
+
+`resolve_toolchain` (`work_engine/stack/runner.ts`) keys the Go ecosystem on
+`go.mod` and resolves exactly one quality command, `go vet ./...`, plus the
+test command `go test ./...`. It does **not** detect `golangci-lint`, so a
+repository that uses one will show a `quality` list shorter than what its CI
+runs. Read the repository's CI workflow before concluding the resolver's list
+is the whole gate.
+
+| Signal | Tool | What it does |
+|---|---|---|
+| `go.mod` present | **`go vet`** | The toolchain's own correctness checks — printf verbs, struct tags, unreachable code, lost cancel |
+| `go.mod` present | **`gofmt`** | Canonical formatting; not resolved as a command because it is not optional in Go |
+| `.golangci.yml` / `.golangci.yaml` | **golangci-lint** | Meta-linter; the resolver does not detect it |
+
+## The toolchain's own commands
+
+```bash
+gofmt -l .                # list files whose formatting differs — empty is the pass
+gofmt -w .                # rewrite them
+go vet ./...              # the resolver's quality command
+go build ./...            # compiles; the cheapest proof the tree is coherent
+go test ./...             # the resolver's test command
+go test -run '<regexp>' ./pkg/...   # the targeted probe
+go test -race ./...       # the race detector — slow, and the only thing that finds a data race
+```
+
+**`gofmt -l .` with empty output is the pass.** It exits 0 whether or not it
+listed files, so a pipeline that checks only the exit code never fails on
+formatting. Check the output, not the status.
+
+## golangci-lint, where a project has it
+
+```bash
+golangci-lint run         # the whole configured set
+golangci-lint run ./pkg/...   # scoped to a package
+```
+
+It wraps `go vet` among others, so a project with `.golangci.yml` does not
+need `go vet` run separately — and running both doubles the report rather than
+widening it.
+
+## Workflow sequence
+
+1. `gofmt -l .` — read the output, not the exit code.
+2. `go build ./...` — a compile error makes every later step meaningless.
+3. `go vet ./...`, or `golangci-lint run` where the project has it.
+4. `go test -run '<the thing you changed>' ./pkg/...` — targeted.
+5. `go test ./...`, once, at the end; `-race` where concurrency changed.
+
+## Gotchas
+
+- **`./...` from the wrong directory.** The pattern is relative to the working
+  directory, not to the module root. Run it from the directory holding
+  `go.mod`, or name the module path.
+- **A vendored tree.** With `vendor/` present the toolchain defaults to
+  `-mod=vendor`; a dependency added to `go.mod` but not vendored fails to build
+  with an error that names the package, not the mode. `go mod vendor` after any
+  dependency change.
+- **Build tags hide packages.** `go vet ./...` and `go test ./...` skip files
+  excluded by build constraints, so a green run says nothing about a
+  `//go:build integration` file. Name the tag (`-tags integration`) to reach it.
+- **No `go` pack exists in this suite yet.** Go artifacts route through
+  `engineering-base` and this reference; `src/packs/go/pack.yaml` <!-- ref-ignore --> is created by
+  `road-to-stacks-beyond-php` step 2.3, which is blocked on the programme's
+  skill-growth question. Until then this file is the whole of the Go quality
+  surface, by design rather than by omission.

package/dist/agent-src/skills/quality-tools/references/python-tools.md

@@ -0,0 +1,104 @@
+# quality-tools — Python quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill. Load this file when
+> the mode table in SKILL.md routes here. The cross-mode material — execution
+> policy, environment, output discipline — stays in SKILL.md and is NOT
+> repeated here.
+
+# Python Quality Tools
+
+## Detection
+
+The resolver is the authority, not this table. `resolve_toolchain`
+(`work_engine/stack/runner.ts`) reads `pyproject.toml` and returns the quality
+commands it found; run those. The table says what each one is, so a reader can
+tell a missing tool from an unknown one.
+
+| Indicator in `pyproject.toml` | Tool | What it does |
+|---|---|---|
+| `[tool.ruff]` | **Ruff** | Linting and formatting in one binary; replaces flake8, isort, pyupgrade and (with `ruff format`) black |
+| `[tool.mypy]` | **mypy** | Static type checking |
+| `[tool.pytest.ini_options]` | **pytest** | Test runner — the resolver binds it as the test command, not as a quality command |
+
+A repository with none of the three resolves an empty `quality` list. That
+means **none was resolved**, never that none is needed — the same distinction
+SKILL.md draws for ruby, jvm and dotnet.
+
+## Ruff — linting and formatting
+
+```bash
+ruff check .              # lint, read-only
+ruff check --fix .        # lint and apply the safe fixes
+ruff format .             # format
+ruff format --check .     # format check, read-only — what CI runs
+```
+
+Config lives in `[tool.ruff]` in `pyproject.toml` (or `ruff.toml`). The two
+settings that change what the other commands mean:
+
+- `line-length` — the formatter's wrap column; `ruff check` reports `E501`
+  against the same number.
+- `[tool.ruff.lint] select` / `ignore` — the rule set. An empty `select` is
+  Ruff's default set, not "no rules".
+
+**`--fix` is not a formatter.** `ruff check --fix` rewrites code to satisfy
+lint rules; `ruff format` rewrites layout. A pipeline that runs only the first
+leaves formatting drift that CI's `ruff format --check` then fails on.
+
+## mypy — type checking
+
+```bash
+mypy .                    # check the package
+mypy --strict .           # every optional strictness flag on
+```
+
+Config lives in `[tool.mypy]`. `strict = true` there is the same as `--strict`
+on the command line, so passing the flag to a project that already sets it
+changes nothing — and passing it to one that does not is a different check
+from the one CI runs. Read the config before adding flags.
+
+An error mypy reports on a file the current change did not touch is
+pre-existing debt. Treat it the way SKILL.md's baseline policy treats a
+PHPStan baseline entry: it is not this change's to clear silently.
+
+## pytest — the test runner
+
+Not a quality tool, listed here because the resolver finds it in the same
+file and a reader looking for "the Python commands" expects it.
+
+```bash
+pytest                    # the resolver's bound command
+pytest -q                 # quiet, what `addopts = "-q"` already sets
+pytest -k '<expr>'        # filter by name — the targeted probe
+pytest path/to/test.py    # filter by file
+```
+
+Run the filtered form when verifying one fix. The whole suite is the final
+gate, never the per-iteration probe.
+
+## Workflow sequence
+
+1. `ruff format --check .` — fails fast and costs nothing.
+2. `ruff check .` — lint.
+3. `mypy .` — types.
+4. `pytest -k '<the thing you changed>'` — targeted.
+5. The full suite, once, at the end.
+
+Each step is cheaper and narrower than the next, so running them out of order
+spends the expensive verdict on a failure the cheap one would have named.
+
+## Gotchas
+
+- **A virtualenv the agent did not activate.** `ruff` and `mypy` installed in
+  a project venv are not on `PATH` outside it. `python -m ruff` / `python -m
+  mypy` run the installed copy; a bare `ruff` may run a different version or
+  none.
+- **`requirements.txt` only.** The resolver still binds pytest (at MEDIUM
+  confidence) but finds no quality commands, because it reads them from
+  `pyproject.toml`. An empty `quality` list on such a repository is correct
+  output, not a detection bug.
+- **`setup.cfg` and `tox.ini` carry config too.** Older projects keep flake8
+  and mypy settings there. The resolver does not read them; if a project has
+  no `[tool.*]` block and a populated `setup.cfg`, the tools are configured and
+  the resolver's empty list is a gap in the resolver, worth reporting rather
+  than working around.

package/dist/agent-src/skills/refine-ticket/SKILL.md

@@ -86,8 +86,8 @@ selected language.
 Reuses the `jira-ticket` command's loader. Accepts:
 
 1. **Ticket key** — `/refine-ticket PROJ-123`
-2. **Branch detection** — `/refine-ticket` with no arg; regex
-   `[A-Z]+-[0-9]+` against `git branch --show-current`
+2. **Branch detection** — `/refine-ticket` with no arg; `agent-config git:convention ticket`
+   on the current branch ([`commit-subject`](../git-workflow/references/commit-subject.md) § Reading the ticket)
 3. **Pasted text** — `/refine-ticket` followed by a markdown block
 4. **URL** — `/refine-ticket https://acme.atlassian.net/browse/PROJ-123`
 
@@ -144,7 +144,7 @@ Check the loaded ticket for clarity signals before orchestrating:
 - Is the scope one feature, or multiple tangled together?
 - Any sentence that references an existing module name, feature flag, or domain concept?
 
-**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): the ticket is rarely a single source. Compare every source against the others and surface any conflict as an *Open question* — never resolve it silently:
+**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md)): the ticket is rarely a single source. Compare every source against the others and surface any conflict as an *Open question* — never resolve it silently:
 - **text ↔ attachment** — does the ticket text agree with every attached mockup / screenshot / diagram? (Canonical miss: text says "birthdays **today**", the mockup shows a birthday from two days ago.) If an attachment cannot be read, say so — do not assume it agrees.
 - **silent-but-needed** — is the spec silent on a clearly-needed behavior (weekend/holiday shift, empty state, error path, timezone, permissions)? Surface it and ask before it becomes an implementation assumption — an inferred behavior is a scope expansion, not a given.
 - **intra-ticket** — do the AC, description, and comments contradict each other?
@@ -347,7 +347,7 @@ DoR check — not automatically on every refinement.
 - The model tends to invent risks that sound plausible but aren't anchored in the ticket text. Every risk in Top-5 must cite a phrase, AC bullet, or sub-skill finding — no hypotheticals.
 - Persona voices degrade into generic platitudes when the ticket is already tight. If a persona has nothing real to flag, write one sentence stating that — do not pad.
 - Sub-skills (`validate-feature-fit`, `threat-modeling`) cost tokens; orchestrate only when the trigger matrix actually matches, not defensively on every run.
-- Branch-detection matches the first `[A-Z]+-[0-9]+` in the branch name; chained keys (e.g. `feat/PROJ-1-and-PROJ-2`) pick the first and note the rest.
+- Branch-detection takes the first `ticket` that `git:convention ticket` prints; chained keys (e.g. `feat/PROJ-1-and-PROJ-2`) pick the first and note the rest.
 
 ## Do NOT
 

package/dist/agent-src/skills/review-routing/SKILL.md

@@ -31,7 +31,7 @@ Do NOT use when:
 - The diff is low-risk and no ownership map exists — fall back to the
   common role vocabulary below.
 - A full PR description is requested — route to
-  [`/pr:create:description-only`](../../domains/git/pr/create/description-only/command.md) and let
+  `/pr:create:description-only` and let
   it call this skill for the routing block.
 - A threat model is wanted — route to
   [`threat-modeling`](../threat-modeling/SKILL.md).
@@ -210,6 +210,6 @@ Data source: <"ownership-map.yml + historical-bug-patterns.yml"
 
 - [`reviewer-awareness`](../../rules/reviewer-awareness.md) — the rule that routes here: anchor reviewer choice in paths and risk, never seniority
 - [`review-routing-data-format`](../../guidelines/agent-infra/review-routing-data-format.md)
-- [`/pr:create:description-only`](../../domains/git/pr/create/description-only/command.md)
+- `/pr:create:description-only`
 - [`judge-test-coverage`](../judge-test-coverage/SKILL.md) — consumes
   the `required_test` entries from matched patterns.

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -100,8 +100,8 @@ roadmaps.
 When the roadmap originates from a ticket/spec that carries a second
 source — an attached mockup/screenshot, a code reality, or an internal
 contradiction — run the **cross-source discrepancy scan** (per
-[`cross-source-consistency`](../../rules/cross-source-consistency.md),
-gated by `consistency.cross_source`) before writing phases. A phase plan
+[`cross-source-consistency`](../../rules/cross-source-consistency.md))
+before writing phases. A phase plan
 built over a text↔image contradiction or a silent-but-needed behavior
 (weekend/holiday shift, empty/error state) bakes the wrong assumption into
 every downstream step. Surface each discrepancy as one batched open

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -213,7 +213,7 @@ is the wrong question asked well.
 **The escalation threshold applies here too.** A third recurrence of the same
 violation class converts an observation into a deterministic gate — and a review
 finding never silently becomes a hard gate. Both halves, specified in
-[`decision-review` § Removal is a disposition](../decision-review/SKILL.md).
+`decision-review` § Removal is a disposition.
 
 ## Output format
 
@@ -242,6 +242,8 @@ finding never silently becomes a hard gate. Both halves, specified in
 - **Reflexion** — [arxiv.org/abs/2303.11366](https://arxiv.org/abs/2303.11366)
   Language agents that reinforce from verbal self-reflection on past
   trials. This pipeline adapts Reflexion by gating promotion with a
-  human review step — learnings only harden into rules/skills after
-  explicit approval, never auto-commit.
+  review step — learnings only harden into rules/skills after explicit
+  approval, never auto-commit: for a proposal scoped to the package, on
+  the AI council's ratification record (user as last rung, ADR-281); for
+  a change a user asked for, on that user's approval.
 

package/dist/agent-src/skills/source-discovery/SKILL.md

@@ -117,7 +117,7 @@ card may exist in the per-user file-first store
   `evidence_report.ts add --bucket assumed --origin global …` and **re-confirm it
   against the live source this session** before use (version skew / schema drift
   across projects). Never "Verified" on the global card alone.
-- A `public`/`vendor` card seen in ≥ `auto_promote_threshold` distinct repos
+- A `public`/`vendor` card seen in ≥ 2 distinct repos
   triggers a one-tap promotion **suggestion** (never silent). `proprietary` cards
   are manual-only and never auto-shared. Record sightings via
   `_lib/knowledge_global_promote.ts record-seen`.

package/dist/agent-src/skills/storybook-workshop/SKILL.md

@@ -16,7 +16,7 @@ agent reads to learn what the component accepts, and the harness that catches a
 focus defect while the component is still in isolation. Stack-agnostic — the tool is
 Storybook, the discipline is not.
 
-Lifted out of [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop, which
+Lifted out of `react-shadcn-ui` § Component workshop, which
 keeps a pointer here rather than a copy.
 
 ## The Iron Law
@@ -135,7 +135,7 @@ Run the project's story test command (the Vitest addon's `storybook test`, or wh
 `package.json` declares — read it, do not assume a name), then read the a11y result.
 
 Write findings into `state.ui_review.a11y` in the shape
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Review pass already defines:
+`react-shadcn-ui` § Review pass already defines:
 
 ```
 {violations: [{rule, selector, severity}, …], severity_floor?, accepted_violations?}
@@ -235,7 +235,7 @@ copied verbatim:
 
 ## See also
 
-- [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — the React stack lane, and the `(rule, selector, severity)` shape § Validate writes into.
+- `react-shadcn-ui` — the React stack lane, and the `(rule, selector, severity)` shape § Validate writes into.
 - [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — the inventory the MCP path accelerates.
 - [`js-library-packaging`](../js-library-packaging/SKILL.md) — the package around the workshop.
 - [`accessibility-auditor`](../accessibility-auditor/SKILL.md) — the WCAG depth behind the a11y half.