From ba0d99f107f4a64d8ef0a0ae50841146506d6c22 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 01:41:33 +0000 Subject: [PATCH] Adopt policy provenance and documentation guidance --- AGENTS.md | 8 +- docs/development.md | 32 +++++-- docs/oss/attribution.md | 5 +- docs/policy/agents.md | 22 ++--- docs/policy/documentation.md | 150 ++++++++++++++------------------- docs/policy/meta.md | 27 ++++++ docs/roadmap/implementation.md | 5 +- 7 files changed, 138 insertions(+), 111 deletions(-) create mode 100644 docs/policy/meta.md diff --git a/AGENTS.md b/AGENTS.md index aa3a737..8b791c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,6 @@ -Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide. +Start with `docs/development.md` for orientation and use its policy reading guide +to select the policies applicable to the task. Do not read the entire suite by +default. -Review and follow `docs/policy/agents.md` before recommending, planning, or -implementing changes to this repository. +Read and follow `docs/policy/agents.md` before recommending, planning, or +implementing repository changes. diff --git a/docs/development.md b/docs/development.md index 1e022c6..426865f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -10,15 +10,31 @@ uses ConfigKit v0.4.1; keep Scriptorium's schema and source selection local. Before recommending, planning, or implementing work: -1. read the [agent policy](policy/agents.md); -2. inspect the working tree and preserve unrelated changes; -3. read the [architecture policy](policy/architecture.md); -4. follow the task-specific contracts and internal documents below; and -5. inspect the relevant implementation and tests before changing them. +1. inspect the working tree and preserve unrelated changes; +2. use the policy and task-specific reading guides below; and +3. inspect the relevant implementation and tests before changing them. -Also read the [documentation policy](policy/documentation.md) before changing -documentation and the [testing policy](policy/testing.md) before changing -tests. +## Policy Reading Guide + +| Policy | Read before… | +| --- | --- | +| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. | +| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. | +| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. | +| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. | +| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. | +| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. | +| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. | + +- Read applicable policies before making decisions they govern; multiple policies + may apply. +- Select policies using the task triggers above. Follow cross-references to + relevant sections when needed to resolve a concrete question. +- Reuse policies already available in context; reread when changed or no longer + available. +- Expand reading when the task's scope expands. +- When revising a policy itself, read that policy and any provisions elsewhere + affected by the revision. ## Task-Specific Reading Guide diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 90f2e0c..bfa5237 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -2,7 +2,10 @@ ## Standard Repository Policies -Material: `docs/policy/oss.md`, adapted for this repository. +Material: `docs/policy/oss.md`, `docs/policy/meta.md`, +`docs/policy/agents.md`, `docs/policy/documentation.md`, `AGENTS.md`, and the +Policy Reading Guide section of `docs/development.md`, adapted for this +repository. Copyright (C) 2026 Eric Rakestraw diff --git a/docs/policy/agents.md b/docs/policy/agents.md index 1703b31..1e972e3 100644 --- a/docs/policy/agents.md +++ b/docs/policy/agents.md @@ -1,12 +1,14 @@ # Agent Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.3 -**Last Updated:** 2026-09-26 +**Last Updated**: 2026-09-28 + +**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md ## Purpose -Agents working in this repository must read and adhere to the following house rules. +Agents must read and follow these rules. ## Implementation Discipline @@ -43,15 +45,15 @@ unless that behavior was expressly selected as part of the contract. ## Git Commit Policy -By default, create a commit after completing each coherent unit of work, using a +By default, commit each completed, nonempty 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. +documentation. Complete the appropriate validation before committing. If work is incomplete or -validation is blocked, report that state rather than presenting it as completed. +validation is blocked, report that state accurately. Before committing: @@ -59,10 +61,10 @@ Before committing: 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. + only when every included change belongs to that unit. Preserve unrelated + staged and unstaged work. +4. Review `git diff --staged` and run appropriate checks for the change. Reuse + successful checks for unchanged content. 5. Review `git log --oneline -n 10` and use `git commit -m ""`. 6. Report the commit identifier and any remaining uncommitted work. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 7c5f51d..ad0e062 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,15 +1,16 @@ # Documentation Policy -**Base Policy Version:** 1.4 +**Base Policy Version:** 1.11 -**Last Updated:** 2026-09-26 +**Last Updated**: 2026-09-28 + +**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md ## Purpose This policy assigns each documentation topic to one canonical owner. Its goal is -to keep this repository's documentation accurate, concise, discoverable, and -resistant to drift for users, operators, developers, integrators, and LLM -coding agents. +to keep this application's documentation accurate, concise, discoverable, and resistant +to drift for users, operators, developers, integrators, and LLM coding agents. ## Core Rules @@ -17,45 +18,38 @@ coding agents. Each authoritative fact belongs in one document. A non-owning document may give a short, stable summary for orientation, but it must link to the canonical owner -instead of repeating volatile details. +for volatile details. Volatile details include commands, flags, configuration fields and defaults, module keys, schemas, file names, paths, status codes, retry behavior, and runtime guarantees. If readers could reasonably treat a statement as a contract, maintain it only in the owning document. -Minimal tested usage examples are allowed outside the owning contract when this -policy assigns them an orientation or instructional purpose. They must link to -the canonical contract and must not redefine complete syntax, defaults, or -semantics. - ### Current And Future Behavior Outside `docs/roadmap/`, documentation describes implemented behavior only. Partial features may be described only to their implemented boundary. -Architectural constraints may govern future changes without implying that the -components or capabilities they would govern already exist. This does not -permit describing a proposed system structure as implemented. +Architectural constraints may govern future changes. Describe current structure +from implemented behavior. -ADRs may record an accepted architectural decision before implementation, but -acceptance must not be presented as proof that the behavior exists. The roadmap -owns implementation status and sequencing until the decision is implemented. -Current architecture, user, operator, -integration, and internal documentation are updated when the behavior lands. +ADRs may record an accepted architectural decision before implementation. The +roadmap owns implementation status and sequencing until the decision is +implemented. Current architecture, user, operator, integration, and internal +documentation are updated when the behavior lands. ### Audience And Detail Write for the document's stated audience and include only the detail needed for -its owned topic. User and operator docs should not expose implementation detail. -Developer docs should link to user-facing and external contracts rather than -restate them. +its owned topic. Keep user and operator docs focused on using and operating the +application. Developer docs should link to user-facing and external contracts +for their definitions. ### Examples Complete copyable files belong in `examples/`. Documentation may use the smallest illustrative snippet needed to explain its owned topic, but should link -to maintained examples instead of embedding a second complete copy. +to maintained examples for complete copyable files. Examples must be valid, secret-free, and tested where practical. Commands and configuration used in documentation should match the application. @@ -71,43 +65,42 @@ secret values. | Topic | Canonical owner | Owned content | Content owned elsewhere | | --- | --- | --- | --- | -| Product orientation and minimal end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward, including license and attribution navigation. | Complete command reference, configuration reference, operational procedures, implementation detail. | -| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, and detailed change recipes, which belong in the relevant internal component document. | -| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | -| Agent policy | `docs/policy/agents.md` | Agent implementation discipline, proportionality, idiomatic simplicity, local commit rules, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. | -| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | -| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | +| Product orientation and minimal end-to-end quickstart | `README.md` | Purpose, value, shortest successful invocation, and navigation, including licensing and attribution. | Complete command reference, configuration reference, operational procedures, implementation detail. | +| Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. | +| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | +| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. | +| Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. | +| Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | +| Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | +| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. | +| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. | +| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. | +| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. | +| Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. | +| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. | +| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. | | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. | -| Configuration contract | `docs/config.md` | Application discovery and precedence, source locations, server fields, render default, HTTP limits, and credential mapping. | Promptkit framework formats and defaults, complete example files, CLI syntax, runtime lifecycle, and implementation detail. | -| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | -| Release policy | `docs/policy/release.md` | Versioning and compatibility, release integrity and immutability, documentation requirements, proportionate gates, publication controls, source completion, and optional verification boundaries. | Repository-specific commands, installation guidance, historical summaries, and CI implementation details. | -| Release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, publication command and guards, asynchronous delivery, optional diagnostics, and failure recovery. | General release requirements, runtime operations, historical announcements, and current application contracts. | -| Version-specific release notes | `docs/releases/` | Immutable release summaries, compatibility notices, and migration announcements for one published version. | Complete CLI, HTTP, configuration, operations, or dependency contracts. | -| Open source licensing and attribution policy | `docs/policy/oss.md` | House attribution format, license-text and notice-link conventions, discoverability, maintenance, and handling of concrete exceptions. | Component entries, license texts, release commands, and dependency security review. | -| Project license | `LICENSE` | The project's own license terms. | Upstream component attribution and dependency license texts. | -| Upstream component attribution | `docs/oss/attribution.md` | Component names, copyright statements, license identification, and license, notice, and source links. | General attribution policy and complete standard license texts. | -| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by attribution entries where applicable. | Project-specific upstream notices, attribution prose, and policy interpretation. | +| Configuration contract | `docs/config.md` | Application configuration discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | PromptKit framework formats and defaults, complete example files, CLI syntax, runtime state lifecycle, module implementation details. | +| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | | Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. | -| Consumer guidance | `docs/consumers/` | Choosing between Scriptorium's executable interfaces and understanding consumer responsibilities. | HTTP wire semantics, CLI syntax, Promptkit's Go package, and internal implementation detail. | -| External and durable integration contracts | `docs/integrations/` | Scriptorium-owned process and executable integration contracts. | Promptkit framework formats and outbound provider protocols, physical runtime placement, internal transformations, CLI syntax, and configuration defaults. | -| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | -| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | -| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | -| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. | -| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. | +| Consumer guidance for executable use and migration | `docs/consumers/` | Task-oriented executable use, migration to PromptKit, minimal examples, and consumer responsibilities. | HTTP wire semantics, CLI syntax, PromptKit's public Go API, external protocol contracts, internal implementation detail. | +| Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. | +| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | +| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | +| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | +| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | +| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. | +| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. | -Documents that do not exist are required only when the corresponding interface -or responsibility exists. Do not create placeholder API, consumer, integration, -or operations documents for behavior the application does not have. +Create supporting documents for existing interfaces and responsibilities when +substantive content is available. ## Boundary Rules ### Orientation -The README owns product orientation. The developer guide routes contributors. -Architecture owns normative structure. Internal overview owns the current -concrete component map. These documents may link to one another but should not -maintain parallel package or behavior descriptions. +Link among orientation, architecture, and internal documents; maintain each +package or behavior description in its canonical owner. ### Commands, Configuration, And Operations @@ -119,26 +112,25 @@ other contracts. ### Releases -The release policy owns release requirements; the release procedure supplies -the commands that satisfy them. Release notes are historical summaries, not -current-state contract owners. The checked-in note at an immutable tag records -that release; current documentation changes with the behavior it describes. -Neither a procedure nor a note may weaken policy or defer required updates to -canonical contracts. +The release policy defines requirements and invariants that every release must +satisfy. The repository-specific release procedure defines the commands and +workflow maintainers use to satisfy that policy. Release notes record history +at immutable tags. Maintain current behavior in its canonical documentation, +update it with the corresponding behavior changes, and keep release procedures +consistent with adopted policy. -### Open Source Attribution +### Project Licensing And Upstream Attribution -The [OSS policy](oss.md) defines the House Format and README and release-link -conventions. Attribution entries own component-specific information. README -and release documents provide navigation to those canonical materials; the -release procedure owns URL construction and publication mechanics. +README and release documents link to the canonical licensing and attribution +materials under the [OSS policy](oss.md). The release procedure owns URL +construction and publication mechanics. ### Contracts And Implementation Integration and API documents define externally observable shapes and -semantics. Internal documents explain how this project implements or consumes -those contracts. Internal docs may name a field, file, or protocol to identify -a dependency, but must link to its canonical contract for the definition. +semantics. Internal documents explain how this application implements or consumes those +contracts. Internal docs may name a field, file, or protocol to identify a +dependency, but must link to its canonical contract for the definition. ### Security Topics @@ -160,31 +152,13 @@ Use sequentially numbered ADR filenames such as 6. alternatives considered; 7. consequences. -Use one of these statuses: - -- **Proposed:** the decision is under consideration and may change; -- **Accepted:** the decision is approved, whether or not implementation is - complete; -- **Rejected:** the proposed decision was considered and not adopted; -- **Superseded:** a later ADR replaces the accepted decision. - -A proposed ADR transitions to accepted or rejected. An accepted ADR transitions -to superseded only when a later accepted ADR replaces it. An ADR may be created -as accepted when the decision has already been made. - -Treat the decision content of an accepted ADR as immutable. Its status and -supersession metadata may be updated, but a changed decision requires a new ADR. -A superseded ADR must link to its replacement, and the replacement must link -back to the superseded ADR. Rejected architectural alternatives belong in the -ADR; rejected product ideas belong in the roadmap. +Treat the decision content of an accepted ADR as immutable. When a decision +changes, create a new ADR and update the earlier ADR's status to superseded. +Rejected architectural alternatives belong in the ADR; rejected product ideas +belong in the roadmap. ## Maintenance -Every policy document records its underlying template version and local -last-updated date immediately below the title. Update the date when revising -local policy; change the base version only when adopting a newer template. -Do not retain template adoption instructions in the local policy. - When behavior changes, update its canonical owner in the same change. If ownership moves, remove the old definition and replace it with a link where navigation remains useful. diff --git a/docs/policy/meta.md b/docs/policy/meta.md new file mode 100644 index 0000000..04954e3 --- /dev/null +++ b/docs/policy/meta.md @@ -0,0 +1,27 @@ +# Policy Set Provenance + +**Base Policy Version:** 1.0 + +**Last Updated**: 2026-09-28 + +**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md + +## Origin And Local Authority + +This repository's policy set is adapted from +[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). +The adopted local policies govern work in this repository. Upstream revisions +become local policy through deliberate adoption, preserving local decisions. +Each policy's `Upstream Source` identifies its adopted baseline. + +## Adoption And Updates + +For policy adoption, upstream revision reviews, and updates, consult the +[upstream adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md). +That guide and the reference example collection are maintained upstream and +accessed through links. Keep discovery links pointed at the current upstream +project and guide; keep adopted-source and example links pinned to commits. + +The local [developer guide](../development.md) routes tasks to applicable +policies. Formal credit and licensing notices for the copied policy material +belong in the local [attribution document](../oss/attribution.md). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6a6f4a0..9b52811 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -122,7 +122,10 @@ copyright fields are omitted, not explained with agent-authored commentary. ## Stage 2: Adopt Provenance, Agent Guidance, And Documentation Ownership -**Status: Pending.** +**Status: Complete.** The three policies carry the selected versions, source +links, and local adoption date; shared text and the orientation template were +compared with the pinned source. The seven-link reading guide and local links +were checked, and attribution names only the incorporated material. Files: new `docs/policy/meta.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`, root `AGENTS.md`,