yaga-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/CONTRIBUTING.md

@@ -95,8 +95,14 @@ complete commit messages: the pull-request title adapter deliberately uses the h
 `body-min-words` is a schema-v1 integer from zero through 100000 with a zero default. It counts only
 Unicode-whitespace-delimited prose-body tokens containing a Unicode alphanumeric character;
 recognized final footers and punctuation-only or emoji-only tokens are excluded. A nonzero value
-does not require an absent optional body, and it is invalid with a forbidden body. Keep its
+does not require an absent optional body, and it is invalid when every reachable body policy
+is forbidden. Per-type forbidden bodies do not receive additional minimum findings. Keep its
 `body.word-count` diagnostic stable across text, JSON, and GitHub reports.
+`body-policy-by-type` is an empty-default schema-v1 mapping with the same bounded, case-insensitive
+type-key validation as scope overrides. It replaces body presence only; all other checks remain
+independent. `body-max-length` is an optional 1-through-100000 total prose limit in the configured
+length unit, excluding recognized final footers. Reject impossible length/word-minimum bounds,
+preserve `body.length`, and keep all body policies out of title-only checks.
 `required-footer-tokens` and `forbidden-footer-tokens` are schema-v1 presence policies for complete
 commits only; pull-request titles remain header-only. Match exact tokens case-insensitively in both
 `Token: value` and `Token #value` forms, allow repeats, and do not infer identity, DCO compliance,
@@ -447,3 +453,35 @@ triggers, fixed environment names, action SHA, and absence of legacy writers.
 Run `uv run make ci` before every push. Use Conventional Commit subjects. Preserve behavior,
 motivation, security boundary, failure mode, migration impact, and validation in the retained commit
 and PR. Fold review fixes and CI repairs into the logical commit they correct.
+
+Keep `pull-request-message` closed to `title-only` (default) and `title-and-body`. The opt-in
+GitHub event check composes literal title, blank line, and bounded UTF-8 body; null/missing bodies
+are empty. Preserve the independent title result, optional schema-v1 `proposed_message` result,
+full policy and spelling checks, body-edit wakes, and pre-exemption event/range validation.
+Do not infer merge settings or claim the proposed text is the final merged commit.
+
+Keep config starter names frozen and the no-option recommended-v1 bytes unchanged. New starters
+must pass the normal loader and preserve atomic no-overwrite publication, race checks, and dry-run
+cleanup. Type explanations must share override resolution with validation, remain bounded and
+sanitized, and never imply that list membership alone proves a message valid.
+
+Keep required-issue-prefixes and footer-values empty by default and full-message-only. References
+are bounded standalone prefix-plus-positive-ASCII-ID tokens, never unrestricted regexes or network
+lookups. Footer values reuse the parser's final suffix and token boundaries, check every occurrence,
+trim outer whitespace, compare values exactly, and emit at most one footer.value finding per token.
+Presence remains separate. Preserve configuration bounds and reject forbidden/breaking token
+constraints; neither reference syntax nor footer labels prove external state or identity.
+
+Keep warning-rules empty by default and closed to the documented configurable diagnostic codes.
+Never demote syntax/resource/merge-selection failures or operational errors. Commit reports always use
+schema v1 with explicit diagnostic severity and warning_count, including clean, empty, and skipped
+results. Diagnostic identity/order is stable, warning-only targets pass, and warning_count counts findings,
+not targets. Preserve severity through spelling, PR checks, and aggregate repository annotations;
+repository/error/config/quality envelopes retain their independent existing schema contracts.
+
+Keep message-format explicit and default conventional. Plain headers use a separate parser with no
+invented type/scope/breaking marker, sharing only content/footer parsing and applicable policy.
+Reject conventional-only config and warnings in plain mode. Message templates must remain stdout-only
+and deliberately incomplete, with explicit conventional components, no invented description or
+footer values, and an explicit supported editor comment character. Validate component input before
+ignored-header policy can bypass it; never modify Git configuration or commit history.

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yaga-cli
-Version: 0.1.2
+Version: 0.2.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

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/changelog.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-20
+
+### Added
+
+- Support explicit plain-message policy and a frozen `plain-v1` starter; print incomplete,
+  policy-guided drafts with `commit template` without changing files or Git.
+
+- Introduce opt-in `warning-rules` for gradual policy adoption, with consistent schema-v1 commit
+  reports containing severity and warning counts, and nonblocking annotations.
+
+- Require bounded work-item references and constrain exact footer values through opt-in
+  `required-issue-prefixes` and `footer-values` settings.
+
+- Add frozen editable workflow starters and `config show --type` explanations of effective
+  body/scope overrides, preserving the existing default starter.
+
+- Validate proposed PR title-plus-description messages with opt-in `pull-request-message`,
+  reusing full commit policy and reporting the proposed message separately.
+
+- Allow per-type body requirements with `body-policy-by-type` and cap total prose with
+  `body-max-length`, preserving existing defaults and independent title checks.
+
 ## [0.1.2] - 2026-09-20
 
 ### Fixed

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/ci-adoption.md

@@ -36,6 +36,12 @@ Inspect the target repository's existing policy before creating one. Run the sel
 known good and known failing inputs. Review findings and agree on policy before requiring the job.
 The [adoption recipes](recipes.md) provide concrete commands and policy examples.
 
+For commit adoption, choose a [workflow starter](commit-policy.md#workflow-starters-and-type-explanations)
+that matches how changes reach the main branch. Plain messages and Conventional Commits are explicit
+choices. Selected policy findings can begin as [warnings](commit-policy.md#gradual-enforcement) while
+input and operational failures remain blocking. If PR descriptions become merge messages, enable
+[proposed-message checks](github-actions.md#proposed-merge-messages) as well.
+
 Keep policy in the target repository. Reuse it in CI rather than duplicating policy arguments in
 workflow files. A [repository plan](repository-plans.md) is useful once several checks need the
 same selection; branch and change checks remain separate commands.

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/commands.md

@@ -10,7 +10,8 @@ or `yaga self update --dry-run` to verify a uv tool installation without updatin
 
 | Command | Input | Reference |
 | --- | --- | --- |
-| `yaga commit check` | One message, file, stdin, commit, or range | [Commit policy](commit-policy.md) |
+| `yaga commit check` | One title, message, editor file, file, stdin, commit, or range | [Commit policy](commit-policy.md) |
+| `yaga commit template` | Selected policy and explicit conventional type/scope, or plain format | [Authoring help](commit-policy.md#read-only-message-templates) |
 | `yaga config init` / `show` | Target repository or explicit configuration | [Configuration](configuration.md) |
 | `yaga branch check` | Explicit short branch name and policy | [Branch policy](branch-policy.md) |
 | `yaga change check` | Explicit Git range and policy | [Changed-path policy](change-policy.md) |

yaga_cli-0.2.0/docs/commit-policy-direction.md

@@ -0,0 +1,83 @@
+# Commit policy direction for 0.2.0
+
+This records the design decisions behind YAGA 0.2.0. See [commit policy](commit-policy.md)
+for supported configuration and [the changelog](changelog.md) for release scope.
+
+## The problem to solve
+
+A useful commit records what changed and enough context to understand why. Teams also use its
+structure for release classification, issue references, and review policy. These are different
+needs: passing a punctuation rule does not prove a message is useful, and a long body can be
+less helpful than a short explanation.
+
+YAGA should make those choices explicit and apply them consistently to the inputs a project
+actually uses: local messages, editor files, historical commits, and pull-request titles.
+Configuration should describe policy without requiring a program to execute it.
+
+## What the surrounding tools teach us
+
+- [commitlint](https://commitlint.js.org/reference/rules.html) offers detailed component rules;
+  its [rule configuration](https://commitlint.js.org/reference/rules-configuration.html) also
+  separates severity from conditions. The useful lesson is control and gradual adoption,
+  not copying every casing convention or inversion into YAGA.
+- [Gitlint](https://jorisroovers.com/gitlint/latest/rules/builtin_rules/) emphasizes readability,
+  configurable limits, and tailored rules, including checks beyond conventional structure.
+  Its [configuration precedence](https://jorisroovers.com/gitlint/latest/configuration/) permits
+  message-level overrides. YAGA should keep policy outside the message being evaluated.
+- [Commitizen](https://commitizen-tools.github.io/commitizen/commands/check/) puts validation
+  alongside authoring and release commands. Helping users prepare a valid message is valuable;
+  quietly exempting broad text prefixes is not the same as verifying a Git merge identity.
+- [Cocogitto](https://docs.cocogitto.io/reference/config.html) connects commit conventions with
+  versioning, changelogs, and monorepos. YAGA should provide dependable checks and reports
+  without requiring users to replace their release tooling.
+- [git-cliff](https://git-cliff.org/docs/configuration/git/) demonstrates the downstream need
+  for classification and reference extraction. Checking stored input and transforming release
+  notes should remain separate operations.
+- [semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) focuses on the
+  title that often becomes a squash commit. The meaningful input depends on merge strategy;
+  validating every intermediate commit is not universally the best default workflow.
+
+These are observations from the tools' primary documentation, reviewed on 2026-09-20. They are
+not a popularity ranking or a promise of compatibility with their configurations.
+
+## YAGA's place
+
+YAGA combines message checks with workflow and committed-tree policy, explicit Git selection,
+bounded processing, and shared local/CI reporting. Its trusted GitHub adapter can verify the
+event and checked-out objects before applying account exemptions. Those properties are worth
+preserving as customization grows.
+
+The 0.2.0 work addresses flexibility and usability: per-type body requirements, nonblocking
+warnings, bounded references and footer values, and policy-guided authoring templates. An explicit
+plain-message format allows readability checks without requiring Conventional Commit structure.
+
+## Defaults and customization
+
+Keep structural validity separate from style. Do not impose universal capitalization, punctuation,
+mandatory prose, dictionaries, or artificial minimum lengths. A project may enable these choices,
+but the documentation must say what each rule measures and what it cannot prove.
+
+Keep existing schema-v1 defaults stable. A future recommended setup should generate explicit,
+editable choices or select a frozen versioned profile. It must not silently change existing
+repositories when YAGA is upgraded. Unknown keys and contradictory requirements should fail
+before checking messages. Project configuration remains independent of global fallback settings.
+
+Add customization in bounded, named forms. Do not put commands, imports, message-controlled
+waivers, or unrestricted regular expressions into policy. Optional authoring assistance should
+preview changes; checking must never rewrite history or alter its input.
+
+## Implemented choices
+
+1. **Content requirements:** require bodies for selected types without skipping other checks;
+   bound total prose independently of line wrapping. Preserve optional-body and title-only behavior.
+2. **Understandable configuration:** explain effective settings and overrides; offer editable
+   starter policies for squash-title and full-message workflows.
+3. **References and trailers:** use bounded project-specific reference and footer-value
+   constraints. Token presence must never be presented as verified identity or completed testing.
+4. **Gradual enforcement:** configure warning/error policy with one schema-v1 report shape and
+   unchanged input-error precedence. Only explicitly selected policy findings become warnings.
+5. **Alternative message formats and authoring:** offer an explicit plain-message mode and
+   configuration-derived message templates. Retain a clear conventional parser boundary.
+
+Full release/changelog automation, arbitrary plugin execution, and automatic commit rewriting are
+not necessary to make commit checking useful. Keep them outside this first 0.2.0 scope.

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/commit-policy.md

@@ -272,3 +272,183 @@ parent, or global configuration discovery. Custom dictionaries are currently uns
 trusted mode: neither a PR's `_typos.toml` nor dirty files in the trusted checkout can weaken it.
 Ordinary local checks and the default PR-head mode retain repository Typos configuration.
 Keep the tool version consistent when comparing local and CI spelling results.
+
+## Proposed PR messages
+
+`pull-request-message = "title-and-body"` opts into full commit policy for the PR title and
+description together. The default is `"title-only"`. This setting affects only event-aware
+PR checks; see [GitHub Actions](github-actions.md#proposed-merge-messages)
+for merge settings, event triggers, reporting, and limitations.
+
+## Workflow starters and type explanations
+
+Start with explicit, editable settings for your workflow:
+
+```bash
+yaga config init --starter title-v1 --dry-run
+yaga config init --starter complete-message-v1
+yaga config show --type fix
+yaga config show --type docs --format json
+```
+
+`config init` without `--starter` retains the original `recommended-v1` starter byte for byte.
+`title-v1` uses lowercase types and a 100-character header limit, allows ending punctuation,
+leaves bodies optional, and ignores Git-proven merge commits. It does not disable checks on
+commits selected by the caller. `complete-message-v1` uses the same choices and additionally
+requires prose for `feat` and `fix`; other types remain optional. Neither starter imposes a
+word count or restricts the set of types. Their names are frozen: future recommendations need
+new names. Generated TOML is yours to edit, and initialization never replaces existing policy.
+`--dry-run` validates and reports the proposed policy without publishing a configuration file.
+
+Both starters retain title-only PR checks. If the PR description is your proposed merge body,
+explicitly enable `pull-request-message = "title-and-body"` as described above. Full-message
+requirements apply to actual commits and enabled proposed messages, never standalone titles.
+
+`config show --type TYPE` adds the effective body and scope requirements and names the override
+or global setting that supplied each. Matching is case-insensitive, just as in the checker.
+The JSON report adds `effective_type` only when requested. `listed_type_allowed` tells you whether
+the configured type list admits the token; it does not evaluate type casing or prove a complete
+message will pass. All independent casing, scope-list, length, footer, and other rules still apply.
+
+The reported `config_path` identifies the single selected file, or built-in defaults. A project
+configuration replaces the global fallback as a whole; fields are not merged between files.
+For trusted Actions, inspect the committed default-branch policy used by that runner: a local
+`config show` does not reproduce a trusted Action's revision selection automatically.
+
+## References and footer values
+
+To require a work-item reference and a controlled validation label in complete messages:
+
+```toml
+[tool.yaga.commit]
+required-issue-prefixes = ["#", "PROJ-"]
+required-footer-tokens = ["Validation"]
+footer-values = {Validation = ["passed", "not-run"]}
+```
+
+Both new settings default to empty and apply only to complete messages, including opted-in
+proposed PR messages. Standalone titles and the independent PR title result remain header-only.
+A full message with neither `#123` nor `PROJ-123` reports `reference.required`.
+
+References are case-sensitive whitespace-delimited tokens, optionally wrapped in the punctuation
+`()` `[]` `{}` `<>` `,` `.` `;` `:` `!` `?` or ASCII quotation marks. A configured prefix must be followed
+by 1–20 ASCII digits, beginning with 1–9. `(#123).` matches; `#0`, `#012`, `prefix#123`, and
+`https://example.com/#123` do not. References may appear in the header, prose, or final footers.
+Markdown links, URLs, and tracker-specific query syntax are not interpreted. Prefixes start with
+an ASCII letter or `#`, followed by ASCII letters, digits, `_`, or `-`; there are at most 128 unique
+prefixes of at most 64 characters. Matching uses a bounded prefix tree over the already bounded
+message rather than user-supplied regular expressions.
+
+`footer-values` constrains every occurrence of each configured final footer token, matching tokens
+case-insensitively and values case-sensitively. It does not require the token to occur: combine it
+with `required-footer-tokens` when presence is mandatory. Values are the complete parsed footer
+value up to the next recognized token, with outer whitespace removed. A multiline value must match
+as a whole, so it cannot satisfy a configured single-line choice by adding an approved first line.
+Each offending token produces one source-located `footer.value` diagnostic. The configured footer
+syntax and paragraph boundary still determine which text is a footer; prose that resembles a
+trailer is not silently reclassified. With hash separators, `Refs #123` has value `123`.
+
+The table allows up to 128 unique case-insensitive tokens and 256 total choices, with at most 128
+choices per token. Each choice is a nonempty safe single-line string of at most 256 characters,
+without outer whitespace; duplicates are rejected. Breaking-change tokens and tokens forbidden
+by `forbidden-footer-tokens` cannot have value constraints.
+
+These options verify stored syntax only. A reference does not prove that an issue exists or is
+resolved. A `Validation: passed` label does not prove that tests ran. An allowed sign-off value
+would not prove identity, DCO compliance, or a cryptographic signature.
+
+## Gradual enforcement
+
+Keep a rule enabled while introducing it as a nonblocking warning:
+
+```toml
+[tool.yaga.commit]
+body-policy = "required"
+body-min-words = 8
+warning-rules = ["body.required", "body.word-count"]
+```
+
+`warning-rules` defaults to empty. Only the listed diagnostic codes become warnings; other findings
+remain errors. A warning does not enable a rule: configure its underlying policy as usual.
+Remove a code from the list when you want its findings to block validation. Messages cannot waive
+or change severity themselves. The same policy applies locally, in the read-only Action, to opted-in
+proposed PR messages, and in the commit provider of `repo check`.
+
+Supported codes are `type.allowed`, `type.case`, `scope.required`, `scope.forbidden`,
+`scope.allowed`, `scope.case`, `header.length`, `description.length`, `description.case`,
+`description.ending`, `breaking.marker-pair`, `body.required`, `body.forbidden`, `body.length`,
+`body.word-count`, `body.line-length`, `body.paragraph-format`, `footer.line-length`,
+`footer.required-colon`, `footer.required`, `footer.forbidden`, `footer.value`, `reference.required`,
+and `typos.word`. The list is closed, case-sensitive, and rejects duplicates. Structural diagnostics
+(`syntax.header`, `syntax.separator`), resource limits, and merge rejection cannot become warnings.
+Missing history, malformed configuration/input, unavailable tools, and other operational errors
+continue to exit 2. A configured warning for spelling never converts a missing or broken Typos tool
+into a successful check.
+
+### Warning-aware report contract
+
+Commit and pull-request JSON reports use schema v1 consistently. Every diagnostic includes an
+`error` or `warning` severity, and every report includes `warning_count`, including zero for clean,
+empty, or skipped selections. Configuring warnings changes enforcement, not the report format.
+Codes, locations, and order remain unchanged. `warning_count` counts diagnostics across all targets,
+including failed targets. A warning-only target has `status: "passed"` and `valid: true`; `passed`,
+`failed`, and `skipped` continue counting targets. Policy errors still produce exit 1, and warning-only
+results exit 0. Consumers should use severity rather than treating every diagnostic as an error.
+Text identifies warning findings and their count. GitHub output emits escaped `::warning`
+annotations for warnings and `::error` for errors, retaining bounded annotation output.
+Repository reports embed the same commit report shape. Configuration inspection, quality-advisory
+reports, and operational-error envelopes retain their existing schema v1 contracts.
+
+## Ordinary messages and authoring help
+
+Teams that want message policy without Conventional Commit prefixes can opt into plain format:
+
+```toml
+[tool.yaga.commit]
+message-format = "plain"
+header-max-length = 100
+body-policy = "required"
+```
+
+Or start from an editable, frozen policy with `yaga config init --starter plain-v1`.
+The default remains `"conventional"`; format is never inferred from the message. Plain format
+requires a nonempty first line without outer whitespace or unsafe controls. The whole first line
+is the description. Header/description limits, casing and ending policy, body/footer rules,
+references, spelling, warnings, Git merge policy, and explicit ignored headers still apply.
+A blank line must separate the title from body or footers.
+
+Plain parsing does not invent a type, scope, or header breaking marker, even when the text looks
+like `fix(core)!: example`. Final footer parsing is shared, including recognized breaking footers,
+but `!` has no special header meaning. Plain configuration rejects `allowed-types`, `type-case`,
+`scope-policy`, `allowed-scopes`, `scope-case`, `scope-policy-by-type`, `body-policy-by-type`, and
+`breaking-markers`, even if explicitly set to their conventional defaults. Warning rules for type,
+scope, or marker pairing are also rejected. Remove those keys when converting an existing policy;
+`config show --type` is not applicable to plain format.
+
+This option does not make messages suitable for tools that require Conventional Commit release
+classification. It changes YAGA's explicit validation grammar only. PR titles, opted-in proposed
+messages, and ordinary selected commits use the same configured format; title-only checks still
+exclude body and footer requirements.
+
+### Read-only message templates
+
+```bash
+yaga commit template --type fix --scope cli
+yaga commit template --type fix --scope cli --comment-char ';'
+# With message-format = "plain":
+yaga commit template
+```
+
+`commit template` prints an incomplete draft using the selected policy. It never writes a file,
+changes Git configuration, launches an editor, or rewrites history. Conventional drafts require an
+explicit type and a scope when policy requires one; supplied components must satisfy blocking policy even
+if an ignored-header pattern would otherwise skip checking. Plain drafts reject type/scope options.
+
+The description is deliberately blank. Required footer labels have blank values: YAGA does not
+invent a reason, work-item ID, sign-off identity, or a `Validation: passed` claim. Commented guidance
+shows effective prose requirements, relevant limits, allowed footer values, and warning rules.
+Complete the draft yourself and validate the final message; the draft is not a passing example.
+
+Template comments default to `#`; `;` is also supported explicitly. Match the Git editor's comment
+character or remove the guidance before committing. YAGA does not inspect or change that setting.
+`commit check --file` reads comments literally; `--edit` uses Git's configured cleanup behavior.

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/configuration.md

@@ -89,7 +89,7 @@ versions, joined by commas (all must match). Each numeric component has at most
 no leading zeroes. The limit is eight comparisons and 256 characters. Wildcards, compatible-release
 operators, prereleases, URLs, and other Python packaging requirement syntax are not supported.
 
-This setting applies to commands that load this configuration: commit checks and quality, the
+This setting applies to commands that load this configuration: commit checks, templates, and quality, the
 GitHub commit adapter, repository checks selecting the commit provider, and `config show`.
 Explicit-policy providers such as `branch check` and `tree check` retain their no-discovery
 contract. Use `yaga config show --config pyproject.toml` as an explicit version preflight before
@@ -102,6 +102,11 @@ version. Pin the installation separately when CI must always use one exact relea
 
 | Key | Values and purpose |
 | --- | --- |
+| `message-format` | `conventional` (default) or `plain`; [format boundaries](commit-policy.md#ordinary-messages-and-authoring-help). |
+| `warning-rules` | Empty-default list of configurable diagnostic codes to report without blocking; [gradual enforcement](commit-policy.md#gradual-enforcement). |
+| `pull-request-message` | `title-only` (default) or `title-and-body`; [proposed merge messages](github-actions.md#proposed-merge-messages). |
+| `required-issue-prefixes` | Empty-default bounded reference prefixes; [matching rules](commit-policy.md#references-and-footer-values). |
+| `footer-values` | Empty-default exact allowed values by footer token; presence is configured separately. |
 | `allowed-types` | Optional nonempty ordered type tokens. Omit to allow any valid type. |
 | `type-case` | `any`, `lower`, or `upper`. |
 | `scope-policy` | `optional`, `required`, or `forbidden`. |
@@ -116,7 +121,9 @@ version. Pin the installation separately when CI must always use one exact relea
 | `required-footer-tokens` | Up to 128 combined required/forbidden ASCII tokens. |
 | `forbidden-footer-tokens` | Exact case-insensitive presence prohibitions. |
 | `body-policy` | `optional`, `required`, or `forbidden`. |
+| `body-policy-by-type` | Empty-default mapping of up to 128 types to body presence overrides. |
 | `body-min-length` | Nonnegative prose-body character lower bound. |
+| `body-max-length` | Optional total prose-body limit from 1 through 100000; independent of line wrapping. |
 | `body-min-words` | Integer from 0 through 100000, counting prose tokens. |
 | `body-max-line-length` | Optional maximum body-line length; omitted means unlimited. |
 | `body-paragraph-splitting` | `skip` (default) or `check` for likely sentence splits across blank lines. |
@@ -135,6 +142,28 @@ unique, non-overlapping, and cannot use `BREAKING CHANGE` or `BREAKING-CHANGE`.
 
 ### Body layout settings
 
+YAGA 0.2.0 adds `body-policy-by-type` and `body-max-length`. A project can require an
+explanation for behavioral changes while keeping
+documentation and maintenance bodies optional:
+
+```toml
+[commit]
+body-policy = "optional"
+body-min-length = 20
+body-max-length = 2000
+body-policy-by-type = { feat = "required", fix = "required" }
+```
+
+Each case-insensitive type override replaces only body presence, not the other checks. Values
+are `optional`, `required`, or `forbidden`; duplicate normalized keys and keys outside configured
+`allowed-types` are errors. Length and word minima apply when an allowed body exists; they do
+not require an optional body and do not create extra minimum findings for a forbidden body.
+All reachable body policies cannot be forbidden alongside a positive minimum.
+The total limit counts stripped prose, including internal newlines, in the configured
+`length-unit`; recognized final footers are excluded. It cannot be smaller than `body-min-length`
+or too small to contain `body-min-words` one-character words separated by whitespace.
+Both limits report `body.length`. No body requirement or limit applies to a standalone title.
+
 `body-max-line-length` is an optional wrapping limit; omitting it leaves body line length
 unlimited. `body-paragraph-splitting` is an explicit layout heuristic. `skip` (the default) allows
 any paragraph layout. `check` identifies the first blank-line boundary where a one-line prose

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/contributing.md

@@ -1,5 +1,8 @@
 # Contributing
 
+See the [commit policy direction for 0.2.0](commit-policy-direction.md) for the current
+problem-led development scope and customization principles.
+
 The docs gate checks rendered local links and anchors, including README routes and the public
 logo, against the built site. Run `uv run make docs` after changing documentation or navigation.
 

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Get started
 
-This guide covers **YAGA 0.1.2 (Beta)**. YAGA requires Python 3.12 or newer. Install the **`yaga-cli`** distribution from PyPI;
+This guide covers **YAGA 0.2.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.
 
 ## Install as a global tool

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/docs/github-actions.md

@@ -28,7 +28,7 @@ at the newer main SHA fails closed. This mode does not support older server beha
 `pull_request_target` from a non-default target branch.
 
 Retain a revision-aware concurrency group containing both PR number and head SHA, and subscribe
-to `edited` as well as commit lifecycle events so title edits are checked. For django-ray,
+to `edited` as well as commit lifecycle events so title and body edits are checked. For django-ray,
 retain the required job name `Commit Messages`. A successful message comparison alone does not
 establish safe event/checkout integration.
 
@@ -46,6 +46,39 @@ consumer's real-event qualification; they do not authorize a production cutover.
 Use ordinary unprivileged CI for repository checks. The write-capable review adapter has a
 separate [deployment guide](github-review-adapter.md); it is not required to use YAGA in CI.
 
+## Proposed merge messages
+
+Repositories using the PR title and description as the default commit message can opt in:
+
+```toml
+[tool.yaga.commit]
+pull-request-message = "title-and-body"
+body-policy = "required"
+body-min-words = 8
+```
+
+Use `[commit]` in `.yaga.toml`. The default `"title-only"` keeps existing behavior.
+The additional check composes the literal title, a blank line, and the description, then applies
+full commit policy: per-type body requirements, prose limits, breaking markers, footer rules,
+and optional spelling. A missing or null description is empty. Markdown and HTML comments are
+not stripped or interpreted; template text can satisfy structural limits without explaining a change.
+
+GitHub supports title plus description for both
+[squash commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests)
+and [merge commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-merging-for-pull-requests).
+Choose this option to match your repository's intended message source. YAGA does not read or modify
+GitHub merge settings. Rebase merges use existing commit messages; multiple enabled merge methods,
+GitHub-generated text, and last-minute message edits can produce a different final commit.
+This check validates the proposed event text, not the final merged object.
+
+Subscribe to `edited` events as well as commit lifecycle events: changing a description does not
+change the PR head SHA. Preserve the workflow's concurrency and trusted-policy protections.
+The existing title and commit results remain separate. An enabled check adds `proposed_message`
+inside the schema-v1 JSON `pull_request` object and includes it in result counts; the key is absent
+in default mode. Text and GitHub summaries identify the additional proposed message explicitly.
+Author exemptions apply to it only after normal event, checkout, policy, and range validation.
+`merge-commits = "ignore"` does not skip it because no Git merge parents exist for proposed text.
+
 ## Pull-request checks in GitHub Actions
 
 `yaga github pull-request check` applies the same commit policy to a GitHub event without calling

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yaga-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Configurable developer workflow checks for local use and GitHub Actions"
 readme = "README.md"
 license = "BSD-3-Clause"

yaga_cli-0.2.0/release-notes.md

@@ -0,0 +1,21 @@
+### Added
+
+- Support explicit plain-message policy and a frozen `plain-v1` starter; print incomplete,
+  policy-guided drafts with `commit template` without changing files or Git.
+
+- Introduce opt-in `warning-rules` for gradual policy adoption, with consistent schema-v1 commit
+  reports containing severity and warning counts, and nonblocking annotations.
+
+- Require bounded work-item references and constrain exact footer values through opt-in
+  `required-issue-prefixes` and `footer-values` settings.
+
+- Add frozen editable workflow starters and `config show --type` explanations of effective
+  body/scope overrides, preserving the existing default starter.
+
+- Validate proposed PR title-plus-description messages with opt-in `pull-request-message`,
+  reusing full commit policy and reporting the proposed message separately.
+
+- Allow per-type body requirements with `body-policy-by-type` and cap total prose with
+  `body-max-length`, preserving existing defaults and independent title checks.
+
+[PyPI](https://pypi.org/project/yaga-cli/0.2.0/)

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/src/yaga/commands/commit.py

@@ -7,6 +7,7 @@ from typing import Annotated
 
 import typer
 
+from yaga.commits.config import load_config
 from yaga.commits.github_reporting import (
     CommitOutputFormat,
     render_commit_error,
@@ -19,11 +20,43 @@ from yaga.commits.reporting import (
 )
 from yaga.commits.service import check_commit_quality
 from yaga.commits.service import check_commits as check_commit_service
+from yaga.commits.template import TemplateComment, message_template
 from yaga.errors import YagaError
 
 app = typer.Typer(help="Inspect and enforce commit-message policy.", no_args_is_help=True)
 
 
+@app.command("template")
+def template(
+    commit_type: Annotated[
+        str | None, typer.Option("--type", help="Explicit conventional commit type.")
+    ] = None,
+    scope: Annotated[
+        str | None, typer.Option("--scope", help="Explicit conventional scope, if needed.")
+    ] = None,
+    repository: Annotated[
+        Path, typer.Option("--repo", help="Configuration discovery root.")
+    ] = Path("."),
+    config: Annotated[
+        Path | None, typer.Option("--config", help="Use one explicit configuration file.")
+    ] = None,
+    comment: Annotated[
+        TemplateComment,
+        typer.Option("--comment-char", help="Match the editor's Git comment character."),
+    ] = TemplateComment.HASH,
+) -> None:
+    """Print an incomplete, policy-guided message template without modifying files or Git."""
+    try:
+        loaded = load_config(config, start=repository.expanduser().resolve())
+        output = message_template(
+            loaded.policy, commit_type=commit_type, scope=scope, comment=comment
+        )
+    except YagaError as error:
+        typer.echo(render_commit_error(error, CommitOutputFormat.TEXT), err=True)
+        raise typer.Exit(code=2) from error
+    typer.echo(output, nl=False)
+
+
 @app.command("check")
 def check_commits(
     edit: Annotated[

{yaga_cli-0.1.2 → yaga_cli-0.2.0}/src/yaga/commands/config.py

@@ -8,7 +8,7 @@ from typing import Annotated
 import typer
 
 from yaga.commits.config import load_config
-from yaga.commits.config_init import initialize_config
+from yaga.commits.config_init import ConfigStarter, initialize_config
 from yaga.commits.models import OutputFormat
 from yaga.commits.reporting import render_config, render_error
 from yaga.errors import YagaError
@@ -18,6 +18,9 @@ app = typer.Typer(help="Inspect YAGA configuration.", no_args_is_help=True)
 
 @app.command("init")
 def init_config(
+    starter: Annotated[
+        ConfigStarter, typer.Option("--starter", help="Frozen editable starter policy.")
+    ] = ConfigStarter.RECOMMENDED_V1,
     repository: Annotated[
         Path,
         typer.Option(
@@ -39,7 +42,7 @@ def init_config(
 ) -> None:
     """Create or preview a recommended standalone .yaga.toml without overwriting."""
     try:
-        loaded = initialize_config(repository, dry_run=dry_run)
+        loaded = initialize_config(repository, dry_run=dry_run, starter=starter)
     except YagaError as error:
         typer.echo(render_error(error, output_format), err=True)
         raise typer.Exit(code=2) from error
@@ -48,6 +51,10 @@ def init_config(
 
 @app.command("show")
 def show_config(
+    commit_type: Annotated[
+        str | None,
+        typer.Option("--type", help="Explain body and scope requirements for this type."),
+    ] = None,
     repository: Annotated[
         Path,
         typer.Option("--repo", help="Configuration discovery root."),
@@ -64,7 +71,8 @@ def show_config(
     """Show the effective configuration and its source."""
     try:
         loaded = load_config(config, start=repository.expanduser().resolve())
+        rendered = render_config(loaded, output_format, commit_type=commit_type)
     except YagaError as error:
         typer.echo(render_error(error, output_format), err=True)
         raise typer.Exit(code=2) from error
-    typer.echo(render_config(loaded, output_format))
+    typer.echo(rendered)