@sous-io/sous 0.2.16 → 0.2.17

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
 
@@ -254,17 +255,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
 

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).
@@ -344,22 +347,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-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

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.17",
   "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.17
 
 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();
   }