@sous-io/sous 0.2.16 → 0.2.18

package/docs/markdown/commands.md

@@ -17,7 +17,8 @@ Every command that works on a project takes these four. `SOUS_CONFIG`, `SOUS_DIR
 a flag beats its variable, and both beat walk-up discovery. See [Discovery and overrides](config-discovery.md).
 
 ?> `repo init`, `repo release` and `repo submit` take none of these. They run inside a recipe repository, which
-has no `.sous/` directory to discover. All three still take `--non-interactive`.
+has no `.sous/` directory to discover. All three still take `--non-interactive`. `repo submit` may also be run
+from a project, which it finds by walking up from the working directory.
 
 ## Flags that answer questions
 
@@ -230,9 +231,22 @@ Example: `sous repo link sous-recipes ~/Projects/sous-recipes`, or `sous repo li
 --generate-branch --latest --yes`
 
 ### `sous repo unlink REPO`
-Stops reading a repository from a working copy and goes back to published versions; `REPO` is the short name as
-it appears in `sous.links.json` (see [File formats](repositories-file-formats.md)). `--global` removes the
-machine-wide link, not this project's; `--dry-run` prints what changes. Example: `sous repo unlink sous-recipes`
+Stops reading a repository from a working copy, goes back to the versions the lockfile pins, and rebuilds the
+project; `REPO` is the short name as it appears in `sous.links.json` (see
+[File formats](repositories-file-formats.md)). On its own it also fetches the repository's index, with a short
+timeout, and reports any newer published version the ranges allow, without moving anything; when the index
+cannot be fetched in time it says it could not check. The checkout stays where it is unless `--remove` is passed.
+Takes `--dry-run`, `--no-build`, `--answer` and `--answers-file`.
+
+- `--global`: remove the machine-wide link, not this project's.
+- `--update`: move this repository's pins to the newest versions their ranges allow before rebuilding. It runs
+  the same code as `sous subscription update REPO`.
+- `--remove`: delete the checkout as well, but only one sous cloned itself; a checkout linked by path is refused
+  with an error. Uncommitted changes, commits no remote has and stashes are listed first and asked about.
+- `-y, --yes`: answer every question this command asks: deleting a checkout that holds work, the update plan,
+  and the trust question for a repository a newer version needs (also `--force`, `--trust`).
+
+Example: `sous repo unlink sous-recipes --update`
 
 ### `sous repo init [DIRECTORY]`
 Creates a new recipe repository in a directory, defaulting to the current one; `--dry-run` prints the files it
@@ -254,17 +268,32 @@ and `git config user.email`), because it commits and cuts annotated tags. Takes
 - `--no-bump`: raise nothing; a changed recipe that was never raised is then an error.
 - `--include-unchanged`: release every recipe in scope, changed or not.
 - `--tag`, `--push`: tag even on a non-default branch, and push the commit and this run's tags.
-- `--check`: only validate. It fails on a problem the release would refuse, and reports, without failing, how
-  merging would rewrite the committed index.
+- `--check`: only validate. It fails on a problem the release would refuse, and on a change to a recipe that
+  takes no proposals (see [`submissions`](repositories-file-formats.md#the-submissions-block)), and reports,
+  without failing, how merging would rewrite the committed index.
 - `--ci`: the merge preset. Never bump, never ask, and fail on anything unbumped. It still needs `--yes` to
   accept the plan it prints, so a merge job runs `sous repo release --ci --yes --push`.
 
 Example: `sous repo release --recipe workflow/task-files --bump minor --push`
 
-### `sous repo submit`
-Proposes this repository's committed changes to its maintainers. `--title <text>` defaults to the last commit's
-subject and `--body <text>` to a summary sous writes; `--draft` opens the proposal as a draft, and `--dry-run`
-prints the plan without sending anything. Example: `sous repo submit --title "Add a linting recipe" --draft`
+### `sous repo submit [REPO]`
+Proposes a recipe repository's changes to its maintainers, and follows the proposal through: it opens one,
+updates it when there is more to send, reports where it stands, and starts the next one once it was merged. Run
+inside a recipe repository it works there; run inside a project, `REPO` names a linked repository and the
+submission runs in its checkout (with no `REPO`, the only linked repository is used, and several are a
+question). Takes `-y, --yes` and `--dry-run`.
+
+- `--title <text>`, `--body <text>`: the proposal's title and description. Both are required for a new
+  proposal, and asked for at a terminal when missing; on an open proposal they are optional and replace its own.
+  The body is followed by a changelog sous generates.
+- `--branch <name>`: work with this branch instead of the one checked out. A branch that does not exist is
+  created from the current commit.
+- `--status`: only report where the branch's proposal stands; nothing is checked, written or sent.
+- `--commit`: commit uncommitted changes for you, after listing them and asking once, with the title, the
+  description and the changelog as the message.
+- `--draft`: open a new proposal as a draft.
+
+Example: `sous repo submit --title "Add a linting recipe" --body "Adds lint rules for shell scripts." --draft`
 
 ## subscription
 
@@ -290,6 +319,20 @@ Example: `sous subscription add workflow/task-files@^1.2.0 --answer apiUrl=https
 Removes a subscription and everything only it brought in, then rebuilds so those files are gone. Also spelled
 `sous unsubscribe`. Takes `--dry-run` and `--no-build`. Example: `sous subscription remove workflow/task-files`
 
+### `sous subscription update [REF]`
+Moves the lockfile's pins to the newest published versions their ranges allow, then rebuilds the project. With
+no `REF` it covers every subscription; a `REF` naming a repository, a namespace or a recipe narrows it, and
+everything outside it stays where it is pinned. It fetches every trusted repository's index first, never widens
+a range, moves dependencies with the closure, and changes only the lockfile, never the subscriptions. It prints
+the plan and asks once; with nothing to update it says so and asks nothing. See
+[Moving to newer versions](repositories-consuming.md#moving-to-newer-versions). Takes `--no-build`, `--answer`
+and `--answers-file`, and `--dry-run`, which fetches the indexes but downloads no recipe and writes nothing.
+
+- `-y, --yes`: accept the plan, and trust any repository a newer version needs (also `--force`, `--trust`).
+- `--accept-first`: when `REF` matches several things, take the first one listed.
+
+Example: `sous subscription update workflow/task-files`
+
 ### `sous subscription list`
 Lists the subscriptions this project declares, switched-off ones included, with the range each resolves within,
 the versions the lockfile pins, the latest version each of those recipes has published, where it came from and
@@ -301,7 +344,8 @@ only the subscriptions that have pinned something. Example: `sous subscription l
 
 `namespace` reads the cached indexes and the lockfile, so it works offline. A trusted repository whose index has
 never been fetched is named at the end of a listing, not left out. Both commands take the
-[browsing flags](#flags-that-browse); with `--installed` the recipe count is the number installed.
+[browsing flags](#flags-that-browse); with `--installed` the recipe count is the number installed. The core version this installation of sous
+ships is listed even while the cached index does not publish it yet.
 
 ### `sous namespace list`
 Lists every namespace the trusted repositories publish, how many recipes each holds, and how much of it this
@@ -338,8 +382,10 @@ Prints what `.sous/sous.lock.json` pins: the recipe, the version, the repository
 ### `sous lock rebuild`
 Recomputes the whole lockfile from the subscriptions the config declares and the cached indexes, starting from
 empty, so an entry nothing holds any more is dropped rather than carried through: the repair for a file that
-drifted through a hand edit or a bad merge. It asks nothing, grants no trust and downloads nothing. Takes
-`--dry-run`. Example: `sous lock rebuild --dry-run`
+drifted through a hand edit or a bad merge. It asks nothing, grants no trust and downloads nothing. The core
+version this installation of sous ships resolves even when the cached index has not published it yet, exactly
+as it does in a build. To move pins to versions published since the last fetch, use `sous subscription update`.
+Takes `--dry-run`. Example: `sous lock rebuild --dry-run`
 
 ## vars
 

package/docs/markdown/repositories-authoring.md

@@ -4,8 +4,9 @@ The guide to publishing recipes of your own: creating a repository, writing a re
 needs, cutting a release, editing a published repository in place, and proposing a change to somebody else's.
 [Repository file formats](repositories-file-formats.md) holds the schemas; this page is the workflow.
 
-?> A recipe repository is not a sous project. It has no `.sous/` directory, and `sous repo init`, `sous repo
-release` and `sous repo submit` do not look for one. Run them from inside the repository itself.
+?> A recipe repository is not a sous project. It has no `.sous/` directory, and `sous repo init` and `sous repo
+release` do not look for one. Run them from inside the repository itself. `sous repo submit` runs there too, and
+may also be run from a project that links the repository.
 
 ## Create a repository
 
@@ -196,8 +197,9 @@ third case is what a merge looks like to continuous integration: the bump is don
 `--namespace <ns>` and `--recipe <ns/name>` narrow the run and both repeat; `--bump <level>` is `patch` (the
 default), `minor`, `major` or `prerelease`; `--no-bump` raises nothing; `--include-unchanged` releases every
 recipe in scope, changed or not; `--check` only reads, validating, failing on any problem the release would
-refuse, and reporting how merging would rewrite the committed index without failing on it, since that index is
-the release's output; and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
+refuse and on a change to a recipe whose [`submissions`](repositories-file-formats.md#the-submissions-block)
+block says it takes no proposals, and reporting how merging would rewrite the committed index without failing
+on it, since that index is the release's output; and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
 this command takes, `--tag`, `--push` and `--non-interactive` among them, is in the
 [command reference](commands.md#sous-repo-release).
 
@@ -235,7 +237,8 @@ missing from the index is rebuilt from it whenever the index is regenerated, whi
 publishes something. A bump edits the manifest in place, so comments, field order and layout survive; a folded
 block of YAML prose may be re-wrapped and the space before a trailing comment collapsed to one.
 
-!> A release commits the version bumps and the index, and nothing else. It refuses to run while anything else is
+!> A release commits the version bumps and the index, and nothing else; the only other commit sous ever makes
+for you is `sous repo submit --commit`. It refuses to run while anything else is
 uncommitted, because a tag names one commit and the index records what each recipe folder holds right now. It also
 refuses when git does not know who is committing: set `git config user.name` and `git config user.email` first, or
 give that identity to the account a continuous integration job runs as (the scaffolded workflow already does).
@@ -286,8 +289,29 @@ and freshness checks no longer apply to it. Builds say so every time.
 Run 'sous repo unlink my-recipes' to go back to published versions.
 ```
 
-`sous repo unlink` removes the map entry and nothing else: the checkout stays where it is, and its path is
-printed so you can delete it. Unlinking a name linked in the other scope says which scope holds it.
+### Unlink, and pick up your release
+
+Linking never touches the lockfile, so `sous repo unlink my-recipes` goes back to exactly the versions pinned
+before the link, and rebuilds the project so its outputs match them. It also fetches the repository's index,
+with a short timeout, and says whether a newer version the ranges allow has been published since; it moves
+nothing, and when the index cannot be fetched in time it says it could not check. Unlinking a name linked in
+the other scope says which scope holds it.
+
+Once your change is released, one of these moves the project onto it:
+
+```bash
+sous repo unlink my-recipes --update       # unlink, move this repository's pins, then rebuild
+sous subscription update my-recipes        # the same move, when nothing is linked any more
+```
+
+`--update` runs exactly the code `sous subscription update my-recipes` runs: every pin the repository supplies
+moves to the newest version its range allows, after one plan and one question. See
+[Moving to newer versions](repositories-consuming.md#moving-to-newer-versions).
+
+The checkout stays where it is unless you pass `--remove`, because `sous repo submit` uses a leftover checkout to
+revise a proposal that is still open. `--remove` deletes it only when sous cloned it; a checkout you linked by
+path is yours, and sous refuses with an error. Before deleting, sous lists anything in the checkout that exists
+nowhere else (uncommitted changes, commits no remote has, and stashes) and asks; `--yes` answers ahead.
 
 ### How a checkout compares with upstream
 
@@ -344,22 +368,60 @@ changing its branch says it affects all of them.
 
 ## Contribute to someone else's repository
 
-`sous repo submit` proposes your committed changes to a repository's maintainers; it never publishes and never
-writes to a repository directly. It takes `--title`, `--body`, `--draft` and `--dry-run`, and runs three stages,
-printing each step:
+`sous repo submit` proposes a change to a repository's maintainers and follows it through; it never publishes
+and never writes to a repository directly. Run it inside the recipe repository you changed, or from a project
+that links it: `sous repo submit sous-recipes` runs in the linked checkout, and with no argument the project's
+only linked repository is used (several are a question). A repository you have since unlinked is still
+submitted from the checkout sous cloned for it, with a note saying so; with no checkout at all there is no
+working copy to propose from, and `submit` says so.
+
+It prints each step as it runs them:
 
 1. **Preflight.** An `origin` remote exists, sous recognizes its provider, that provider's command line tool
-   (`gh` or `glab`) is installed and signed in, and everything is committed.
+   (`gh` or `glab`) is installed and signed in, and everything is committed. `--commit` lifts that last rule:
+   sous lists what is uncommitted, asks once (`--yes` answers), checks git knows who is committing before
+   writing anything, and commits it all with the proposal's title, description and changelog as the message.
 2. **Validation.** The repository validates, and your change leaves `sous.index.json` as it found it, so a
    proposal never fails the maintainer's own checks and wastes their review. The index is written by the
    repository's own release after a merge; whether it agrees with the release tags is checked there, by
    `sous repo release --check` on a full clone, not by `submit`. That is what lets `submit` run from the shallow
    checkout `sous repo link` makes, which holds almost none of the tags. The comparison is made against the
    copy of the default branch your checkout holds (`origin/main`, for example); when it holds none, `submit`
-   says the check was skipped.
+   says the check was skipped. A change that touches a recipe whose
+   [`submissions`](repositories-file-formats.md#the-submissions-block) block says it takes no proposals is
+   warned about, with where to send it instead, and proposed only if you carry on.
 3. **Delegation.** Sous asks the provider whether you can push to the repository itself, forks it onto your
    account when you cannot, pushes the branch, and asks the provider to open the proposal. A change sitting on
-   the default branch is moved to `sous/submit-<YYYYMMDD>-<HHMM>`.
+   the default branch is moved to `sous/submit-<YYYYMMDD>-<HHMM>`, or to the branch `--branch` names.
+
+**A title and a description are yours to write.** A new proposal needs both: pass `--title` and `--body`, or
+answer the two questions at a terminal (Tab opens your editor for a longer description). Sous never borrows a
+commit message. The body is your description followed by a changelog sous generates by comparing the manifests
+your change carries with the default branch:
+
+- recipes added, and recipes retired (a renamed recipe shows as one of each);
+- version changes;
+- recipes whose files changed without a version raise, which merging will release as the next patch;
+- namespaces added or removed;
+- variables added, removed or changed, with a warning that removing a variable or tightening its validation is
+  usually a major change.
+
+The changelog explains; it never refuses. Only what the repository's own checks would reject stops a submission.
+
+**One command for the proposal's whole life.** Every run looks up the proposal for the current branch (or the
+one `--branch` names), by the fork's owner as well as the branch when you work through a fork, and then:
+
+| The branch's proposal | What `submit` does |
+|-----------------------|--------------------|
+| none | Opens one |
+| open, with new commits | Pushes them, which updates it; a given `--title` or `--body` replaces its own |
+| open, with nothing new | Reports where it stands: review, checks, whether it can merge |
+| merged | Says so, then continues on a new branch: you name one, sous generates one, or you cancel. `--yes` generates one |
+| closed without merging | Says so, and opens a fresh one for the branch |
+
+When the branch on the remote holds commits yours lacks (a maintainer pushed to it), git refuses the push and
+`submit` passes git's own explanation through and stops. It never forces a push. `--status` only reports, and
+`--dry-run` works everything out and writes and sends nothing.
 
 Each step is the provider's own business, and what each one can do depends on the host; see
 [Providers](repositories-providers.md#proposing-a-change). Sous sequences the steps and reports what came back. A

package/docs/markdown/repositories-consuming.md

@@ -220,7 +220,48 @@ build` instead. The `Latest version` column beside it is read from the cache, or
 `sous repo list` shows each trusted repository with its provider, origin, whether it is linked, its
 recipe count and its URL; `--verbose` adds a `Namespaces:` line under each row. `sous lock show`
 prints the other half: every version your lockfile pins, where it came from and who holds it. When
-that file has drifted, `sous lock rebuild` recomputes it from your subscriptions.
+that file has drifted, `sous lock rebuild` recomputes it from your subscriptions and the cached
+indexes, fetching nothing.
+
+## Moving to newer versions
+
+A build holds the versions the lockfile pins, so a newer release reaches the project only when
+something moves the pin. `sous subscription update` is that step:
+
+```term
+$ sous subscription update workflow/qa-variables
+  Updating the recipe 'qa-recipes:workflow/qa-variables' changes the lockfile:
+
+    • Adding workflow/qa-helper version 1.0.0
+    • Updating workflow/qa-variables from version 0.1.0 to version 0.2.0
+
+  Update the lockfile? (y/N)
+```
+
+It fetches every trusted repository's index first, so a version published a minute ago counts.
+With no reference it covers every subscription; a reference names a repository, a namespace or a
+recipe, at any level of qualification, and everything outside it stays exactly where it is pinned.
+What it will and will not do:
+
+- A pin moves only within the range its subscription declares, or the range the recipe depending
+  on it declares; a range is never widened. Prereleases count only for a subscription that opted
+  into them.
+- Dependencies move with the closure: a dependency a newer version adds is pinned, and one it
+  dropped leaves the lockfile unless something else still holds it.
+- Only the lockfile changes. Your subscriptions stay exactly as they are written.
+- It prints the plan and asks once; `--yes` accepts it, and a run with no terminal and no `--yes`
+  fails naming the flag. With nothing to update it says so and asks nothing.
+- A repository a newer version needs that the project does not trust goes through the usual trust
+  question, and new questions the newer versions ask are asked the way subscribing asks them.
+- A repository whose index cannot be fetched is skipped and named, and its pins stay put.
+- A linked repository's pins move too, and the plan notes that builds keep reading the checkout
+  until it is unlinked.
+- The built-in `core` subscription never moves: its range is exactly the running sous version, so
+  upgrading sous is what moves it.
+
+It rebuilds the project afterwards. `--dry-run` fetches the indexes and prints the plan, and
+downloads no recipe and writes nothing, so the dependencies and questions of a version this machine
+does not hold yet are named rather than listed. `--no-build` skips the rebuild.
 
 ## Remove a subscription
 
@@ -290,7 +331,8 @@ lapsed (`store.freshnessSeconds`, five minutes by default), or when a command fo
 check never breaks a build, because the cached index is used instead. Always-pull changes what
 happens after that check, not how often it happens: a repository or subscription marked
 `alwaysPull` takes a newer in-range version rather than the locked one; set it with
-`--always-pull`, or on either entry in the config.
+`--always-pull`, or on either entry in the config. Without it, `sous subscription update` is how a
+pin moves; see [Moving to newer versions](#moving-to-newer-versions).
 
 Every other repository the lockfile pins from is checked on the same window, only to tell you what
 is newer. A build lists each recipe with a newer version inside the range declared for it, beside

package/docs/markdown/repositories-file-formats.md

@@ -54,6 +54,7 @@ recipes:                            # every recipe folder, relative to the repos
 | `description`, `contribute` | no | A summary for anyone reading the repository, and where to send a contribution when a provider cannot support `sous repo submit` |
 | `namespaces` | yes | Keyed by namespace name; each entry takes an optional `description` |
 | `recipes` | yes | Relative paths, each holding a recipe manifest; a path listed twice is an error |
+| `submissions` | no | Whether the repository's recipes take proposed changes; see [The submissions block](#the-submissions-block) |
 
 ## `sous.recipe.yaml`: the recipe manifest
 
@@ -77,11 +78,30 @@ contents:                           # what a subscriber actually receives
 | `description` | no | Copied into the index at release time; shown by `sous recipe list` and `sous repo search` |
 | `depends`, `subscribes` | no | Build dependencies and co-subscriptions; within either list, no entry may repeat |
 | `contents`, `variables` | no | Contents default to an empty list, which is what a curated bundle publishes; a duplicated variable name, or two definitions claiming one `env`, is an error |
+| `submissions` | no | Whether this recipe takes proposed changes, winning over the repository's block; see [The submissions block](#the-submissions-block) |
 
 `contents[].kind` is `skills`, `memories`, `prompts` or `config`. The first three are written to the
 destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land); `config` entries become config
 layers instead. `include` needs at least one glob, and both lists are recipe-relative.
 
+### The submissions block
+
+Both manifests accept a `submissions` block. On `sous.repo.yaml` it covers every recipe in the repository; on
+`sous.recipe.yaml` it covers that recipe, and wins over the repository's.
+
+```yaml
+submissions:
+  allowed: false                    # defaults to true
+  instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+```
+
+It exists for a recipe whose files are copied in from somewhere else: an edit merged into the copy is
+overwritten by the next copy, and a version it tagged can collide with the one the real source publishes.
+`sous repo submit` warns before proposing a change that touches such a recipe, prints the `instead` text, and
+proposes it if the contributor carries on. `sous repo release --check` fails a pull request that changes one,
+because a pull request can be opened without `submit`, and the check is the one gate every change passes. A
+release itself is never restricted, so whatever publishes the recipe still releases it.
+
 ### Dependencies named by location
 
 `depends` and `subscribes` share one grammar in two spellings: `workflow/qa-helper` is a sibling in this
@@ -232,7 +252,8 @@ freshness checks; entries are keyed by the repository's configured short name.
 ```
 
 `path` is absolute; `origin` is `clone` when sous cloned the working copy itself and `path` when it was
-pointed at an existing checkout, and unlinking removes the entry while leaving either in place. Both the
+pointed at an existing checkout. Unlinking removes the entry and leaves the checkout in place, unless
+`sous repo unlink --remove` is asked to delete one sous cloned; it never deletes a `path` checkout. Both the
 project's `.sous/sous.links.json` and `$SOUS_HOME/sous.links.json` are read, and the project's entries win.
 
 ## Configuration keys

package/docs/markdown/repositories-providers.md

@@ -21,8 +21,12 @@ Nothing there clones a whole repository. A provider that can also carry a contri
 the **write path**: report whether its command line tool is installed and signed in, say whether
 you may push to the repository itself, fork it onto your account, and open the proposal.
 
-Each provider declares which of the two features, `fetch` and `submit`, it genuinely answers, and
-sous consults that declaration rather than a provider's name. Asking for something outside a
+A provider may also answer the **proposals** path, which is what lets a submission follow a proposal
+after it is opened: find the proposal a branch was pushed for, report where it stands, and replace its
+title or body.
+
+Each provider declares which of the three features, `fetch`, `submit` and `proposals`, it genuinely
+answers, and sous consults that declaration rather than a provider's name. Asking for something outside a
 provider's features is refused with a sentence naming it and what it cannot do, never a crash.
 
 ## How a URL is matched
@@ -184,11 +188,15 @@ finds the index but cannot clone has only the second half missing.
 your repository, then hands the host-specific mechanics to the provider that owns its `origin`
 remote. Providers differ, and sous says so rather than pretending otherwise:
 
-| Provider | Tool | Push permission | Forking | Proposal |
-|---|---|---|---|---|
-| `github` | `gh` | read from GitHub, so a contributor without it is forked automatically | `gh repo fork`, with a `fork` remote added for you | pull request |
-| `gitlab` | `glab` | sous cannot tell, so it pushes to `origin` and says so | not done for you | merge request |
-| `local` | none | not applicable | not applicable | not applicable |
+| Provider | Tool | Push permission | Forking | Proposal | Following it up |
+|---|---|---|---|---|---|
+| `github` | `gh` | read from GitHub, so a contributor without it is forked automatically | `gh repo fork`, with a `fork` remote added for you | pull request | `gh pr list`, `gh pr view` and `gh pr edit`, matching a fork's pull request by its owner |
+| `gitlab` | `glab` | sous cannot tell, so it pushes to `origin` and says so | not done for you | merge request | not done: every run opens a merge request, and `--status` is refused |
+| `local` | none | not applicable | not applicable | not applicable | not applicable |
+
+**GitLab cannot follow a proposal up yet.** It does not declare `proposals`, so a submission cannot
+look for a merge request that is already open; it says so, pushes, and opens one. When the branch
+already has one, the push updates it and GitLab may refuse the second.
 
 **GitLab reports "cannot tell" rather than guessing.** Sous has no cheap, reliable way to ask
 whether you may push, and a wrong guess would send you down a fork path this provider cannot
@@ -297,14 +305,16 @@ subclass overrides it. Each member is documented where it lives, in
 The subclass supplies the rest:
 
 - `id`, the identifier a repository entry and a locator scheme use;
-- `features`, the ones it genuinely answers (`fetch`, and `submit` only if all four write calls
-  are real);
+- `features`, the ones it genuinely answers (`fetch`; `submit` only if all four write calls are
+  real; `proposals` only if `findProposal`, `proposalStatus` and `updateProposal` are);
 - `matches(url)` and `canonicalize(url)`, the URL half;
 - `fetchIndex(repo, options)` and `fetchRecipeTree(repo, recipePath, tag, destDir, options)`, the
   read half;
 - `cli` and `proposalNoun` when it submits, so messages can name the tool and call a proposal
   what the host calls it;
-- overrides of the four write-path calls when it submits.
+- overrides of the four write-path calls when it submits, and of the three proposals calls when
+  it can follow a proposal up. Each answers with plain data (a proposal's id, address, state,
+  title, review and check counts), never with a host's own vocabulary.
 
 Every call takes an options object carrying the testing seams (`cwd`, `env`, `fetchImpl`, `run`),
 which is why no provider reaches for `spawn` or the global `fetch` directly and no test in this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.16
+version: 0.2.18
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous
@@ -19,6 +19,13 @@ description: >-
   debugged, the .tpl. template convention and LiquidJS syntax, what an agent
   skill is, and how to create one.
 
+# The copy in sous-io/sous-recipes is overwritten by every sous release, so a
+# change proposed there would be lost, and a version it tagged would collide
+# with the one the release publishes.
+submissions:
+  allowed: false
+  instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+
 contents:
   - kind: skills
     include:

package/src/commands/repo/release.ts

@@ -11,6 +11,7 @@ import {
   anythingToCommit,
   buildIndex,
   buildReleasePlan,
+  checkSubmissions,
   bumpRecipeVersion,
   commitPaths,
   createAnnotatedTag,
@@ -391,6 +392,46 @@ export default class RepoRelease extends Command {
       log("  records for every version it publishes.");
     }
     reportPending(result, "These versions have no tag yet; they publish when this merges:");
+
+    // A pull request can be opened without `sous repo submit`, so this check is
+    // the one gate every change passes. The release itself is not restricted:
+    // whatever publishes such a recipe still releases it.
+    section("Checking the recipes that take no proposals");
+    const submissions = await checkSubmissions(validation);
+    if (submissions.refusing.length > 0) {
+      const problems: ValidationProblem[] = submissions.refusing.map((recipe) => ({
+        level: "error",
+        where: recipe.path,
+        message:
+          `this change touches '${recipe.key}', which does not take proposed changes ` +
+          `(${recipe.declaredBy === "recipe" ? "its own manifest" : "the repository manifest"} ` +
+          `says so). Merging it would break whatever publishes the recipe.` +
+          (recipe.instead === undefined ? "" : ` Instead: ${recipe.instead}`),
+      }));
+      reportProblems(problems);
+      displayErrorBlock(
+        `This change cannot be merged: it touches ` +
+          `${describeCount(problems.length, "recipe")} that ${problems.length === 1 ? "does" : "do"} ` +
+          `not take proposed changes, listed above.\n` +
+          `  Take those edits out of the change, and send them where each recipe asks.`
+      );
+      return this.exit(1);
+    }
+    if (submissions.comparedWith.kind === "branch") {
+      log(
+        `  Compared with the branch '${submissions.comparedWith.branch}': this change touches no ` +
+          `recipe that declines proposals.`
+      );
+    } else if (submissions.comparedWith.kind === "tags") {
+      log("  Compared with each recipe's last release tag: nothing that declines proposals changed.");
+    } else if (submissions.comparedWith.kind === "none declined") {
+      log("  No recipe in this repository declines proposed changes.");
+    } else {
+      note(
+        "This checkout holds neither a copy of the default branch nor a release tag of any " +
+          "recipe that declines proposed changes, so there was nothing to compare with."
+      );
+    }
     footer();
   }