Align project policies and simplify the release workflow

docs/policy/agents.md

@@ -0,0 +1,88 @@
+# Agent Policy
+
+**Base Policy Version:** 1.1
+
+**Last Updated:** 2026-09-23
+
+## Purpose
+
+Agents must follow these house rules before recommending, planning, or
+implementing repository changes.
+
+## Implementation Discipline
+
+Write the simplest idiomatic code that satisfies the user's request.
+Simplify the mechanism, not the user's choices. Do not implicitly strengthen
+requirements, restrictions, or guarantees.
+
+**Keep implementation machinery proportionate.** Use straightforward,
+idiomatic code and introduce only the machinery needed to support the requested
+behavior and flexibility. Optimize for conceptual simplicity and
+maintainability, not for the fewest lines, fewest options, or narrowest product
+surface.
+
+**Do not invent restrictions.** Do not reject, prohibit, constrain, cap,
+harden, or otherwise narrow behavior unless required by the user, an explicit
+repository contract, or an unavoidable correctness constraint. Preserve
+operator and caller choice where policy has not been established. If an
+additional restriction appears advisable, present it as a decision rather than
+silently implementing it.
+
+A correctness constraint must follow from the requested behavior or an
+established invariant, not from the convenience of the chosen implementation.
+Explain the specific failure it prevents and why a less restrictive
+implementation cannot satisfy the contract.
+
+**An implementation detail is not repository policy.** Tests and documentation
+must not elevate incidental behavior into a durable guarantee or restriction
+unless that behavior was expressly selected as part of the contract. Existing
+explicit contracts remain authoritative; changing or weakening one requires a
+deliberate decision rather than being inferred from this principle.
+
+Agent-authored plans, tests, documentation, and prior implementations are not
+evidence that an additional restriction was deliberately approved. Identify the
+authorizing requirement or decision; when that authority is unclear, surface
+the ambiguity rather than treating repetition as approval.
+
+**Do not invent guarantees.** Do not strengthen public contracts, guarantees,
+or invariants beyond those expressly requested by the user.
+
+**Use the standard library.** Prefer simple, idiomatic standard-library
+implementations when they satisfy the requested behavior. Do not add custom
+power-loss protection or defenses against privileged concurrent filesystem
+actors unless expressly required. Preserve existing repository contracts.
+
+## Git Commit Policy
+
+By default, create a commit after completing each coherent unit of work, using a
+concise, plain-English message describing what changed. This policy is standing
+authorization to create those local commits; a separate user request is not
+required. An explicit user instruction to leave work uncommitted takes precedence.
+
+A unit of work is a focused, reviewable outcome, including its relevant tests and
+documentation. Do not commit after every intermediate edit or create empty commits.
+Complete the appropriate validation before committing. If work is incomplete or
+validation is blocked, report that state rather than presenting it as completed.
+
+Before committing:
+
+1. Run `git status --short` and review the relevant diff, including any staged
+   changes. Identify changes that predate the current unit of work.
+2. Exclude secrets, local environment files, generated junk, and unrelated changes.
+3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
+   only when every included change belongs to that unit. Do not disturb unrelated
+   staged or unstaged work.
+4. Review `git diff --staged` and run appropriate checks for the change. Do not
+   repeat checks already passed for unchanged content merely to create a commit.
+5. Review `git log --oneline -n 10` and use
+   `git commit -m "<concise plain-English commit message>"`.
+6. Report the commit identifier and any remaining uncommitted work.
+
+If the unit cannot be safely separated from pre-existing work, leave it uncommitted
+and explain the overlap rather than silently including that work. If a commit
+fails, preserve the changes and report the failure; do not bypass hooks.
+
+Default commit authorization does not authorize pushing, publishing, amending,
+resetting, reverting, or rewriting history. Those actions require a separate user
+instruction. Do not use `git commit -a` or `git commit --no-verify` to bypass the
+staging and validation discipline above.

docs/policy/architecture.md

@@ -1,5 +1,9 @@
 # Architecture Policy
 
+**Base Policy Version:** 1.0
+
+**Last Updated:** 2026-09-23
+
 ## Purpose
 
 This document defines Promptkit's current high-level architecture and the
@@ -17,42 +21,9 @@ The module root contains package `promptkit`, which is the public facade. It
 provides the supported engine, configuration and source options, requests,
 results, public values, extension interfaces, profiles, and error sentinels.
 
-The implemented internal components consist of:
-
-- `internal/domain`, which owns framework data values and source-neutral
-  invariants shared by later internal components;
-- `internal/backend`, which owns validated immutable OpenAI-compatible backend
-  definitions;
-- `internal/capacity`, which owns engine-local bounded run admission and
-  model-generation scheduling for limited backends;
-- `internal/defaults`, which owns application-neutral framework defaults and
-  constructs the default execution target;
-- `internal/filecatalog`, which discovers YAML files and provides source-path
-  helpers for filesystem and `fs.FS` consumers;
-- `internal/catalog`, which validates immutable external maintained-catalog
-  assets and their reserved profile namespace before they are eligible for
-  engine assembly;
-- `internal/jsonvalue`, which validates and defensively copies JSON-compatible
-  extra-parameter trees;
-- `internal/promptdef`, which loads and validates prompt definitions from
-  filesystem and `fs.FS` sources;
-- `internal/profile`, which loads, validates, and overlays execution profiles
-  from filesystem and `fs.FS` sources;
-- `internal/prompt`, which renders prompt messages from Go templates;
-- `internal/artifact`, which resolves ordinary inline and unrestricted
-  caller-selected file references;
-- `internal/validate`, which validates basic, JSON, and JSON Schema output
-  using filesystem and `fs.FS` schema sources;
-- `internal/llm`, which defines the provider-neutral generation boundary and
-  implements outbound OpenAI-compatible chat requests; and
-- `internal/usecase`, which coordinates preparation and execution across the
-  internal framework components.
-- `internal/engine`, which assembles those components into one engine and
-  delegates execution to the use-case runner.
-
-The `examples/go-library/prepare` and `examples/go-library/run` packages are
-maintained downstream consumers of the root facade. They do not expose library
-packages or participate in internal assembly.
+The [internal component overview](../internal/overview.md) owns the inventory
+of implemented packages and their concrete responsibilities. This policy owns
+the boundaries and dependency rules those components must preserve.
 
 The internal engine assembles one immutable backend registry, one capacity manager,
 the internal repositories, renderer, validator, outbound client, and use-case

docs/policy/documentation.md

@@ -1,5 +1,9 @@
 # Documentation Policy
 
+**Base Policy Version:** 1.1
+
+**Last Updated:** 2026-09-23
+
 ## Purpose
 
 This policy assigns each Promptkit documentation topic to one canonical owner.
@@ -68,17 +72,19 @@ mechanisms, not secret values.
 
 | Topic | Canonical owner | Owned content | Content owned elsewhere |
 | --- | --- | --- | --- |
-| Project orientation | `README.md` | What Promptkit is, its current usability, module identity, license summary, and links onward. | Exact API contracts, contributor procedures, architecture detail, and release steps. |
+| Project orientation | `README.md` | What Promptkit is, its current usability, module identity, license summary, a minimal successful quickstart, and links onward. | Exact API contracts, contributor procedures, architecture detail, and release steps. |
 | Contributor workflow | `docs/development.md` | Task-oriented reading guide, local workflow, validation commands, and repository hygiene. | Architecture rules, API semantics, subsystem behavior, and release procedure. |
 | Current architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, package boundaries, invariants, and non-goals. | Concrete component inventory, implementation mechanics, contributor procedures, decision history, and future work. |
+| Agent policy | `docs/policy/agents.md` | Agent implementation discipline, proportionality, idiomatic simplicity, local commit authorization and discipline, and rules against inventing restrictions, guarantees, or repository policy. | Public contracts, architecture, testing, and contributor procedures. |
 | Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and document lifecycle. | Library architecture or runtime behavior. |
 | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression policy, and test maintenance. | Subsystem behavior, exact public contracts, subsystem-specific test inventories, and implementation plans. |
-| Release procedure | `docs/release.md`, when present | Required release validation, version and tag procedure, release ordering, and post-publication checks. | General contributor workflow, public API semantics, and decision history. |
+| Release policy | `docs/policy/release.md` | Versioning, compatibility, release-note requirements, validation obligations, immutability, recovery, and adoption scope. | Executable commands, publication mechanics, and historical release summaries. |
+| Release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, concrete publication guards and commands, verification, and recovery steps. | Release-policy requirements, public API semantics, and historical summaries. |
 | Exact exported Go API | Go declarations and GoDoc, as APIs are implemented | Exported names, signatures, types, values, errors, and exact behavioral contracts. | Task-oriented consumer walkthroughs, implementation details, and future API proposals. |
 | Framework file formats | `docs/formats.md` | Prompt-definition and profile YAML fields, schema references, defaults, validation modes, built-in profiles, credentials, and file-to-request precedence. | Exported Go declarations, outbound wire behavior, internal parsing mechanics, and application configuration. |
 | Consumer guidance | `docs/consumers/`, when consumer workflows require dedicated guidance | Task-oriented use of implemented public APIs, minimal examples, and consumer responsibilities. | Exact exported declarations and internal mechanics. |
 | Durable integration contracts | `docs/integrations/`, when integrations exist | External formats and protocols, compatibility behavior, and upstream or downstream responsibilities. | Internal transformations and public Go declarations. |
-| Supplemental release guidance | None. `docs/releases/` may be used when a release benefits from a changelog or migration guide. | No canonical content. These files may briefly summarize release-specific changes, compatibility, and consumer migration paths, and may be corrected, consolidated, archived, or removed when no longer useful. | Public API and behavior contracts, formats, integrations, architecture, release procedure, and the authoritative annotated-tag release record. |
+| Release-note history | `docs/releases/` | Mandatory version-matched historical summaries for releases made under the adopted release policy; the note at the immutable tag records that release. | Current APIs, behavior, formats, compatibility contracts, and release procedures. |
 | Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal documents. | Normative architecture, contributor workflow, external contracts, and proposed components. |
 | Internal subsystem behavior | Other files under `docs/internal/`, when a subsystem needs durable detail | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, public API definitions, and future package plans. |
 | Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
@@ -110,22 +116,22 @@ but must link to its canonical definition rather than restate it.
 The [framework format reference](../formats.md) owns exact prompt, profile, and
 schema-file contracts. Integration documents own external wire formats.
 
-### Supplemental Release Guidance
+### Release Documentation
 
-Files under `docs/releases/` may provide changelog-style summaries and
-migration guidance for a particular release. They are navigation and
-orientation aids, not canonical owners of public APIs, behavior, formats,
-integrations, architecture, release procedure, or other durable facts. When a
-reader needs detail beyond a short release-specific note, the release document
-must link to the applicable canonical documentation rather than reproduce its
-contract.
+The [release policy](release.md) owns release requirements; the
+[repository release procedure](../release.md) owns their concrete execution.
+Version-matched checked-in notes are required for future releases under that
+policy. The source tag is the release identity, and the note in its immutable
+tree is the historical summary; annotated tag messages complement that record.
 
-The annotated tag message required by the
-[release procedure](../release.md#write-the-release-note) remains the
-authoritative release record. Supplemental release documents may be corrected,
-consolidated, archived, or removed at any time when they are no longer useful,
-provided maintained documentation does not depend on them and the annotated
-tag record remains intact.
+Release notes do not own current API or behavior contracts. Link to the
+canonical owners for details instead of reproducing those contracts. Published
+notes are not disposable guidance and must not be replaced under the same
+version. Corrections belong in a subsequent release.
+
+Adoption is prospective. Previously published tags and historical notes retain
+their original records and are not reformatted or rewritten to satisfy the new
+requirements.
 
 ### Security Topics
 
@@ -178,9 +184,8 @@ durable owners, update incoming links, and archive or remove the roadmap
 according to repository practice. Do not preserve completed roadmaps as a
 second current-state reference.
 
-Supplemental release documents may likewise be removed without preserving a
-replacement. Before removal, update maintained incoming links so current
-documentation does not depend on an optional historical guide.
+Retain release notes as historical records under the release policy. Do not
+apply temporary-roadmap retirement rules to published release notes.
 
 Before completing documentation work:
 

docs/policy/release.md

@@ -0,0 +1,146 @@
+# Release Policy
+
+**Base Policy Version:** 1.0
+
+**Last Updated:** 2026-09-23
+
+## Purpose And Adoption Scope
+
+This policy owns Promptkit's release requirements and compatibility rules.
+The [release procedure](../release.md) owns the commands used to satisfy them.
+This scoped adoption applies to releases prepared after its adoption on
+2026-09-23. Published tags and historical notes are not rewritten to retrofit
+the new note format.
+
+## Release Model And Compatibility
+
+Promptkit publishes source-only Go module releases from committed, pushed
+`main` candidates through annotated `vMAJOR.MINOR.PATCH` tags. It publishes
+no binaries, hosted releases, or other artifacts and uses maintainer-run
+validation rather than hosted CI. Versions must be unused locally and on
+`origin`; the existing procedure accepts stable version tags only.
+
+Before v1, minor releases may change the public API and patches preserve
+compatibility within their minor line, subject to the catalog-data provision
+below. Release notes must identify compatibility impact, public API changes,
+and required consumer action. The source tag identifies the exact release;
+the checked-in note at that tag records its historical summary.
+
+## Catalog Profile Compatibility
+
+External catalog profile data may be added, removed, renamed, or modified
+without deprecation or advance notice. This exception is limited to profile
+data imported from the maintained catalog modules. It does not weaken ordinary
+compatibility for Promptkit's public Go API, configuration and format semantics,
+runtime behavior, catalog-module APIs, manifest schema, backend definitions, or
+consumer-owned definitions.
+
+Within the catalog versions selected and tested by a Promptkit release, and
+unless a consumer overrides the name or its base, Promptkit keeps the literal
+profile IDs `promptkit-openrouter-standard` and
+`promptkit-openrouter-auto` available. The names do not promise a permanent
+model, backend, routing behavior, settings, cost, output, or upstream
+availability. The [framework format reference](../formats.md#built-in-profile-catalog)
+owns their current definitions.
+
+`v0.10.0` is the initial minor release for this compatibility transition.
+Afterward, catalog-only updates and adjustments to the current selections may
+ship in a patch release when all other compatibility obligations remain intact.
+External profile removals can require consumer action; they are not automatic
+migrations.
+
+Catalog adoption and release validation remain local and offline. They do not
+probe provider endpoints, request model lists, or make inference calls.
+
+## Release Documentation
+
+Every new release must include `docs/releases/<version>.md` in the tagged
+source, using the complete tag as the filename. Its title contains Promptkit
+and that exact version. Use this structure:
+
+```markdown
+# Promptkit vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+State “No action required” or “None” where appropriate rather than omitting a
+section. Keep exact current contracts in their canonical documents and link
+to them. Update affected canonical documentation in the same candidate.
+
+These notes are historical records, not optional disposable guidance. Published
+release-note contents must not be replaced under the same version. Corrections
+belong in a subsequent release. Annotated-tag messages complement the checked-in
+note: generate the annotation from that note and the validated commit rather
+than maintaining a second summary.
+
+## Validation And Publication
+
+The [publication script](../../scripts/release.sh) runs the
+[local checks](../../scripts/release-check.sh) once for the final candidate.
+Retain clean-candidate, synchronized-main, unused-version, module-hygiene,
+release-note structure, and tag-target checks. Publish only the selected tag
+ref. Changing the candidate requires fresh validation. No provider endpoint
+probes or inference calls are release checks.
+
+Release-note content and retirement of completed roadmaps are preparation
+responsibilities, not separate human sign-off gates. Preserve planned and
+deferred work and repair links. Ordinary change review covers unintended files,
+secrets, and private data; do not repeat it as a release-specific approval.
+
+A successful tag push to origin completes the release. Never wait for CI to
+finish or succeed. CI results, remote read-back, and Go module availability
+are informational follow-ups, not completion gates. An ambiguous push result
+requires confirming publication on origin, not waiting for CI.
+
+## Immutability And Failure Recovery
+
+Never move, replace, recreate, or delete a published tag or replace published
+release contents. If validation fails before publication, correct the candidate,
+rerun the complete checks, and repeat the publication guards. Remove an
+unpublished local tag only after confirming it was not published.
+
+If publication or subsequent investigation reveals a defect, leave the
+published release intact. Correct the defect on main, select a new patch or
+other semantically appropriate version, write its matching release note, and
+repeat the complete procedure. If publication status is uncertain, inspect
+the authoritative remote before deciding whether a tag is unpublished; do not
+overwrite it to retry.
+
+Transient network, authentication, CI, or module-availability failures do not
+by themselves warrant a new version. Investigate separately and publish a
+corrective release only when published contents actually need changing.
+
+## Policy Exceptions And Deliberate Scope
+
+This adoption follows the maintainer-approved lean workflow rather than every
+base-policy guard:
+
+- Collision checks concern origin, the authoritative publication destination,
+  rather than every configured remote. Local and origin tag checks, synchronized
+  main, and an explicit selected-ref push protect the actual release channel.
+- Automated local validation and publication-state checks replace manual
+  mechanical inspections and separate human sign-offs. Ordinary change review,
+  editorial responsibility for release notes, and roadmap housekeeping remain;
+  repeating them as approvals would add friction without distinct protection.
+- Successful tag publication completes this source-only release. CI can be slow
+  or unreliable, and module availability depends on external services. Neither
+  is a completion gate. Local candidate validation and explicit tag-target
+  checks protect publication; ambiguous push results are resolved against origin.
+  Actual defects are corrected in a new release, never by replacing a tag.
+
+Ignored local files are not prohibited merely because they exist: they are not
+included in the tagged commit. The clean-candidate guard and ordinary review of
+tracked changes protect the published contents.
+
+The catalog profile provision preserves an already approved compatibility
+boundary; it does not extend volatility to backend definitions or runtime
+contracts. Further release-governance changes require deliberate approval.

docs/policy/testing.md

@@ -1,5 +1,9 @@
 # Testing Policy
 
+**Base Policy Version:** 1.0
+
+**Last Updated:** 2026-09-23
+
 ## Purpose
 
 Our tests exist to make **incorrect changes expensive and correct changes cheap**.
@@ -50,16 +54,21 @@ Examples of appropriate seams include clocks, randomness, subprocesses, remote A
 ## Test execution requirements
 
 Promptkit currently uses maintainer-run validation rather than hosted CI.
-Maintainers run the complete local workflow in the
-[development guide](../development.md#maintainer-validation) before accepting
-changes. That guide is the canonical owner of exact commands, formatting,
-documentation-link validation, and repository-hygiene checks.
+Ordinary work requires validation proportionate to its scope and risk. Do not
+repeat successful checks for unchanged content merely to create a commit.
+Release candidates require the complete local workflow in the
+[development guide](../development.md#maintainer-validation). That guide routes
+contributors to the executable checks for formatting, documentation links,
+and repository hygiene.
 Introducing hosted CI later would supplement, not silently redefine, this
 documented validation model.
 
-Maintainer validation must include ordinary and race-enabled package tests,
-static analysis, a complete build, and execution of both maintained offline
-consumer examples. The preparation example protects assembled preparation and
+Full release-candidate validation includes race-enabled package tests, explicit
+static analysis, and execution with automated semantic checks of both maintained
+offline consumer examples. The test run builds the packages; the examples
+also exercise ordinary compilation. Separate ordinary tests and a standalone
+build are not additional release gates. Ordinary tests remain useful during
+development. The preparation example protects assembled preparation and
 inspection behavior. The execution example separately protects assembled
 `Run`, injected-client, validation, usage, and result behavior.