automatic 26.08 → 26.09

data/doc/POLICY.md

@@ -22,10 +22,22 @@ The Invariants below decide over the rest of it.
 
 ### 1.1 Purpose and scope
 
+Automatic Ruby is neither system infrastructure nor a purpose-built
+application. It is a general-purpose composition framework. Its purpose is to
+keep a small composition mechanism stable enough that independent plugins can
+be combined freely, without turning the framework into a host baseline, a
+general workflow engine or a collection of hard-coded applications.
+
 - **Automatic Ruby is a framework, and the framework is the small part.** It
   loads a Recipe, finds classes by name and calls them in order. Nearly every
   change belongs in a plugin, and a change that adds domain knowledge to the
   framework needs a reason beyond convenience.
+- **Generality comes from composition, not from accumulating framework
+  features.** A concrete use case that needs branching, transactional
+  orchestration, multi-user state, permissions, a strongly coupled domain
+  model or another responsibility that does not fit a short linear pipeline is
+  not automatically a reason to enlarge the framework. A purpose-built
+  application is often the correct boundary for that complexity.
 - **It is one person's tooling, run unattended from `cron`.** It is not a
   service, not multi-tenant and not a product. That premise decides several
   rules below that would otherwise look lax — the Recipe being trusted, chiefly.
@@ -55,24 +67,42 @@ general policy would otherwise ask for.
 4. **A dependency needed by one plugin is not a dependency of the framework.**
    Installing the gem must not pull in an SDK for a service the operator does
    not use. See section 9.
-5. **A failure is never silent.** No `rescue` that returns an empty pipeline as
+5. **Composability is an architectural invariant, not an optimization goal.**
+   The small framework, independent plugins, one pipeline representation and
+   Recipe-level ordering are the identity of the system. They are not traded
+   away merely for convenience, central validation, richer orchestration or a
+   more application-like design.
+6. **A failure is never silent.** No `rescue` that returns an empty pipeline as
    if nothing happened, and no run that exits zero after something went wrong.
-6. **The default test suite reaches no network and needs no credential.** None
+7. **The default test suite reaches no network and needs no credential.** None
    is configured in CI.
-7. **A plugin that cannot work is never simulated into working.** Stubbing a
+8. **A plugin that cannot work is never simulated into working.** Stubbing a
    dead service to make a test pass, or to make the catalogue look better, is
    forbidden outright. Removing the plugin is the correct outcome. See
    section 4.
-8. **No credential is committed**, in a Recipe, an example, a fixture or a test,
+9. **No credential is committed**, in a Recipe, an example, a fixture or a test,
    and none is written to the log.
-9. **Historical release history is not rewritten.** Past versions and their
-   dates in [`VERSIONS`](VERSIONS) are a record, not a thing to tidy.
-10. **The licence is GPL version 3 or LGPL version 3.** Automatic Ruby is
+10. **Historical release history is not rewritten.** Past versions and their
+    dates in [`VERSIONS`](VERSIONS) are a record, not a thing to tidy.
+11. **The licence is GPL version 3 or LGPL version 3.** Automatic Ruby is
     dual-licensed, and a user may choose either license at their discretion. New
     files use the same dual license.
 
 ### 1.3 Design philosophy
 
+The repository is maintained in three layers, and they do not receive the same
+degree of conservatism.
+
+- **Core contracts receive the strongest compatibility protection:** the
+  Recipe format, plugin contract, pipeline shape, plugin lookup and override
+  semantics, execution order and established CLI contract.
+- **Framework implementation may improve within those contracts:** the CLI,
+  loader, pipeline implementation, logging and shared helpers are not frozen
+  merely because they are old.
+- **Plugins are replaceable components:** they may be added, repaired,
+  replaced or removed as their external systems and purposes change. A dead
+  integration is not retained by simulation.
+
 - Simple comes before clever. Common work should fit in a short Recipe, and a
   new abstraction needs a concrete problem the existing plugin contract cannot
   solve.
@@ -90,7 +120,43 @@ general policy would otherwise ask for.
 - Old is not a defect. Neither is unfashionable. A defect is something that does
   not work, is not understood, or cannot be tested.
 
-### 1.4 The parts and the direction of dependency
+### 1.4 Change discipline and maintenance boundary
+
+Automatic Ruby does not inherit every maintenance rule that is appropriate
+for long-lived host infrastructure. Its core contracts deserve comparable
+caution because external Recipes and plugins depend on them, but the whole
+repository is not treated as immutable infrastructure.
+
+Finding a possible safety, portability, maintainability, cleanup,
+modernization or refactoring improvement does not by itself authorize an
+implementation change. A change is made when that change is part of the stated
+work, not merely because an opportunity was noticed while editing nearby code.
+
+Established behaviour is evaluated by layer. A Recipe or plugin contract that
+has been used for years has strong compatibility value. A framework internal
+implementation detail may be improved while preserving those contracts. A
+shipped plugin may be replaced or removed when its external service or
+interface is gone and the plugin can no longer perform real work.
+
+Safety mechanisms are means, not goals. A guard, validation layer, sandbox,
+permission model, retry layer or other defensive mechanism is justified by the
+risk it materially reduces and by whether that benefit outweighs added
+complexity, new failure modes and maintenance cost. This project is trusted
+single-user tooling; controls appropriate to an untrusted multi-user service
+are not added merely because they are generally considered safer.
+
+Long-running operational history is evidence, especially for Recipe semantics,
+plugin contracts and cron pipelines. It is not a reason to preserve a broken
+integration or to freeze internal implementation that can change without
+altering those contracts.
+
+A change that would introduce branching, loops, fan-out, transactional
+orchestration, multi-user state, a central plugin registry, domain knowledge in
+the framework or another responsibility that changes the composition model is
+an architecture change. It is not reached as a routine refactoring or as a
+convenient way to satisfy one plugin or one Recipe.
+
+### 1.5 The parts and the direction of dependency
 
 ```text
 bin/automatic
@@ -127,7 +193,7 @@ Dependency points one way and there is no edge back up:
   to two, the boundary is wrong and is corrected, rather than the code being
   written across it.
 
-### 1.5 The plugin boundary
+### 1.6 The plugin boundary
 
 - The framework's knowledge of a plugin is: its name, its file's location, its
   constructor's two arguments and its `run` method. It does not know a plugin's
@@ -142,7 +208,7 @@ Dependency points one way and there is no edge back up:
 - Shared plugin code that the framework does not use stays under `plugins/`, not
   in `lib/`. `plugins/store/database.rb` is where it is for that reason.
 
-### 1.6 Configuration
+### 1.7 Configuration
 
 - A Recipe is the whole of a job's configuration. There is no second file, no
   configuration directory, and no environment-variable settings.
@@ -161,7 +227,7 @@ Dependency points one way and there is no edge back up:
   change is a setting; a value that is part of what the plugin means stays in
   the code.
 
-### 1.7 Error handling
+### 1.8 Error handling
 
 - **The framework catches nothing from a plugin.** A plugin that raises ends the
   run, for the reason given in `REQUIREMENTS.md` section 12. Adding a blanket
@@ -181,8 +247,15 @@ Dependency points one way and there is no edge back up:
   and its backtrace is wanted.
 - **The library never calls `exit` or `abort`.** Exit status is decided at the
   process entry point, from the value `Automatic::CLI.run` returns.
+- The result of an operation, whether later work continues, and whether a
+  message is emitted are separate decisions. This does not change the
+  framework rule above: a plugin exception still ends the run, and plugin retry
+  behavior remains owned by the plugin.
+- A required condition whose absence makes correct completion impossible is a
+  failure, not a warning used to keep the run moving. A normal guard, no-op, or
+  inapplicable path is not a failure merely because it performs no work.
 
-### 1.8 Logging and output
+### 1.9 Logging and output
 
 - **A library file never calls `puts`, `print` or `warn`.** It logs, through
   `Automatic::Log`.
@@ -190,13 +263,18 @@ Dependency points one way and there is no edge back up:
   version, subcommand results — to standard output.
 - A plugin whose purpose is to write to the terminal holds its output object in
   an instance variable defaulting to `$stdout`, so that a test can substitute it.
-- `info` says what a step did, `warn` says what was skipped, `error` says what
-  failed. An error that was rescued is logged at `warn` or `error`, never at
-  `info`.
+- `info` records useful normal progress. `warn` is reserved for a degraded or
+  otherwise abnormal but recoverable condition the operator should know about;
+  a normal guard, no-op, or inapplicable path may be silent and is not a warning
+  merely because work was skipped. `error` says what failed. An error that was
+  rescued is logged at `warn` or `error`, never at `info`.
+- Do not emit a line merely to prove that a normal branch was taken, and do not
+  duplicate a failure message at multiple layers when one responsible layer
+  already reports it through the established interface.
 - No log line contains a credential. A plugin that logs its own settings
   wholesale is a defect.
 
-### 1.9 Filesystem access
+### 1.10 Filesystem access
 
 - The framework touches two roots: the installation directory and
   `~/.automatic`. Nothing else, and no absolute path elsewhere appears in the
@@ -211,7 +289,7 @@ Dependency points one way and there is no edge back up:
   extended, and nothing else acquires the ability to delete an operator's data.
 - A plugin writes only where its settings tell it to.
 
-### 1.10 Network access
+### 1.11 Network access
 
 - **The framework reaches nothing.** No update check, no telemetry, no
   phone-home. Every request is a plugin's, on a Recipe's instruction.
@@ -233,7 +311,7 @@ Dependency points one way and there is no edge back up:
 - Every request has a connect and a read timeout. An unattended run that hangs
   is a failure mode with no upper bound on its cost.
 
-### 1.11 Security and credentials
+### 1.12 Security and credentials
 
 - **A Recipe is trusted local configuration**, equivalent to a shell script the
   operator wrote. This is the trust boundary, it is stated in
@@ -251,7 +329,7 @@ Dependency points one way and there is no edge back up:
 - A change that touches authentication says in its `VERSIONS` entry what it
   changed.
 
-### 1.12 Judging a change
+### 1.13 Judging a change
 
 - Does it keep the Recipe format and the plugin contract, and if not, is that
   deliberate and recorded?
@@ -261,6 +339,15 @@ Dependency points one way and there is no edge back up:
 - Is it the smallest change that does the job?
 - Does a test say it works, and does the default suite still need no network?
 - Do the documents still match the code, in the same commit?
+- Which layer is changing: a core contract, framework implementation or a
+  replaceable plugin?
+- Is a framework change solving a framework problem, or absorbing
+  domain-specific behaviour that belongs in a plugin or an application?
+- Does a new dependency remain local to the plugin that needs it?
+- Does a proposed safety mechanism materially reduce a relevant risk without
+  imposing disproportionate complexity on trusted single-user tooling?
+- Does the change preserve the small linear composition model, and if not, has
+  an explicit architecture change actually been chosen?
 
 ---
 
@@ -306,7 +393,7 @@ appear in the order shown below. An executable uses this canonical form:
 #!/usr/bin/env ruby
 # -*- coding: utf-8 -*-
 # Name::        automatic
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
@@ -335,7 +422,7 @@ appear in the order shown below. An executable uses this canonical form:
 - A `Description::` line may be added below `Name` when the file's purpose is
   not obvious from its name. New plugins should have one.
 - The magic encoding comment is redundant on the supported Rubies. It is left in
-  place in existing files, because removing it from forty files is a diff with
+  place in existing files, because removing it across existing files is a diff with
   no benefit, and it is not required in a new file.
 
 Files do not carry a per-file version history. This repository versions at the
@@ -397,7 +484,7 @@ repository level only; see section 10.
 - **Converting the pipeline into some other representation is a `Publish`
   plugin's work, and the result stays inside the plugin.** It is serialized at
   the boundary, written to the destination, and never passed along the pipeline
-  or made known to the framework, which keeps Invariant 2 and section 1.5
+  or made known to the framework, which keeps Invariant 2 and section 1.6
   intact. Producing a portable document — one a person can read, ordinary tools
   can process and another program can be given, with no service behind it — is
   a destination like any other and belongs in that category.
@@ -423,7 +510,7 @@ Plugins outlive the services they talk to. The policy for what happens then:
   "does not work and never will"; a plugin in that position is removed.
 - **A dead integration is never faked into life.** No stub of a shut-down
   service, no mock that makes an integration look alive, no test that asserts
-  against a simulation. This is Invariant 7 and it has no exceptions. If a
+  against a simulation. This is Invariant 8 and it has no exceptions. If a
   plugin can only be made to look supported by simulating what it talks to,
   what it needs is deletion, not a double.
 - **Unsupported code is not kept for preservation.** Git history holds every
@@ -472,7 +559,7 @@ Plugins outlive the services they talk to. The policy for what happens then:
 - **RSpec**, under `spec/`, mirroring the source tree: `spec/lib/` for the
   framework and `spec/plugins/<category>/` for plugins.
 - **The default suite reaches no network and needs no credential.** This is
-  Invariant 6. A spec that would is not written; the integration Recipes under
+  Invariant 7. A spec that would is not written; the integration Recipes under
   `test/integration/` are where that belongs, and they are run by hand.
 - A framework spec covers the loader, the Recipe, the pipeline, the log and the
   CLI's exit statuses.
@@ -623,6 +710,12 @@ declared as runtime dependencies**. An operator who uses that plugin installs
 the gem. This is Invariant 4, and it is why installing this gem does not install
 an AWS SDK.
 
+Dependency minimization is not a repository-wide contest to use the fewest
+libraries. A plugin may be rich when its purpose requires it. The rule is that
+the cost stays with the plugin that needs it: a parser, database driver, SDK or
+other domain-specific dependency must not become a framework dependency merely
+because one plugin uses it.
+
 The permanent rules of the split:
 
 - **A core dependency is one the framework itself has.** A plugin's dependency
@@ -752,10 +845,19 @@ agree rather than asserting a literal.
   file is the record of released versions, not of the construction that precedes
   the first of them, and its first entry is written when that release is made.
 - **A series of changes made on one day is one version**, not several. Do not
-  split a day's work across version numbers.
-- **A version that actually existed is never merged into another**, even when it
-  shares a date with one. `14.10.0` and `14.10.1` were both released on
-  2014-10-23 and both stay.
+  split a day's work across version numbers. This rule has no exception:
+  separate commits, pull requests, independent features, bug fixes, security
+  fixes, compatibility changes, breaking changes, or release units do not
+  permit a second version number on the same calendar date. A same-date change
+  joins that day's single entry; independence decides bullet grouping only.
+- **If today's release has already been published, a correction may be
+  prepared but no second version, tag or package release may be published
+  until a later calendar date.** A published version is never overwritten,
+  reused or moved, and its correction is a later-dated version.
+- **Historical same-date versions remain recorded as historical facts.**
+  `14.10.0` and `14.10.1` were both released on 2014-10-23 and both stay in
+  `doc/VERSIONS`, but they violate the current one-version-per-day rule and
+  are not precedent for future releases.
 - A documentation-only change takes no entry unless its scale makes it worth one
   line saying so.
 - Git tags carry the release version, and are created only when a release is
@@ -779,21 +881,21 @@ the version history records what it amounts to.
 - Each entry opens with `vX.YY (YYYY-MM-DD)`, or `vX.YY (Release Date: TBD)`
   while unreleased, underlined with `-`, followed by one `-` bullet per change.
   Newest first. UTF-8.
-- **One coherent change is one bullet on one physical line.** The entry is a
-  list meant to be scanned, and a wrapped bullet costs it that: the eye no
-  longer finds the changes by counting lines, and a diff no longer shows one
-  added line per added change.
-- This is a deliberate exception to the wrapping the other plain text documents
-  follow. Do not rewrap `doc/VERSIONS` to 80 columns, and do not report a long
-  bullet there as a defect.
-- Aim for about 100 columns. A bullet carrying file names, module names, setting
-  names or plugin names may run to about 120, or past it when the names it needs
-  are that long. These figures prompt a reread, they are not a limit to enforce.
-  A bullet that is long because the change is long is correct.
-- **When a bullet runs long, abstract it; never break it across lines.** Drop
-  the implementation detail, the example, the reason and the secondary effect,
-  and state what the change is. Keep what a reader cannot reconstruct without
-  it: what changed, what is now observably different, what it does to
+- **One coherent change is one bullet, at most two physical lines.** A single
+  line at or under 80 columns is preferred whenever practical. This is an
+  explicit limit, not a prompt to reread: a bullet that runs past two lines,
+  or a single line that runs past 80 columns without necessity, must be
+  shortened. The entry is a list meant to be scanned, and a bullet that grows
+  past this limit costs it that: the eye no longer finds the changes by
+  counting lines, and a diff no longer shows a small, bounded edit.
+- A bullet carrying file names, module names, setting names or plugin names
+  may pass 80 columns on its one or two lines when those names cannot be
+  shortened without losing meaning. The two-line ceiling still applies.
+- **When a bullet runs long, abstract it first.** Drop the implementation
+  detail, the example, the reason and the secondary effect, and state what
+  the change is. Wrap onto the second line only when the abstracted bullet
+  still exceeds 80 columns. Keep what a reader cannot reconstruct without it:
+  what changed, what is now observably different, what it does to
   compatibility, what it does to security, and the identifiers someone would
   search for.
 - Changes serving one purpose are described together even when they touch
@@ -806,7 +908,10 @@ the version history records what it amounts to.
 - Order within a version serves the reader, not the commit history.
 - Released entries retain their substantive history even when their wording or
   level of detail predates these rules.
-- `doc/VERSIONS` carries these guidelines again at its foot.
+- `doc/VERSIONS` carries these guidelines again at its foot, and an entry
+  written into it follows the limit recorded there.
+- The first entry, at the lowest version `doc/VERSIONS` reaches, reads only
+  `Initial release.` and nothing else.
 
 ### 10.5 The historical record
 

data/doc/QUICKSTART.md

@@ -1,12 +1,15 @@
 # Quick Start
 
-This guide takes four public pages through one short Automatic Ruby pipeline and
-leaves what they publish as one Markdown document. It needs no account, no
-credential, no paid service and no database server.
-
-It does need two of the optional gems — because of the plugins the Recipe
-names, not because of the framework — and installing exactly those is a step of
-this guide rather than a footnote to it. Automatic Ruby installs what the
+This guide takes the public pages listed in its Recipe through one short
+Automatic Ruby pipeline and leaves what they publish as one Markdown document.
+It needs no account, no credential, no paid service and no database server.
+
+It does need optional gems because of the plugins the Recipe names, not because
+of the framework. The exact requirements are derived in
+[Install what the Recipe needs](#4-install-what-the-recipe-needs) from the
+canonical optional-dependency table in
+[`DEPLOYMENT.md`](DEPLOYMENT.md#optional-plugin-dependencies), rather than
+being maintained as a separate count here. Automatic Ruby installs what the
 framework needs and leaves a plugin's gems to the operator who uses that
 plugin, so "which plugins does this Recipe name, and what do they need" is a
 question every Recipe asks. Skipping it is the usual way a first run stops half
@@ -38,7 +41,7 @@ overwritten.
 ## 3. Write the Recipe
 
 A Recipe is one job: the plugins it runs, in order, with their settings. This
-one reads four public index pages as HTML and makes a feed of the articles each
+one reads the public index pages listed under `sites` as HTML and makes a feed of the articles each
 lists — which is what to do for a page whose feed you do not have — keeps a
 record of what it has already seen, and appends the rest to a Markdown
 document.
@@ -101,7 +104,7 @@ plugins:
       mode: append
 ```
 
-Three plugins, and each hands its result to the next:
+Each plugin hands its result to the next:
 
 - **`CustomFeedWeb`** fetches each page and makes a feed of the article links it
   lists. `include` is what tells an article from a navigation link, `interval`
@@ -117,7 +120,8 @@ Three plugins, and each hands its result to the next:
 
 Read the Recipe you have just written, plugin by plugin, and look each one up in
 the table of optional plugin dependencies in [`DEPLOYMENT.md`](DEPLOYMENT.md).
-That table gives, for these three:
+For the plugins in this Recipe, that table resolves the requirements as
+follows:
 
 - **`CustomFeedWeb`** — `nokogiri`, which it reads the pages with. In a
   checkout, the group `html`.
@@ -221,10 +225,10 @@ bundle exec bin/automatic scaffold
 bundle exec bin/automatic -c ~/.automatic/config/web2markdown.yml
 ```
 
-Step 4 is the step that differs, because a checkout resolves its gems through
-Bundler rather than through RubyGems. Each optional gem is in a Bundler group,
-and the Recipe's groups — `html` and `store`, from step 4 — are selected
-together and installed once:
+The "Install what the Recipe needs" step is the step that differs, because a
+checkout resolves its gems through Bundler rather than through RubyGems. Each
+optional gem is in a Bundler group, and the Recipe's groups — `html` and
+`store`, from that step — are selected together and installed once:
 
 ```sh
 bundle config set --local with "html store"
@@ -233,7 +237,7 @@ bundle install
 
 `gem install nokogiri` does **not** work here: the gem installs, and the
 checkout still reports it as missing, because it is not in the bundle. That
-difference, the commands that show what the bundle holds, and the same three
+difference, the commands that show what the bundle holds, and the same Recipe
 plugins taken step by step through choosing their groups are in
 [`DEPLOYMENT.md`](DEPLOYMENT.md) under "Working out what a Recipe needs, in a
 checkout".

data/doc/RELEASING.md

@@ -33,8 +33,9 @@ gem --version
 bundle --version
 ```
 
-The release Ruby need not reproduce the complete CI matrix locally. Required
-GitHub Actions checks must be green on Ruby 3.3, 3.4 and 4.0 before publication.
+The release Ruby need not reproduce the complete CI matrix locally. Required GitHub Actions checks must be green for every Ruby version in the
+current matrix of [`.github/workflows/ci.yml`](../.github/workflows/ci.yml)
+before publication.
 
 ## 2. Authentication and credentials
 
@@ -85,8 +86,12 @@ X.YY        release in year X, month YY
 X.YY.PATCH  correction to an earlier release in the same month
 ```
 
-Section 10 of `POLICY.md` is authoritative. A release updates these three
-places together in one release-metadata commit:
+`PATCH` may correct an earlier release in the same month, but never on the same
+calendar date as that release. A versioned unit has one version number per
+calendar date, without exception.
+
+Section 10 of `POLICY.md` is authoritative. A release updates these release-metadata sources together in one
+release-metadata commit:
 
 - `VERSION` contains the package version;
 - `lib/automatic/version.rb` defines `Automatic::VERSION` for the CLI;
@@ -207,7 +212,7 @@ Confirm that:
 - the name is `automatic` and the version equals `VERSION`;
 - the summary and homepage describe this project;
 - `source_code_uri` is the Automatic Ruby repository;
-- the required Ruby version is `>= 3.3.0`;
+- the required Ruby version matches `automatic.gemspec`;
 - licenses contain both `GPL-3.0-only` and `LGPL-3.0-only`;
 - the authors are correct;
 - runtime and development dependencies match `automatic.gemspec`, and the
@@ -273,7 +278,9 @@ git push origin "v$version"
 The tag identifies the source used to build the gem. Do not move or force-update
 a release tag after publication. If the tag is wrong before publication, stop
 and correct it openly. If publication has happened, preserve the source history
-and make the correction in a new commit and version.
+and prepare the correction in a new commit. Publish the correction under a new
+version only on a later calendar date; do not create or publish a second
+version on the same date.
 
 The repository has no established requirement for a GitHub Release separate
 from its Git tag. If maintainers create one, create it from the same immutable
@@ -337,16 +344,22 @@ Stop on an error and diagnose it; do not bypass RubyGems security controls.
 - **Version already exists:** do not attempt to overwrite it. Determine whether
   it was already published correctly; otherwise fix the source, increment the
   version according to `POLICY.md`, rebuild and repeat every verification step.
+  The incremented version is published on a later calendar date than the
+  existing one, never on the same date.
 - **Malformed metadata or rejected gem:** fix the gemspec and release metadata,
   increment the version if that version reached RubyGems.org, then rebuild,
   inspect and test the new archive. Do not use `--force` to hide validation.
+  A version that reached RubyGems.org counts as that date's release, so the
+  incremented version waits for a later calendar date.
 
 `gem yank automatic -v X.Y.Z` removes a published version from normal index use.
 Yank only for an exceptional serious mispublication, such as exposed secrets or
 a release that must not be installed. It is not the normal correction process,
 does not make the version reusable, and does not erase every downloaded copy.
 The normal response is to correct the problem, bump the version and publish a
-new release. Rotate any exposed secret immediately as well as yanking.
+new release on a later calendar date. Yanking does not permit a second version
+on the date of the yanked release. Rotate any exposed secret immediately as
+well as yanking.
 
 Publication state and Git history are separate. Never rewrite a published
 commit, force-push the release branch, or move a release tag to simulate a

data/doc/REQUIREMENTS.md

@@ -50,6 +50,16 @@ to a plugin, and plugins are expected to come and go.
 
 - **Not an application.** It has no behaviour of its own. With no Recipe it does
   nothing, and every useful thing it does is a plugin's doing.
+- **Not host infrastructure.** It is not a common system baseline installed to
+  provide the same foundational behaviour to every host. It is operator tooling
+  for assembling jobs, and the jobs, dependencies and effects are chosen by each
+  Recipe.
+- **Not a substitute for a purpose-built application.** The fact that many jobs
+  can be expressed as plugin pipelines does not make every problem a framework
+  problem. A concrete purpose that needs branching, complex shared state,
+  transactions, interactive behaviour, multi-user permissions or tightly
+  coupled domain logic belongs in an application rather than in a larger
+  Automatic Ruby core.
 - **Not a daemon or a scheduler.** One invocation runs one Recipe once and
   exits. Repetition is `cron`'s job, and periodic running is deliberately left
   outside; see section 15.
@@ -88,8 +98,12 @@ several plugins shell out to Unix commands.
 
 ## 7. The two public interfaces
 
-Two things in this repository are interfaces that people outside it depend on,
-and they are treated accordingly.
+Two public contracts define how external Recipes and plugins compose with the
+framework, and they receive the strongest compatibility protection in this
+project. That protection is deliberately narrower than treating every
+implementation detail or every shipped plugin as permanent. The Recipe format
+and the plugin contract are stable composition contracts; framework internals
+may improve within those contracts, and plugins remain replaceable components.
 
 ### 7.1 The Recipe
 
@@ -132,6 +146,12 @@ that acquires something which is not a feed — a row of a TSV file, an API
 response, a weather report — converts it into this shape and the rest of the
 pipeline is unaffected.
 
+The single pipeline shape is part of the framework's composition model. It is
+protected for the same reason as the plugin contract: changing it would not
+merely refactor an implementation, but would change what existing plugins can
+compose with. Composability here is an architectural invariant, not an
+optimization preference.
+
 This is the framework's one substantive constraint on plugins, and it is what
 makes them compose. Three consequences are requirements:
 
@@ -295,6 +315,13 @@ The requirements on failure:
 - **A Recipe naming a plugin that does not exist fails immediately**, before any
   plugin runs, with a message naming the plugin.
 
+These execution rules describe the straight-line composition model Automatic
+Ruby supports. They are not an incomplete version of a richer workflow engine.
+A use case that fundamentally requires branching, resume checkpoints,
+transactional coordination or cross-step state ownership should not cause the
+framework to grow those features by default; it should first be judged as a
+candidate for a purpose-built application.
+
 ## 13. The user directory
 
 `~/.automatic` is where an installation's own material lives, so that it
@@ -464,8 +491,9 @@ Two statements are made here, and they are deliberately different.
   dependency the project needs moves it, or when the version drops out of the
   distributions the project is used on.
 
-**The continuously validated versions** are **3.3, 3.4 and 4.0** — the ends of
-the range and the release in the middle.
+**The continuously validated versions** are the versions in the matrix of
+[`.github/workflows/ci.yml`](../.github/workflows/ci.yml). That workflow is
+authoritative for the set checked on every commit.
 
 - CI runs representative versions rather than every intermediate release. The
   cost of a matrix entry is paid on every commit, and a third entry between two
@@ -476,9 +504,10 @@ the range and the release in the middle.
 - Adding a released Ruby to the matrix is how support for it becomes continuous,
   and is a small change.
 
-One statement of the supported range lives in the gemspec, one statement of the
-validated set lives in the CI matrix, and the README and the documents agree
-with both.
+`automatic.gemspec` is authoritative for the supported Ruby requirement, and
+`.github/workflows/ci.yml` is authoritative for the continuously validated
+set. User-facing documents state the supported range where readers need it
+and refer to the matrix rather than duplicating its current membership.
 
 ## 21. Portability
 
@@ -507,9 +536,10 @@ with both.
 
 ## 23. Simplicity
 
-The framework is under seven hundred lines of Ruby and is meant to stay that
-size. It is the small fixed part that plugins are written against, and it earns
-its keep by not changing.
+The framework is meant to remain the small fixed part that plugins are written
+against. Its responsibility boundary, rather than a duplicated current line
+count, is the maintained constraint; see
+[`BASIC_DESIGN.md`](BASIC_DESIGN.md).
 
 - A capability that can live in a plugin lives in a plugin.
 - A framework feature that only one plugin would use does not belong to the