yaga-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 0
           persist-credentials: false
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           version: "0.13.0"
@@ -150,7 +150,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           version: "0.13.0"

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/.github/workflows/commit-adoption-qualification.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.12"
       - name: Install pinned Typos for spelling controls

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/.github/workflows/commit-quality.yml

@@ -33,7 +33,7 @@ jobs:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 0
           persist-credentials: false
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           version: "0.12.7"

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/.github/workflows/docs.yml

@@ -30,7 +30,7 @@ jobs:
         with:
           persist-credentials: false
       - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           version: "0.12.7"
       - run: uv sync --frozen --group dev --python 3.12

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
         run: |
           test "$(git rev-parse HEAD)" = "$EVENT_SHA"
           git merge-base --is-ancestor HEAD "refs/remotes/origin/$DEFAULT_BRANCH"
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           version: "0.12.7"
           enable-cache: false
@@ -81,7 +81,7 @@ jobs:
         with:
           name: distributions
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
 
   github-release:
     name: Create GitHub Release

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/AGENTS.md

@@ -13,6 +13,29 @@ Agent review gate is the public review contract. Its current provider adapter re
 
 ## Preserve the CLI contract
 
+- Keep pull-request description checks installed-only under `src/yaga/descriptions/`, with one
+  explicit versioned policy and file/stdin/event/PR source plus an optional explicit Markdown template.
+  Keep the checker pure, Markdown support deliberate, and Typos execution bounded and isolated.
+  Require meaningful content and unique ordered template headings; preserve schema-v1 reports,
+  exact finding counts, 256 stored diagnostics, 64 KiB policy/body/template and 1 MiB event limits.
+  Keep `heading-min-level` defaulted to 2 and `heading-max-length` to 120, with strict integer
+  ranges 1–6 and 1–256. Apply these rules to top-level ATX and Setext headings, reject raw HTML
+  heading tags outside comments/code/escaped literals, and reject conflicting templates.
+  Preserve the `description.heading-*` and `description.html-heading` diagnostic boundaries;
+  structural checks are neither a complete Markdown renderer nor an HTML sanitizer.
+  Keep text hygiene source-located and code/comment/escape-aware. Diagnose invisible format
+  controls, prose tabs, high-confidence literal newline escapes, and unmatched backticks without
+  rejecting ordinary Unicode joining/emoji sequences or guessing arbitrary emphasis. Reject
+  unsupported control characters and bare CR before normalization; preserve LF/CRLF input.
+  Keep file/stdin/event sources offline. Only explicit `--pr` may fetch the current body through
+  the installed authenticated `gh` CLI: require a canonical HTTPS URL or a positive number plus
+  `--repo [HOST/]OWNER/REPO`, reject mixed sources and URL/repository ambiguity, and never infer
+  checkout or environment selection. Use shell-free bounded process execution, verify returned
+  PR identity and strict JSON, preserve the 64 KiB decoded-body limit, and never expose raw process
+  output or credentials. Keep the 30-second, 512 KiB stdout, and 64 KiB stderr bounds. Fetches may
+  check open/closed/merged PRs, without retrieving historical descriptions or writing to GitHub.
+  Never discover templates or policy, access Git history, or inherit commit-author exemptions.
+  Keep this provider outside repository plans and both Action import graphs.
 - `commit check` accepts one explicit source or defaults to `HEAD`; never silently combine sources,
   fetch history, reduce a Git selection, or ignore a missing base.
 - Treat commit messages, Git output, revisions, paths, and displayed labels as untrusted. Bound

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/CONTRIBUTING.md

@@ -42,10 +42,36 @@ with project and Python environment leakage removed.
 That strict build gate runs on Python 3.12. The Python 3.15 test jobs permit PyYAML's source-build
 fallback because the locked PyYAML release does not publish Python 3.15 wheels.
 
+The default `make ci` changed-path check covers only `HEAD^..HEAD`. To qualify a complete pull
+request, use exact base/head SHAs that are already available in complete local history, and run
+from the head checkout:
+
+```bash
+uv run yaga commit check --range '<base-sha>..<head-sha>'
+uv run make ci CHANGE_RANGE='<base-sha>...<head-sha>'
+```
+
+The independent two-dot commit check selects branch-only commits; the three-dot changed-path
+check compares the head against its unique merge base. Neither command fetches or infers a remote
+branch. The range override does not change workflow, formatting, or test inputs: those still use
+the current checkout. A final docs-only commit must not hide an earlier source change from the
+complete PR check.
+
+Minimum runtime compatibility has a separate optional check:
+
+```bash
+uv run --locked --python 3.12 python scripts/check_minimum_runtime.py --report minimum-runtime.json
+```
+
+It builds a fresh base wheel, resolves the lowest runtime dependency versions outside the checkout,
+checks installed provenance and dependency consistency, and exercises representative CLI/report
+paths. See [minimum runtime qualification](docs/minimum-runtime.md) for scope and retained evidence;
+this complements the frozen-lock `make ci` and strict package build gates.
+
 ## CLI and commit policy contract
 
 The public installed command groups are `branch`, `change`, `commit`, `config`, `github`, `mode`,
-`path`, `repo`, `self`, `size`, `test`, `tree`, `workflow`, and `gate`.
+`path`, `pull-request`, `repo`, `self`, `size`, `test`, `tree`, `workflow`, and `gate`.
 Keep Typer declarations in `src/yaga/commands/`; keep commit parsing, policy, Git selection,
 configuration, GitHub event adaptation, and reporting in focused dependency-light modules under
 `src/yaga/commits/`. Domain behavior must remain directly testable without invoking Typer.
@@ -180,6 +206,36 @@ diagnostics.
 must refuse to shadow any effective discovered configuration, never edit `pyproject.toml`, and keep
 its deterministic starter template round-trippable through the strict loader.
 
+Pull-request description policy lives under `src/yaga/descriptions/` and remains installed-only.
+Require one explicit versioned policy and description source, plus an optional explicit template.
+Keep the Markdown subset and checker pure; file/stdin/event loading, explicit current-PR fetching,
+and bounded isolated Typos execution belong in adapters. File/stdin/event sources remain offline.
+Only `--pr` invokes the installed authenticated `gh` CLI to read the current description. Require
+a canonical HTTPS PR URL or a positive number plus `--repo [HOST/]OWNER/REPO`; reject mixed sources,
+URL/repository ambiguity, and implicit checkout/environment selection. Use the shared shell-free
+bounded process runtime with a 30-second timeout, 512 KiB stdout, and 64 KiB stderr; strictly parse
+JSON and verify returned PR identity before checking its bounded body. Do not expose raw process
+output or credentials. Support open, closed, and merged PRs without historical-description reads.
+No Git history access, policy/template discovery, author exemptions, or writes belong in this
+provider. Schema v1 controls prose word minimum, total character maximum,
+heading level/length, whole-line placeholders, task completion, and optional spelling. Default
+`heading-min-level` to 2 (strict integer 1 through 6) and `heading-max-length` to 120 (strict integer
+1 through 256). Apply level/length/content checks to top-level ATX and Setext headings; Setext
+paragraphs do not contribute prose words. Reject raw HTML `h1` through `h6` tags outside comments,
+code, and escaped literal markup; this narrow rule does not sanitize or forbid other HTML.
+Template headings must occur once in order with meaningful section content; hidden comments and
+fenced code cannot satisfy it. Reject template/policy conflicts as configuration errors.
+Keep fixed text hygiene checks code/comment/escape-aware: suspicious invisible Unicode characters,
+prose tabs, high-confidence literal newline escapes, and unmatched backtick delimiters. Preserve
+ordinary Unicode joining/emoji behavior and source byte-column locations. Reject unsupported
+control characters and bare CR before normalization; accept LF and CRLF. Do not infer lost text,
+rewrite descriptions, or claim complete Markdown rendering or HTML sanitization.
+Preserve 64 KiB policy/body/template bounds, the 1 MiB event bound, 64 template headings, exact
+finding counts with 256 stored diagnostics, schema-v1 reports, and exits 0/1/2. The GitHub body
+adapter validates supported open-PR events without claiming authenticated identity or requiring
+commit metadata. Keep both commands outside repository plans and both Action import graphs.
+See [pull-request descriptions](docs/pull-request-descriptions.md) for the complete public contract.
+
 Branch-name policy lives under `src/yaga/branches/` and remains installed-only. `branch check`
 requires one explicit versioned policy and one explicit short name; never inspect Git, infer the
 current branch, discover policy, parse an event, normalize `refs/` or remote prefixes, or read an
@@ -399,7 +455,11 @@ gate. Its PR-head configuration is contributor-controlled and is only a quality
 ## Action contract
 
 The public inputs are exactly `gate`, `operation`, `github-token`, `prerequisite-workflow`,
-`lifecycle-workflow`, `owner-id`, `approval-marker`, `request-timeout`, and `job-timeout-minutes`.
+`lifecycle-workflow`, `owner-id`, `approval-marker`, `request-timeout`, `job-timeout-minutes`, and
+`agent-review-policy-file`. The last input defaults to empty; nonempty values are deliberately
+rejected before API access because this fixed GitHub adapter cannot execute named lenses or bind
+their outcomes to a policy digest. Provider-neutral `gate agent-review policy` commands remain
+available to external adapters.
 `operation` is closed to `invalidate`, `prepare`, `authorize`, `observe`, `request`, and `finalize`.
 Only `prepare` emits the closed `route` capability and `pull_request_number` used by the template;
 its routes are `skip`, `done`, `observe`, `owner`, `external`, and `approved`. Candidate identity

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/Makefile

@@ -2,6 +2,7 @@
 
 DOCS_ADDR ?= localhost:9000
 BUILD_ARGS ?=
+CHANGE_RANGE ?= HEAD^..HEAD
 
 actionlint:
 	uv run yaga workflow lint .github/workflows examples
@@ -23,7 +24,7 @@ check:
 	uv run ty check
 	uv run pre-commit validate-manifest .pre-commit-hooks.yaml
 	uv run yaga repo check --plan .yaga/checks/ci.toml --commit HEAD --revision HEAD
-	uv run yaga change check --policy .yaga/change-policy.toml --range HEAD^..HEAD
+	uv run yaga change check --policy .yaga/change-policy.toml --range "$(CHANGE_RANGE)"
 	bash -n scripts/composite_smoke_python
 
 test:

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yaga-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Configurable developer workflow checks for local use and GitHub Actions
 Project-URL: Documentation, https://dariuszpanas.github.io/yaga/
 Project-URL: Changelog, https://dariuszpanas.github.io/yaga/changelog.html
@@ -24,6 +24,7 @@ Requires-Python: >=3.12
 Requires-Dist: pyyaml<7,>=6.0.3
 Requires-Dist: typer<1,>=0.27.2
 Provides-Extra: quality
+Requires-Dist: certifi>=2026.10.19; extra == 'quality'
 Requires-Dist: torch<3,>=2.13; extra == 'quality'
 Requires-Dist: transformers<6,>=5.10; extra == 'quality'
 Provides-Extra: quality-bedrock
@@ -45,6 +46,7 @@ become another review conversation. Start with one check and adopt more as your
 | Problem | What YAGA checks |
 | --- | --- |
 | Commit messages and branch names follow inconsistent conventions | [Commit policy](https://dariuszpanas.github.io/yaga/commit-policy.html) and [branch naming](https://dariuszpanas.github.io/yaga/branch-policy.html) defined by your team |
+| Pull requests omit useful context or leave template sections unfinished | [Description checks](https://dariuszpanas.github.io/yaga/pull-request-descriptions.html) for required content, templates, and optional spelling |
 | A change lands without the related files your project expects | [Changed-path rules](https://dariuszpanas.github.io/yaga/change-policy.html), such as source changes accompanied by tests |
 | Unwanted files, oversized blobs, or incompatible paths enter the repository | [Committed-file checks](https://dariuszpanas.github.io/yaga/repository-checks.html) for contents, sizes, names, and entry modes |
 | GitHub Actions workflows drift from your security and maintenance rules | [Workflow checks](https://dariuszpanas.github.io/yaga/workflow-checks.html) for immutable references, permission and checkout rules, and syntax |

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/README.md

@@ -13,6 +13,7 @@ become another review conversation. Start with one check and adopt more as your
 | Problem | What YAGA checks |
 | --- | --- |
 | Commit messages and branch names follow inconsistent conventions | [Commit policy](https://dariuszpanas.github.io/yaga/commit-policy.html) and [branch naming](https://dariuszpanas.github.io/yaga/branch-policy.html) defined by your team |
+| Pull requests omit useful context or leave template sections unfinished | [Description checks](https://dariuszpanas.github.io/yaga/pull-request-descriptions.html) for required content, templates, and optional spelling |
 | A change lands without the related files your project expects | [Changed-path rules](https://dariuszpanas.github.io/yaga/change-policy.html), such as source changes accompanied by tests |
 | Unwanted files, oversized blobs, or incompatible paths enter the repository | [Committed-file checks](https://dariuszpanas.github.io/yaga/repository-checks.html) for contents, sizes, names, and entry modes |
 | GitHub Actions workflows drift from your security and maintenance rules | [Workflow checks](https://dariuszpanas.github.io/yaga/workflow-checks.html) for immutable references, permission and checkout rules, and syntax |

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/docs/changelog.md

@@ -2,6 +2,65 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-29
+
+### Added
+
+- Add installed `pull-request description check` and `github pull-request description check`
+  commands for explicit Markdown files, stdin, and GitHub event bodies. Version-one policies
+  check meaningful content, word and character limits, unfinished placeholders, optional task
+  completion, and isolated Typos spelling. Explicit templates require ordered, filled sections
+  and replacement of unchanged prompts. Reports support text, JSON, and GitHub annotations;
+  existing commit checks and composite Actions retain their separate contracts.
+
+- Check description heading structure even without a template. Default to H2 or deeper and at
+  most 120 heading-text characters; reject empty headings and raw HTML heading tags. Recognize
+  top-level Setext headings so a whole paragraph formatted as an H1 or H2 cannot count as prose.
+  Reject templates whose headings conflict with the selected policy.
+
+- Detect suspicious invisible characters, prose tabs, literal escaped line breaks, and unmatched
+  backticks outside code and comments. Reject bare carriage returns and identify unsupported
+  control characters without rendering them. Document literal UTF-8 file authoring to preserve
+  Markdown through shell commands.
+
+- Add `pull-request description check --pr` for the current body of an existing GitHub pull
+  request. Accept an explicit URL or a number with `--repo`, fetch through the installed
+  authenticated `gh` CLI with bounded process execution, and run the same policy/template checks
+  without a checkout or Actions. File, stdin, and event checks remain offline.
+
+- Add a separate minimum-runtime qualification helper that builds a fresh base wheel, installs
+  the lowest resolved runtime dependencies outside the checkout, checks installed imports, and
+  runs the shared CLI smoke checks. Its JSON receipt records actual versions and the wheel hash;
+  the frozen-lock matrix and strict package build gate remain required.
+
+- Make source types, prerequisites, network behavior, reports, repository-plan membership, and
+  Action availability discoverable from installed help and the command guide, with tested local
+  and complete-PR recipes.
+
+- Document the staged-check design assessment, including index semantics, report compatibility,
+  and implementation acceptance criteria. Staged execution is not included in this release.
+
+### Fixed
+
+- Reject Git object-path selectors in changed-path range endpoints before repository access, so
+  a crafted gitlink cannot redirect the selected comparison and hide policy findings.
+
+- Isolate installed-wheel smoke Git setup from ambient repository variables, user/system
+  configuration, and templates, preserving unrelated repositories during qualification.
+
+- Allow an explicit `CHANGE_RANGE` override for local `make ci` qualification. Document the
+  independent full commit range check and the default last-commit-only comparison.
+
+- Require `certifi>=2026.10.19` in the published `quality` extra, including wheel metadata, to
+  prevent supported model-download stacks retaining older affected certificate bundles. This
+  applies when installing/upgrading with the extra; base and Bedrock requirements are unchanged.
+
+- Reject inconsistent Typos success/finding responses instead of silently accepting unexpected
+  output as a clean spelling result.
+
+- Correct the documented repository-plan key, stdout/stderr capture, lifecycle exit codes,
+  quality-provider help, and the fixed GitHub Action's rejecting policy-file input.
+
 ## [0.3.0] - 2026-10-18
 
 ### Added

yaga_cli-0.4.0/docs/commands.md

@@ -0,0 +1,135 @@
+# Command index
+
+Start with the source you intend to check, then read the linked reference for its policy,
+diagnostics, and limits. Run `yaga <group> --help` for the installed version's exact options.
+Checks never imply an all-checks mode or automatically run another provider.
+
+## Choose a source and prerequisites
+
+"Offline" below describes checking after installation. Optional spelling requires an installed
+Typos executable; Git-backed commands require local objects and never fetch. No command in the
+first table needs GitHub credentials except an explicit description `--pr` fetch.
+
+| Command and reference | Source and required selection | External tools and execution |
+| --- | --- | --- |
+| [`yaga commit check`](commit-policy.md) | One literal title/message, editor file, file, stdin, commit, or range; defaults to `HEAD`. One discovered or explicit commit config. | Offline. Git for history and `--edit`; Typos if spelling is enabled. |
+| [`yaga branch check`](branch-policy.md) | Literal short name via `--name` and explicit `--policy`. | Offline; no Git. |
+| [`yaga pull-request description check`](pull-request-descriptions.md) | File, stdin, or current PR; explicit `--policy`, optional `--template`. | File/stdin are offline. Only `--pr` uses authenticated `gh` and network to read current metadata; no checkout. Typos if enabled. |
+| [`yaga change check`](change-policy.md) | Committed changed paths from explicit `--range A..B` or `A...B` and `--policy`. | Offline Git; complete history and a unique three-dot merge base. |
+| [`yaga tree check`](tree-policy.md) | Committed path names; explicit `--revision` and `--policy`. | Offline Git; selected commit/tree must exist. |
+| [`yaga path check`](path-policy.md) | Committed path portability; explicit `--revision` and `--policy`. | Offline Git; selected commit/tree must exist. |
+| [`yaga mode check`](mode-policy.md) | Committed entry modes; explicit `--revision` and `--policy`. | Offline Git; selected commit/tree must exist. |
+| [`yaga size check`](size-policy.md) | Committed blob sizes; explicit `--revision` and `--policy`. | Offline Git; selected commit/tree/blobs must exist. |
+| [`yaga workflow check`](workflow-checks.md) | Current workflow files: explicit paths or documented `.github/workflows` defaults. | Offline; installed YAML parser, no external tool. |
+| [`yaga workflow security`](workflow-checks.md) | Same current files; frozen `recommended-v1` default, optional explicit profile/rules. | Offline; installed YAML parser, no external tool. |
+| [`yaga workflow lint`](workflow-checks.md) | Current workflows plus bounded transitive local workflow/Action support files. | Docker CLI and Linux daemon; may pull the pinned image. Container networking is disabled. The active context can be remote and receives the snapshot. |
+| [`yaga github pull-request check`](github-actions.md) | Event snapshot, matching runner identity/checkout, complete commit history, and commit config. | Offline Git; no API/token. Typos if enabled; trusted `gpgv` for the opt-in signed Dependabot exemption, otherwise normal checks run. |
+| [`yaga github pull-request description check`](pull-request-descriptions.md#github-actions) | Explicit `--event-file`, `--policy`, optional `--template`. | Offline; no Git/checkout. Typos if enabled. |
+| [`yaga repo check`](repository-plans.md) | Explicit provider list or `--plan`; selected providers' runtime inputs. | Inherits each selected provider's tools and execution boundary. |
+
+`tree`, `path`, `mode`, and `size` do not see staged, untracked, or working-file changes. A
+`repo check --revision SHA` sets only their committed source; it does not make workflow checks
+read that revision. Policies and workflow files remain current runtime inputs.
+
+## Planning and optional review
+
+| Command and reference | Source and required selection | External tools and execution |
+| --- | --- | --- |
+| [`yaga test policy check`](test-planning.md) | Explicit policy via `--file`. | Offline; no Git or test execution. |
+| [`yaga test plan`](test-planning.md) | Explicit policy/profile and exactly one range or revision; revision requires a full profile. | Offline Git; no test execution. Range needs complete history; revision needs its commit/tree. |
+| [`yaga test evaluate`](test-planning.md#evaluate-normalized-results) | Explicit plan/results and independent policy, binding, commit/tree, run, and attempt identities. | Offline; no Git, provider API, or test execution. |
+| [`yaga commit quality`](commit-quality.md) | One message, file, stdin, commit, or range; default `HEAD`; quality config and optional provider overrides. | Optional provider extra. Hugging Face runs locally but may download models; cached `--offline` prevents downloads. Bedrock sends selected text remotely and needs AWS credentials/region/access. Git for history. |
+| [`yaga gate agent-review policy check`](agent-review-gate.md) | Explicit named-lens policy via `--file`. | Offline; no agent execution or credentials. |
+| [`yaga gate agent-review policy plan`](agent-review-gate.md) | Explicit named-lens policy via `--file`. | Offline; describes work for an external adapter, does not run it. |
+| [`yaga gate agent-review policy template`](agent-review-gate.md) | Explicit named-lens policy via `--file`. | Offline; emits a pending receipt scaffold. |
+| [`yaga gate agent-review policy evaluate`](agent-review-gate.md) | Explicit policy and adapter results via `--file` and `--results`. | Offline; validates receipts, does not authenticate external provenance. |
+| [`yaga gate agent-review <operation>`](github-review-adapter.md) | Trusted GitHub environment/event, lifecycle evidence, permissions and applicable approval marker. | Network and environment-only GitHub token. May write comments/statuses; trusted default-branch workflows only. |
+
+## Reports and execution surfaces
+
+For ordinary checks, `0` means passed, `1` means findings, and `2` means the check could not
+complete. Receipt evaluation uses `1` for failed or incomplete obligations. Reports use stdout;
+structured operational errors use stderr. CLI usage errors may be plain text even with
+`--format json`; see [exit-aware capture](troubleshooting.md#read-the-exit-code-first).
+
+| Commands | Formats; exits | Repository plan | Bundled Action |
+| --- | --- | --- | --- |
+| `commit check`; `workflow check`, `security`, `lint`; `tree`, `path`, `mode`, `size` checks | Text, JSON, GitHub; `0/1/2` | Exactly these eight providers; tree/path/mode/size require plan v2. | None directly; commit policy is reused by the event-aware commit Action. |
+| `repo check` | Text, JSON, GitHub; `0/1/2` with operational errors taking precedence | Runs a selected plan. | None. |
+| `branch check`, `change check`, both description checks, `commit quality` | Text, JSON, GitHub; `0/1/2` | No. | None. |
+| `github pull-request check` | Text, JSON, GitHub; `0/1/2` | No. | Read-only `actions/commit-check`. |
+| `test policy check`, `test plan` | Text, JSON; `0/2` | No. | None. |
+| `test evaluate` | Text, JSON; `0/1/2` | No. | None. |
+| `gate agent-review policy check`, `plan` | Text, JSON; `0/2` | No. | None. |
+| `gate agent-review policy template` | JSON scaffold; `0/2` | No. | None. |
+| `gate agent-review policy evaluate` | Text, JSON, GitHub; `0/1/2` | No. | None. |
+| `gate agent-review <operation>` | Lifecycle output; `GateError` returns `1`, not the policy-check error code | No. | Trusted write-capable root Action. Nonempty `agent-review-policy-file` is rejected. |
+
+All installed commands can run in suitable ordinary CI with their stated prerequisites. The two
+bundled Actions are narrow adapters, not wrappers for every checker. Quality advice remains
+advisory; a plan is not evidence that tests or reviews ran. See [Usage modes](usage.md) and
+[Assess and adopt in CI](ci-adoption.md) before choosing required gates.
+
+## Copyable starting points
+
+These Bash recipes assume the named policies/input files exist. Choose policies from the linked
+references; YAGA does not discover standalone policies or fetch missing history.
+
+### Before creating a commit
+
+```bash
+yaga commit check --file message.txt --config .yaga.toml
+yaga branch check --policy .yaga/branch-policy.toml --name feat/parser
+yaga workflow check .github/workflows
+yaga workflow security .github/workflows --profile recommended-v3
+yaga pull-request description check --policy .yaga/description-policy.toml --file pr-description.md
+```
+
+These select the prospective message, supplied branch name, current workflow files, and local
+description. Committed-tree checks still need a commit containing the intended changes.
+
+### A complete committed pull request
+
+Set `YAGA_BASE_SHA` and `YAGA_HEAD_SHA` to the exact base/head commits already available locally.
+Use two dots for branch-only commit messages and three dots for changed paths against the merge
+base. This repository plan must select `commit` and at least one committed-tree provider:
+
+```bash
+: "${YAGA_BASE_SHA:?Set the exact PR base SHA}"
+: "${YAGA_HEAD_SHA:?Set the exact PR head SHA}"
+yaga repo check --plan .yaga/checks/ci.toml \
+  --range "$YAGA_BASE_SHA..$YAGA_HEAD_SHA" --revision "$YAGA_HEAD_SHA"
+yaga change check --policy .yaga/change-policy.toml \
+  --range "$YAGA_BASE_SHA...$YAGA_HEAD_SHA"
+```
+
+Check out the intended head separately for working-file workflow checks. A last-commit-only range
+can miss earlier source changes followed by a docs-only commit. YAGA contributors can use the
+explicit local qualification override in [Contributing](contributing.md#development-loop).
+For a plan without committed-tree providers, omit `--revision`.
+
+### Descriptions when Actions are unavailable
+
+The local command above works offline. To read a current published description, authenticate
+`gh` for the intended host and supply the full canonical PR URL; no checkout is required:
+
+```bash
+: "${YAGA_PR_URL:?Set the canonical HTTPS pull-request URL}"
+yaga pull-request description check --policy .yaga/description-policy.toml --pr "$YAGA_PR_URL"
+```
+
+Use `--pr 123 --repo OWNER/REPO` instead when choosing a numeric PR explicitly. This reads the
+current body; it does not check event-bound commit history or edit the pull request.
+
+## Authoring and installation helpers
+
+[`yaga config show`](configuration.md) reads one discovered or explicit config;
+[`yaga config init`](configuration.md) creates a new standalone config with no-overwrite semantics
+and supports `--dry-run`. Both are offline, use text/JSON, and return `0/2`.
+[`yaga commit template`](commit-policy.md#read-only-message-templates) prints an incomplete message
+from explicit conventional components or plain policy; it is offline, text-only, and returns
+`0/2`. None belongs to repository plans or the bundled Actions.
+
+For installation maintenance, use [`yaga self update`](getting-started.md#update-or-uninstall)
+or `yaga self update --dry-run` to verify a uv tool installation without updating it. Actual
+updates invoke uv and may access the package index; this is maintenance, not a policy check.

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/docs/commit-quality.md

@@ -10,6 +10,15 @@ through 3.14 for this extra. The repository's Linux CPU index has Python 3.15 wh
 index selection is not part of the published wheel metadata. The core CLI and the separate
 `quality-bedrock` extra do not require PyTorch.
 
+The published `quality` extra also requires `certifi>=2026.10.19` for certificate bundles used
+by supported online model-download dependencies. The [certifi advisory](https://github.com/certifi/python-certifi/security/advisories/GHSA-6q48-6c7w-9gw2)
+identifies 2026.10.18 as removing the affected roots; [PyPA recommends 2026.10.19 or later](https://github.com/pypa/advisory-database/blob/main/vulns/certifi/PYSEC-2026-4320.yaml),
+which restores unaffected roots. Upgrade with `pip install --upgrade 'yaga-cli[quality]'` (or
+the equivalent command for your environment) to apply this extra-scoped floor. Wheel metadata
+cannot repair untouched environments, installations using `--no-deps`, or incompatible external
+constraints. This direct requirement also installs certifi if a future model-download dependency
+graph no longer needs it; base CLI and `quality-bedrock` requirements are unchanged.
+
 ## When to use it
 
 Run both checks when exact policy enforcement and broader writing feedback are useful:

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/docs/configuration.md

@@ -273,11 +273,23 @@ a tree or workflow policy:
 | `.yaga/path-policy.toml` | `path-policy-version = 1` | exact `--revision` |
 | `.yaga/mode-policy.toml` | `mode-policy-version = 1` | exact `--revision` |
 | `.yaga/size-policy.toml` | `size-policy-version = 1` | exact `--revision` |
-| `.yaga/checks/*.toml` | `repository-plan-version` | explicit `--plan` |
+| `.yaga/checks/*.toml` | `plan-version = 1` or `plan-version = 2` | explicit `--plan` |
 
 These files are quality policy only. A pull-request-controlled plan or policy is never trusted
 security authority for a privileged workflow.
 
+A minimal workflow-only repository plan uses the same explicit version key as larger plans:
+
+```toml
+# workflow-checks.toml
+plan-version = 2
+checks = ["workflow"]
+```
+
+Run it with `yaga repo check --plan workflow-checks.toml`; workflow files come from the current
+checkout. See [Repository plans](repository-plans.md) for all eight supported providers and
+their runtime inputs.
+
 ## Provider configuration examples
 
 ```toml
@@ -340,8 +352,9 @@ diagnostics, and revision requirements.
 Use the narrowest provider that expresses the requirement. `commit` checks message structure and
 footers; `change` checks relationships between changed paths; `branch` checks one supplied branch
 name; `tree`, `path`, `mode`, and `size` check one committed snapshot; and the workflow providers
-check Actions files. Combine them only through explicit `repo check` selections or a checked-in
-plan. A policy file never causes another provider to run.
+check Actions files. Repository plans combine only the supported commit, workflow, tree, path,
+mode, and size providers; invoke branch and change checks separately. A policy file never causes
+another provider to run.
 
 For a committed-tree provider, always pass the exact revision that CI checked out:
 

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/docs/contributing.md

@@ -22,7 +22,22 @@ uv run make ci
 ```
 
 The full gate covers formatting, lint, type checks, tests, repository policies, workflow linting,
-documentation, and the package build. The documentation-only loop is:
+documentation, and the package build. Its default changed-path range is only `HEAD^..HEAD`.
+For a complete PR, run from the head checkout with exact base/head SHAs already available in
+complete local history:
+
+```bash
+uv run yaga commit check --range '<base-sha>..<head-sha>'
+uv run make ci CHANGE_RANGE='<base-sha>...<head-sha>'
+```
+
+The two-dot command checks all branch-only commit messages; the three-dot override checks paths
+against the unique merge base. No remote branch is inferred and no history is fetched. Workflow,
+formatting, and test checks still read the current checkout. The independent
+[minimum runtime qualification](minimum-runtime.md) checks the base wheel's lowest dependency
+resolution; it does not replace the locked gate.
+
+The documentation-only loop is:
 
 ```bash
 make docs

yaga_cli-0.4.0/docs/designs/staged-checks.md

@@ -0,0 +1,93 @@
+# Staged repository checks: design assessment
+
+## Decision for YAGA 0.4.0
+
+Complete the assessment requested in [#243](https://github.com/dariuszpanas/yaga/issues/243);
+retain the existing committed-only commands in this release. An explicit index source is useful
+for local feedback before a commit, especially for required paths, forbidden generated files,
+executable bits, portability, and oversized blobs. It needs a separate source and reporting
+contract before implementation. This assessment does not introduce a `--staged` option.
+
+The current result is intentional: creating or staging a required file does not change
+`tree check --revision HEAD`; committing it does. Workflows and literal message/description
+checks already offer useful checks before committing. Staged checks would complement them and
+would not establish the final commit identity or replace committed CI checks.
+
+## Proposed scope
+
+Start with an explicit `--staged` source for `tree`, `path`, `mode`, and `size`, mutually exclusive
+with `--revision`. Require exactly one source and an explicit policy, retaining `--repo .` as the
+only repository default. Do not infer HEAD, merge staged and working files, include untracked
+files, discover policy, fetch objects, or write the caller's index. Repository-plan integration,
+change coupling, test planning, and both composite Actions remain separate decisions.
+
+Reuse each provider's pure checker and policy version where its meaning stays identical. The
+adapter should provide the complete proposed index tree, not just changed entries, so required
+paths and total-size policy have their normal meaning. Reuse the shared bounded Git runtime;
+do not create a commit or use `write-tree` to manufacture a committed identity.
+
+## Required semantics
+
+| Index state | Proposed behavior |
+| --- | --- |
+| Addition or deletion | Check the complete index after the staged change; absence is a deletion. |
+| Rename | Treat the indexed destination and removed source as paths; no rename detection. |
+| Partial staging | Inspect indexed blob identities and sizes, never current file contents. |
+| Unstaged or untracked work | Exclude it, including edits made after `git add`. |
+| Unmerged entries | Return an operational error; never choose a conflict stage. |
+| Intent-to-add entry | Return an operational error until actual content is staged; do not silently treat it as an empty blob. |
+| Symlink | Check the indexed mode and stored link-blob size; never follow/read its target. |
+| Executable mode | Check the index mode, independent of host permissions. |
+| Gitlink | Treat it as one leaf, never recurse; size excludes it as today. |
+| LFS pointer | Count the stored pointer bytes, not downloaded LFS content. |
+| Duplicate blob ID | Count bytes per path, as in the committed size provider. |
+| Missing required object | Return an operational error without lazy fetch. |
+| Sparse or split index | Support only after proving complete expansion and snapshot identity; initial implementation may reject these explicitly. |
+| Index changes during collection | Fail the collection or operate on a validated private snapshot; never mix observations. |
+
+An unborn repository can have a valid staged snapshot without a HEAD commit. Empty index behavior
+must be explicit: tree requirements can fail, while empty path/mode/size input can pass according
+to policy. The snapshot covers the entire repository even when `--repo` names a subdirectory.
+
+## Snapshot and trust requirements
+
+Before implementation, a small native-Git spike must prove a bounded way to capture an index
+snapshot and identify unmerged, intent-to-add, sparse, split, and unsupported extension states.
+Plain `ls-files --stage` output alone is insufficient evidence for all of these distinctions.
+Private snapshotting must account for linked worktrees and shared-index dependencies and validate
+regular-file type, identity, size, and any before/after race observations. If a stable snapshot
+cannot be established, fail closed. Document the concurrency guarantee instead of presenting
+two matching reads as an atomic transaction against a malicious writer.
+
+Use shell-free fixed Git commands with the existing trusted executable, isolated environment,
+no prompts, no replacements, no lazy fetch, bounded cleanup, and graft checks. An implementation
+must not run hooks, filters, external diff/textconv, or inspect symlink targets. Size lookup should
+read object metadata by validated object ID, not materialize file contents. Keep the existing
+30-second process, 64 MiB tree-output, 50,000-entry, 4,096-byte path, 64-component path,
+10,000,000 matcher-work-unit, portable-integer, and 256-stored-diagnostic boundaries.
+
+## Reporting compatibility decision
+
+Keep committed-source schema-v1 reports unchanged. Introduce a separately versioned staged
+report envelope before exposing the new source; do not put an index hash in `commit_sha` or
+`tree_sha`, or emit invented/null identities under an unchanged committed schema. The proposed
+envelope needs an explicit `source.kind = index`, a canonical ordered entry-manifest digest,
+and policy/source identity sufficient to distinguish repeated observations. Specify the digest
+grammar and object hash algorithm before use. It identifies observed input, not a trusted origin
+or a commit that will later be created.
+
+Preserve provider diagnostic codes, exact totals, first-pattern attribution, text/JSON/GitHub
+formats, and exits 0/1/2. Text and annotations must say staged/index. Report schema selection
+and future repository aggregation need explicit compatibility tests and documentation.
+
+## Implementation gate
+
+Implementation is appropriate after a concrete local-hook/editor consumer confirms the need and
+the snapshot spike passes on Linux and Windows with supported Git versions. Acceptance must cover
+every row above, linked worktrees, subdirectory selection, hostile Git environment/configuration,
+malformed/bounded output, missing objects, race failures, and clean temporary-file ownership.
+Installed-wheel tests must compare staged versus committed results and verify that neither index
+bytes nor repository history change. Required CI continues checking exact committed sources.
+
+This closes the design assessment for YAGA 0.4.0. Shipping staged execution requires a
+separate implementation decision and the above evidence; it is not part of this release's CLI.

{yaga_cli-0.3.0 → yaga_cli-0.4.0}/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Get started
 
-This guide covers **YAGA 0.3.0 (Beta)**. YAGA requires Python 3.12 or newer. Install the **`yaga-cli`** distribution from PyPI;
+This guide covers **YAGA 0.4.0 (Beta)**. YAGA requires Python 3.12 or newer. Install the **`yaga-cli`** distribution from PyPI;
 the executable and import package are **`yaga`**. The `yaga` distribution is an unrelated project.
 
 The core CLI is tested on Python 3.12 through 3.15. Python 3.15 installations currently use