@sous-io/sous 1.0.13 → 1.0.14

package/docs/markdown/_sidebar.md

@@ -52,3 +52,4 @@
   - [0020: Config expressions](adrs/0020-config-expressions.md)
   - [0021: Reporting as levels and styles](adrs/0021-reporting-levels-and-styles.md)
   - [0022: Intents return outputs](adrs/0022-intents-return-outputs.md)
+  - [0023: The project's lockfile is the only lock](adrs/0023-the-project-lockfile-is-the-only-lock.md)

package/docs/markdown/repositories-authoring.md

@@ -132,7 +132,7 @@ A subscriber is offered the missing plugin when they subscribe; see
 ## Declare the variables a recipe needs
 
 A recipe that needs a value from the project asks through a **definition**: a published specification, never a
-value. Sous asks the question only when a subscribed recipe needs the variable and no valid answer is in scope.
+value. Sous asks the question only when a recipe the project holds needs the variable and no valid answer is in scope.
 
 ```yaml
 variables:
@@ -177,7 +177,7 @@ variables:
   a value the environment already carries, such as `GITHUB_TOKEN`; `x-intentional: true` then silences the
   release warning about claiming a well-known name (`PATH`, `HOME`, `USER`, `SHELL`, `GITHUB_TOKEN`,
   `GITLAB_TOKEN`, `NPM_TOKEN`, or anything starting `AWS_` or `SOUS_`, except the `SOUS_VAR_` names sous
-  derives itself). Two definitions of the same name may share one variable; two of **different** names
+  derives itself). Two definitions of the same name share one variable; two of **different** names
   claiming the same one is an error.
 - **`secret: true`** hides the value everywhere sous prints it, and **`scope`** picks the file the answer is
   written to: `shared` for the committed `.sous/.env`, `local` for the gitignored `.sous/.env.local`. A secret
@@ -187,19 +187,23 @@ variables:
   answering, and the message names your pattern. Within a major version a schema may only LOOSEN: tightening a
   constraint is a major bump, and an upgrade re-validates stored answers, re-prompting only where an old one no
   longer fits.
+- **Reading another recipe's variable** needs no definition: list that recipe under `depends` and use the name in
+  your templates. Redefining it makes a second definition, which sous combines with the first; see
+  [Two recipes, one name](repositories-variables.md#two-recipes-one-name).
 - **Further reading:** [Recipe variables](repositories-variables.md) covers how an answer is found at build
   time; [Variable definitions](repositories-file-formats.md#variable-definitions) is the full field table.
 
 ## Declare dependencies and co-subscriptions
 
 `depends` fetches and pins a recipe whose files stay OUT of a subscriber's output but are addressable from your
-own templates, and from the templates of any project whose lockfile pins it. `subscribes` is a co-subscription: its questions run and its files DO enter the output, which is
-how a curated bundle is built. Both hold plain strings naming their target by where it lives.
+own templates, and from the templates of any project whose lockfile pins it. `subscribes` is a co-subscription: its
+files DO enter the output, which is how a curated bundle is built. Under either list, the other recipe's questions
+are asked and its answers reach your templates. Both hold plain strings naming their target by where it lives.
 
 ```yaml
 depends:
-  - workflow/qa-helper                                       # a sibling, released alongside me
-  - workflow/qa-helper@^1.1                                  # a sibling with a range; uncommon
+  - workflow/qa-helper                                       # a sibling: ^ its version at release
+  - workflow/qa-helper@1.1.4                                 # a sibling at exactly one version
   - github://sous-io/sous-recipes/workflow/sat@^1.0          # another repository
   - gitlab://gitlab.example.com/group/subgroup/proj/-/qa/lint  # a self-hosted host, with subgroups
   - https://github.com/acme/recipes/tree/main/recipes/lint     # a URL copied from the browser
@@ -207,14 +211,15 @@ subscribes:
   - quality/code-review                                      # co-subscribed: its files land too
 ```
 
-A **bare ref** is a sibling in this repository; with no range it means "the version released alongside me", since
-one run cuts both tags and records the exact version in the index. A location names another repository: a
+A **bare ref** is a sibling in this repository; with no range it means `^<the sibling's version at release>`, any
+later version with the same major. A location names another repository: a
 locator, an HTTPS or SSH URL, or a URL copied from the browser. A ref is stored and printed as its published
 **identity** (namespace and recipe), never as a folder path. Any spelling that settles to one identity is
 accepted, including a folder path or a pasted browser URL: a recipe stored at `recipes/shared/sat/` and
 published as `workflow/sat` may be written `github://owner/repo/workflow/sat` or
 `https://github.com/owner/repo/tree/main/recipes/shared/sat`, and the release settles the second through the
-other repository's index. The optional range after `@` follows npm's rules. `local://` locators and `repo:`
+other repository's index. The optional range after `@` follows npm's rules, and may be exact when your recipe needs
+certainty; nothing else pins a dependency to one version except the subscribing project's lockfile. `local://` locators and `repo:`
 short names are refused: a local repository is a consumer's convenience, and a short name is one project's
 private label. See [Dependencies named by location](repositories-file-formats.md#dependencies-named-by-location)
 and every accepted spelling in [Ref forms](repositories-file-formats.md#ref-forms).
@@ -292,8 +297,9 @@ this release's scope** is fine: the release depends on the last published versio
     release's scope; 'workflow/qa-variables@0.1.1' will depend on 'workflow/qa-helper@0.1.0'.
 ```
 
-Each version's resolved dependencies are written into the index, so a consumer installing that version gets what
-it was published with rather than ranges re-resolved months later. Each dependency also records the manifest
+Each version's dependencies are written into the index as ranges: the range the manifest declares, or
+`^<the sibling's version at release>` for a sibling named with no range. A consumer resolves those ranges, and
+its own lockfile pins what it got; that lockfile is the only lock. Each dependency also records the manifest
 entry that brought it in and whether it is a co-subscription or a build dependency, and each version records the
 variable definitions its manifest publishes, so `sous recipe show` and `sous subscription add --dry-run` can say
 what a recipe installs and asks before anything is fetched. A published version never changes: its content

package/docs/markdown/repositories-consuming.md

@@ -67,8 +67,8 @@ upstream's newest version beside the installed one.
 
 Read `sous recipe show` before subscribing. It works offline, from the index alone: every published
 version, what the version depends on (the manifest entry that brings each dependency in, whether it
-is a co-subscription whose files land here or a build dependency, and the version it was released
-against), every recipe a subscription would install, and every question that would ask. Only the
+is a co-subscription whose files land here or a build dependency, and the range of versions it
+may take), every recipe a subscription would install, and every question that would ask. Only the
 files it publishes wait until it is installed. A preset set, a recipe that only bundles others,
 reads like this:
 
@@ -77,11 +77,11 @@ $ sous recipe show omakase/house
     Latest version : 1.0.0
     Pinned version : this project pins none
     Subscribed     : no
-  Dependency       Declared as                     Resolved to  Repository       Kind
-  ---------------  ------------------------------  -----------  ---------------  ----------------
-  tools/lint       tools/lint                      1.0.0        this repository  build dependency
-  workflow/notes   the whole 'workflow' namespace  1.0.0        this repository  co-subscription
-  workflow/review  the whole 'workflow' namespace  1.0.0        this repository  co-subscription
+  Dependency       Declared as                     Resolved to       Repository       Kind
+  ---------------  ------------------------------  ----------------  ---------------  ----------------
+  tools/lint       tools/lint                      the range ^1.0.0  this repository  build dependency
+  workflow/notes   the whole 'workflow' namespace  the range ^1.0.0  this repository  co-subscription
+  workflow/review  the whole 'workflow' namespace  the range ^1.0.0  this repository  co-subscription
 ➔ What subscribing asks you:
   These recipes ask 3 questions, 3 of which nothing answers yet.
   workflow/notes asks 1 question:
@@ -168,7 +168,8 @@ change when you say yes: `.sous/conf.d/510-subscriptions.jsonc` records the subs
 the new skills are on disk when it returns; `--no-build` defers that, and a failed build keeps it.
 
 ?> Only a recipe a manifest lists under `subscribes` contributes files; one listed under `depends`,
-like `workflow/qa-helper` above, is fetched and pinned but stays out of your output. See
+like `workflow/qa-helper` above, is fetched and pinned but stays out of your output. Recipes under both
+lists have their questions asked. See
 [Dependencies](repositories.md#dependencies).
 
 ## Choose where the files land
@@ -312,6 +313,11 @@ 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.
+- Every subscription in scope resolves together, so a recipe several of them need takes one version
+  that every holder's range allows: the pinned one while it still fits, otherwise the newest that
+  does. When no version fits every holder, the subscription that cannot join is refused, naming each
+  holder and its range. A library held only through `depends` that its holders need at
+  incompatible versions is instead pinned once per holder.
 - 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.

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

@@ -217,7 +217,7 @@ fetches only this file; nothing more is downloaded until a project subscribes.
   "recipes": { "quality/qa-remote-dep": { "path": "recipes/quality/qa-remote-dep",
     "versions": { "0.1.0": {
       "dependencies": {
-        "workflow/qa-helper": { "version": "0.1.0", "declared": "workflow", "kind": "subscribes" },
+        "workflow/qa-helper": { "range": "^0.1.0", "declared": "workflow", "kind": "subscribes" },
         "workflow/sub-agent-delegation": { "range": "^1.0", "repo": "github.com/sous-io/sous-recipes",
           "declared": "github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0",
           "kind": "depends" } },
@@ -239,20 +239,26 @@ fetches only this file; nothing more is downloaded until a project subscribes.
 | `recipes` | top level | Keyed `namespace/recipe`; a recipe whose namespace is not declared is an error. Each entry carries `path` (the recipe folder), `description`, and `versions`, keyed by exact version |
 | `hash`, `tag` | per version | The content hash verified after every fetch, and the tag, which must be exactly `namespace/recipe@version` so a version can never point at a branch |
 | `prerelease`, `releasedAt`, `seeded` | per version | Whether ranges skip it unless a subscription opts in, when it was released, and whether it is the copy sous folds in from its own package |
-| `dependencies` | per version | What the version was released against, keyed `namespace/recipe`; see below |
+| `dependencies` | per version | The range each dependency may take, keyed `namespace/recipe`; see below |
 | `variables` | per version | The version's variable definitions, exactly as its manifest publishes them (see [Variable definitions](#variable-definitions)), with `required`, `secret` and `scope` filled in; `[]` when it asks nothing |
 | `depends`, `subscribes` | per version | The version's manifest lists, exactly as written; `[]` when empty |
 
-Dependencies are resolved at release time and keyed `namespace/recipe`. An entry carries `version` (a
-sibling, resolved exactly) or `range` plus `repo` (the identity of the repository publishing it, whose own
-index resolves the range); at least one is required. Installing a version installs these rather than
-re-resolving the manifest's ranges.
+Dependencies are recorded at release time and keyed `namespace/recipe`. Each entry carries `range`: the range
+the manifest declares, or `^<the sibling's version at release>` for a sibling named with no range (`*` when the
+sibling has no version yet). A dependency in another repository also carries `repo`, the identity of the
+repository publishing it, whose own index resolves the range. The index never pins a dependency to one version;
+the consuming project resolves every range and its lockfile is the only lock.
+
+An entry written by an older release carries `version`, the exact version that release resolved, instead of
+`range`. Sous reads it as `^<version>`, further limited by the range in the entry's `declared` field when it
+holds one, so `{ "version": "1.1.1", "declared": "workflow/sub-agent-delegation@~1.1" }` allows any `1.1.x`
+from `1.1.1` up. Nothing is republished to change it.
 
 **Each version describes itself.** So that a recipe can be described before anything is fetched, every
 version a release records carries more than its dependencies. Each dependency records `declared`, the
 manifest entry that brings it in exactly as written (a recipe such as `workflow/qa-helper@^1.0`, a whole
 namespace such as `workflow`, or a locator), and `kind`: `subscribes` for a co-subscription, whose files
-land and whose questions are asked, or `depends` for a build dependency. When several entries cover one
+land, or `depends` for a build dependency, whose files stay out; the questions of both are asked. When several entries cover one
 recipe, an entry naming it wins over a namespace, and it is a co-subscription when any entry covering it is
 one. The version records `variables`, its manifest's definitions, and `depends` and `subscribes`, its
 manifest's lists as written; the lists are what a consumer walks, because a namespace of another repository
@@ -263,15 +269,16 @@ the resolver walks a recipe whose files are not on the machine from its index en
 its manifest. A version recorded before a release wrote these fields keeps its entry as it is; its questions
 are known only once its files are fetched, and the dry run names it as such.
 
-**A published version's entry is frozen.** Its dependencies are resolved once, when the version is first
-recorded, and every later release carries the entry forward exactly as published, like its hash; releasing
+**A published version's entry is frozen.** Its dependencies are recorded once, when the version is first
+published, and every later release carries the entry forward exactly as published, like its hash; releasing
 other recipes, adding a recipe to a namespace it subscribes to, or raising a sibling it names changes nothing
 in it. A release still checks the recorded list against the version's manifest: a recipe the manifest names
-that the list lacks, a recipe in the list the manifest does not declare, a sibling outside its declared
-range, or another repository's entry with a different repository or range is an error naming the recipe, the
-version and each difference; restore the entry if the index was edited, or bump the version to publish
-different dependencies. A version rebuilt from its tag, when the index lost it, has its dependencies resolved
-against the repository as it stood at that tag, then frozen the same way. An entry written before sous
+that the list lacks, a recipe in the list the manifest does not declare, a recorded range that is not the
+declared one (for a sibling named with no range, not a `^<version>` range or `*`), an older entry's `version`
+outside its declared range, or another repository's entry with a different repository is an error naming the
+recipe, the version and each difference; restore the entry if the index was edited, or bump the version to publish
+different dependencies. A version rebuilt from its tag, when the index lost it, has its dependencies recorded
+from the repository as it stood at that tag, then frozen the same way. An entry written before sous
 recorded dependencies carries none, stays that way, and installs by resolving its manifest's ranges.
 
 **Fields this sous does not know are kept, not refused.** A later sous may add fields to the index, at any
@@ -311,12 +318,29 @@ Machine-written, committed, and the reason a fresh clone restores with no prompt
 | `repos.<name>.url`, `.identity`, `.indexHash` | Where the repository lives, as recorded when it was added; the canonical identity the store and index cache file it under; and the hash of the index this lock was resolved against, when known |
 | `recipes.<key>.repo`, `.version`, `.hash` | The project's short name for the repository, which must appear under `repos`; the version resolved; and the hash verified against the store after every fetch |
 | `recipes.<key>.requestedBy`, `.kind` | Who holds the entry, the literal `project` or the key of a recipe that requires it, and whether that holder is a `subscribes` or a `depends` |
+| `recipes.<key>.pins.<holder>.version`, `.hash` | A version pinned for one holder alone, keyed by that holder's recipe key; absent when every holder uses `version` |
 
 A repository appears under two names on purpose: the key is the project's own short name, which every
 message uses, while `identity` is what the store is keyed by, so two projects with different labels share
 one cached copy. `identity` is optional on read only, for older lockfiles, and is derived from the URL on
 the next write. `requestedBy` makes removal safe; an entry goes when its last holder does.
 
+`pins` appears only when a holder that reaches the recipe through `depends` needs a version no other
+holder's range allows. The entry's `version` is the one the project uses (a recipe some holder reaches
+through `subscribes` has exactly one); each holder under `pins` uses its own version instead, for its
+includes and its questions, and nothing from that version reaches the project's files. Every holder under
+`pins` is also listed in `requestedBy`, and loses its pin when it stops holding the entry. Each pinned
+version is fetched, checked against its hash and kept in the store like the shared one.
+
+```json
+"support/base": { "kind": "depends", "repo": "fixtures", "version": "1.0.0", "hash": "sha256-1b...",
+  "requestedBy": ["lib/one", "lib/two"],
+  "pins": { "lib/two": { "version": "2.0.0", "hash": "sha256-9c..." } } }
+```
+
+A lockfile with no `pins` reads exactly as it did before. A version of sous older than this field refuses a
+lockfile that carries one, naming the unknown key, because the format is strict.
+
 ## The store on disk
 
 The store is machine-wide, immutable per version, and disposable (everything is re-fetchable from a

package/docs/markdown/repositories-quickstart.md

@@ -93,8 +93,8 @@ sous recipe show workflow/task-files
 ```
 
 On a machine that has never fetched the recipe, sous shows what the index knows: every published
-version, and every dependency with each declared range beside the exact version the index resolved
-it to. The questions it asks are not known until it is fetched; run the same command after
+version, and every dependency with the range it was declared with and the range the index records
+for it. The questions it asks are not known until it is fetched; run the same command after
 subscribing and it adds a table of the variables the recipe publishes.
 
 ## 4. Subscribe to a recipe

package/docs/markdown/repositories-variables.md

@@ -31,6 +31,37 @@ match on a worker under a fixed budget of 100 milliseconds, and a pattern that e
 naming the pattern and the recipe rather than blaming your answer. See
 [A variable pattern that runs out of time](repositories-troubleshooting.md#a-variable-pattern-that-runs-out-of-time).
 
+## Two recipes, one name
+
+Answers are shared by name, so when several recipes, or several versions of one recipe, define a variable of
+the same name, sous asks **one** question, built from the strictest combination of every definition:
+
+- secret when any definition is secret, `scope: local` when any is local, and required when any is required;
+- only the values every definition accepts: the `enum` options they share, the highest `min` and `minLength`,
+  the lowest `max` and `maxLength`, and every `pattern`;
+- the first definition's prompt, description and example, with the question naming the other recipes
+  (`workflow/notes, also used by review/checklist`);
+- the first `default` that passes the combination; a default that fails it is dropped.
+
+For example, one recipe defines `port` as a number of at least 1000 and another as a secret number of at most
+9000: you are asked once, for a secret number from 1000 to 9000, stored locally.
+
+When no answer could satisfy every definition (one says `number` and the other `string`, their `enum` lists
+share no option, or one's `min` is above another's `max`), the definitions are not combined. Sous says why,
+naming both, and asks each recipe separately, storing each answer under that recipe's
+[recipe-scoped name](#how-sous-finds-an-answer-the-ladder) (`SOUS_VAR_<NAMESPACE>_<RECIPE>_<VARIABLE>`).
+
+Two versions of one recipe (a recipe pinned at a different version for some of the recipes that depend on it)
+would share that recipe-scoped name, so when their definitions cannot be combined, sous asks only one of them:
+the version the lockfile shares, or else the first version the lockfile lists. The other version gets no
+answer, not even its default, and the variable renders empty where that version is used. `sous vars ask`,
+`sous vars list` and `sous vars show`, a build, and the question preview of `sous subscription add --dry-run`
+and `sous recipe show` warn about it, naming both versions, the recipes that use each, and why the definitions
+cannot be combined.
+
+A recipe that only reads another recipe's variable, by listing that recipe under `depends` and using the
+name in its templates, does not define it, so it adds nothing to the combination.
+
 ## Answer the questions
 
 Subscribing asks whatever is unanswered, so in normal use you rarely run `sous vars ask` yourself; reach for

package/docs/markdown/repositories.md

@@ -93,8 +93,8 @@ with the project.
 A recipe manifest can declare two relationships to other recipes, and they differ in exactly one
 respect: whose files end up in your project. `depends` fetches, pins and trust-gates the target
 and makes it addressable while rendering, but keeps its files out of your output; `subscribes`
-does all of that and lands the target's files in your project too, along with the variable
-questions it publishes (see [Recipe variables](repositories-variables.md)).
+does all of that and lands the target's files in your project too. Under either list, the variable
+questions the target publishes are asked (see [Recipe variables](repositories-variables.md)).
 
 ```yaml
 depends:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,44 +39,44 @@
     "sous.config.schema.json"
   ],
   "dependencies": {
-    "@sous-io/plugin-api": "1.0.13"
+    "@sous-io/plugin-api": "1.0.14"
   },
   "devDependencies": {
     "esbuild": "^0.27.4",
     "jsonc-parser": "^3.3.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@sous-io/documents": "1.0.13",
-    "@sous-io/plugin-authoring": "1.0.13",
-    "@sous-io/plugin-build": "1.0.13",
-    "@sous-io/plugin-claude-code": "1.0.13",
-    "@sous-io/core": "1.0.13",
-    "@sous-io/plugin-cli": "1.0.13",
-    "@sous-io/plugin-confd": "1.0.13",
-    "@sous-io/plugin-config-files": "1.0.13",
-    "@sous-io/plugin-formats": "1.0.13",
-    "@sous-io/plugin-github": "1.0.13",
-    "@sous-io/plugin-expressions": "1.0.13",
-    "@sous-io/plugin-git": "1.0.13",
-    "@sous-io/plugin-harnesses": "1.0.13",
-    "@sous-io/plugin-gitlab": "1.0.13",
-    "@sous-io/plugin-init": "1.0.13",
-    "@sous-io/plugin-compiler": "1.0.13",
-    "@sous-io/plugin-inspect": "1.0.13",
-    "@sous-io/plugin-host": "1.0.13",
-    "@sous-io/plugin-liquid": "1.0.13",
-    "@sous-io/plugin-local": "1.0.13",
-    "@sous-io/plugin-mcp": "1.0.13",
-    "@sous-io/plugin-memories": "1.0.13",
-    "@sous-io/plugin-npm": "1.0.13",
-    "@sous-io/plugin-pnpm": "1.0.13",
-    "@sous-io/plugin-recipe-answers": "1.0.13",
-    "@sous-io/plugin-recipes": "1.0.13",
-    "@sous-io/plugin-skills": "1.0.13",
-    "@sous-io/plugin-variables": "1.0.13",
-    "@sous-io/plugin-update": "1.0.13",
-    "@sous-io/plugin-yarn": "1.0.13",
-    "@sous-io/plugin-refs": "1.0.13"
+    "@sous-io/core": "1.0.14",
+    "@sous-io/documents": "1.0.14",
+    "@sous-io/plugin-build": "1.0.14",
+    "@sous-io/plugin-claude-code": "1.0.14",
+    "@sous-io/plugin-authoring": "1.0.14",
+    "@sous-io/plugin-cli": "1.0.14",
+    "@sous-io/plugin-compiler": "1.0.14",
+    "@sous-io/plugin-config-files": "1.0.14",
+    "@sous-io/plugin-formats": "1.0.14",
+    "@sous-io/plugin-expressions": "1.0.14",
+    "@sous-io/plugin-confd": "1.0.14",
+    "@sous-io/plugin-git": "1.0.14",
+    "@sous-io/plugin-github": "1.0.14",
+    "@sous-io/plugin-harnesses": "1.0.14",
+    "@sous-io/plugin-init": "1.0.14",
+    "@sous-io/plugin-host": "1.0.14",
+    "@sous-io/plugin-inspect": "1.0.14",
+    "@sous-io/plugin-gitlab": "1.0.14",
+    "@sous-io/plugin-local": "1.0.14",
+    "@sous-io/plugin-liquid": "1.0.14",
+    "@sous-io/plugin-mcp": "1.0.14",
+    "@sous-io/plugin-memories": "1.0.14",
+    "@sous-io/plugin-pnpm": "1.0.14",
+    "@sous-io/plugin-recipe-answers": "1.0.14",
+    "@sous-io/plugin-npm": "1.0.14",
+    "@sous-io/plugin-recipes": "1.0.14",
+    "@sous-io/plugin-skills": "1.0.14",
+    "@sous-io/plugin-update": "1.0.14",
+    "@sous-io/plugin-variables": "1.0.14",
+    "@sous-io/plugin-refs": "1.0.14",
+    "@sous-io/plugin-yarn": "1.0.14"
   },
   "engines": {
     "node": ">=22"

package/recipes/core/sous-skills/skills/about-sous-recipes/SKILL.tpl.md

@@ -134,8 +134,13 @@ The fields in that example, and the ones it leaves out:
   answers already stored.
 
 A template may also read a variable another recipe defines. List that recipe under `depends`, so
-the variable is there wherever this recipe is, and branch on it in the template rather than telling
-the agent to look the setting up; `about-liquid-templates` shows how.
+the variable is there wherever this recipe is, and MUST NOT redefine it; branch on it in the
+template rather than telling the agent to look the setting up (`about-liquid-templates` shows how).
+
+When two recipes do define one name, the project is asked one question built from the strictest
+combination: secret, `local` or required if any definition is, and only the values every definition
+accepts. When no value can satisfy both (different types, no shared `enum` option), each recipe is
+asked separately under its recipe-scoped name.
 
 ## Depends and Subscribes
 
@@ -144,14 +149,18 @@ Both lists name other recipes, and they do different things:
 - `depends` makes the other recipe a **library** for this one. It is fetched and pinned, and its
   files can be included from this recipe's templates, but its files never reach the subscriber's
   output.
-- `subscribes` is a **co-subscription**. The other recipe's files land and its questions are asked,
-  as if the project had subscribed to it too.
+- `subscribes` is a **co-subscription**. The other recipe's files land, as if the project had
+  subscribed to it too.
+
+Under either list, the other recipe's questions are asked, and its answers are in this recipe's
+templates.
 
 Each entry names its target by where it lives:
 
 - a bare `namespace/recipe` (or `namespace` for all of it) for a sibling in the same repository.
-  With no range it means the version released alongside this one; an `@` range (npm's rules) is
-  allowed but uncommon.
+  With no range it means `^<the sibling's version at release>`, the same major version. An `@`
+  range follows npm's rules and MAY be exact (`workflow/qa-helper@1.2.0`) when this recipe needs
+  certainty; the subscribing project's lockfile is the only thing that pins an exact version.
 - a location for a recipe in another repository, such as
   `github://example-org/team-recipes/review/wording@^1.0`, an HTTPS or SSH URL, or a URL copied
   from the browser. A ref is stored and printed as its published identity (namespace and recipe),

package/recipes/core/sous-skills/skills/about-sous-repos/SKILL.tpl.md

@@ -65,8 +65,9 @@ contribute: https://github.com/harbor-labs/team-recipes/blob/main/CONTRIBUTING.m
 A recipe's version lives in its manifest, which is the source of truth. A version is **published**
 once a git tag shaped `namespace/recipe@version` exists for it (for example
 `review/checklist@1.2.0`). The index records each published version with its content hash, its
-tag, the exact versions of its dependencies at release time (each with the manifest entry that
-brought it in and whether it is a co-subscription or a build dependency) and the variable
+tag, the range each of its dependencies may take (the declared range, or `^<version at release>`
+for a sibling named with no range; each with the manifest entry that brought it in and whether it
+is a co-subscription or a build dependency) and the variable
 definitions it publishes, which is how a project lists what a recipe installs and asks before
 fetching it; for the length of one release commit it also records the version each manifest
 declares, whose tag that release cuts next. A published version never changes: new files need a

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

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 1.0.13
+version: 1.0.14
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous