bullswarm 0.28.2 → 0.28.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # bullswarm changelog
 
+## 0.28.4 — the skill says how, the schema file says what
+
+- skill: the method and the schema are now separate files. `skill/SKILL.md`
+  (1,345 → 914 words) keeps only what the kernel cannot check: choosing the
+  shape, decomposing into territories, dependencies as inputs rather than
+  phases, the integrator, evidence, the effort rule (writers are `implement`;
+  high belongs to `integration`, `architecture`, `adversarial-acceptance`;
+  never `defaults.effort: high`), and an explicit validate → read `advisories`
+  → adjust → launch sequence. The new `skill/references/program.md` holds the
+  program format: fields, kinds, requirement-ID derivation, enforced rules and
+  one example that validates with no advisories. `plan contract` is no longer a
+  step in the default flow; operations.md documents it as the live fallback
+  and the dispatched planner's brief. Reasoning depth, digest details and the
+  watch flags live in operations.md only.
+
+## 0.28.3 — connector upgrades learn new packaged profiles
+
+- command-code: a profile entry for `deepseek/deepseek-v4.1-flash` that
+  carries the model's own pricing from
+  https://commandcode.ai/docs/resources/pricing-limits (2026-09-11): input
+  $0.15, cache read $0.003, output $0.60 per million tokens off peak (the
+  peak window is documented in the entry). Tier and rank stay exactly what the
+  generic flash catch-all gives; this is not a recommendation, and none will
+  be packaged without benchmark evidence. Note for operators: model discovery
+  is only re-run by `bullswarm strategy refresh`, so a model a CLI added since
+  the last refresh is rejected by `strategy set-rung` until you refresh.
+- Connector upgrades now insert packaged `modelProfiles` entries that the
+  installed connector lacks (keyed by `match` or `id`) at the position the
+  packaged order implies: before the installed generic catch-all a specific
+  entry was written to precede, never ahead of a profile the operator
+  authored. Profiles the installed connector already holds are never touched.
+  Before this, `modelProfiles` was copied only when the installed connector
+  had none at all, so existing installations never learned new entries.
+
 ## 0.28.2 — terminal glyph fallback, issue watcher, health on a fresh home
 
 - `bullswarm workflow` repainted flashing `?` characters on macOS

package/connectors/command-code.json

@@ -256,6 +256,19 @@
       "tier": "low",
       "qualityRank": 3
     },
+    {
+      "match": "^deepseek/deepseek-v4\\.1-flash$",
+      "tier": "low",
+      "qualityRank": 2,
+      "$comment-deepseek": "Facts only, no recommendation: tier and rank are exactly what the generic flash catch-all below would give, kept here so the entry carries the model's own pricing. OpenRouter publishes no indices for this model yet; raise nothing here without benchmark evidence. Pricing is the off-peak rate (17 h/day); peak is $0.30 input / $1.20 output during 01–04 and 06–10 UTC Monday–Friday.",
+      "pricing": {
+        "inputUsdPerMillion": 0.15,
+        "cacheReadUsdPerMillion": 0.003,
+        "outputUsdPerMillion": 0.6
+      },
+      "pricingSource": "https://commandcode.ai/docs/resources/pricing-limits",
+      "pricingUpdatedAt": "2026-09-11"
+    },
     {
       "match": "(?:flash|(?:^|[/.-])mini(?:$|[/.-])|luna|free)",
       "tier": "low",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.28.2",
+  "version": "0.28.4",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -5,167 +5,120 @@ description: Delegate bounded work through Bullswarm to one quota-routed coding
 
 # Bullswarm
 
-You supply the task or dependency graph. Bullswarm routes workers by quota and
-capability, runs them, and saves their outputs. For workflows, **you are the
-planner by default**: write the graph once; the kernel executes it to the end.
+You write the task. Bullswarm picks a worker by quota and capability, runs it,
+and saves the output. For a workflow you are the planner: write the program
+once and the kernel runs it to the end.
 
 Keep the user's scope and working directory. Delegate only authorized work;
 permission to delegate does not authorize messages, releases, or other external
-writes. If `BULLSWARM_DEPTH` is set, do the assigned work directly unless the
-task explicitly requires nested delegation.
+writes. If `BULLSWARM_DEPTH` is set you are already a worker: do the assigned
+work directly unless it explicitly requires nested delegation.
 
-## 1. Choose the shape yourself
+## 1. Choose the shape
 
-Use one agent for a bounded outcome such as a review or localized fix. Use a
-workflow for parallel territories, integration, or implementation followed by
-independent acceptance. There is no preview or classifier step — decide from
-the request itself and go directly to the matching mode below.
+One agent for one bounded outcome: a review, a localized fix, a study with one
+deliverable. A workflow when the work splits into parallel territories, needs
+integration, or needs independent acceptance. Decide from the request itself;
+there is no classifier command.
 
 ## 2a. One agent
 
-Dispatch it directly:
-
 ```bash
 bullswarm run --lane=analyze --add-dir=<abs-dir> --prompt='<task>' --json
 ```
 
-An unrecognized `--flag` on any command prints `unknown flag --name` plus
-that command's synopsis and exits 2, before routing or spawning anything.
-
-Choose `build` for edits, `chore` for mechanical edits, or `analyze` for
-read-only work. Use `--task-file` instead of `--prompt` for long text or
-awkward quoting. The result's top-level fields include `ok`, `keepOnClaude`,
-`pick` (the chosen `{pool, model, command}`), `outFile`, and `why`:
-
-- `keepOnClaude: true`: do the work yourself, even if `ok` is true.
-- Otherwise, when `ok: true`, read `outFile` and check its content before using it.
-- `ok: false`: inspect and report the failure; a successful CLI exit is not
-  proof that the work succeeded.
-
-Do not run `doctor` unless dispatch reports a readiness problem.
+Lanes: `build` edits, `chore` mechanical edits, `analyze` read-only. Use
+`--task-file` for long text. Read the result: `keepOnClaude: true` means do it
+yourself; `ok: true` means read `outFile` and check its content before using
+it; `ok: false` means inspect and report the failure. A clean exit code is not
+proof of success. Do not run `doctor` unless dispatch reports a readiness
+problem.
 
 ## 2b. A workflow
 
-Get the planning contract:
+The program format lives in [program.md](references/program.md): fields, kinds,
+requirement IDs, enforced rules, and one example. This section is how to
+author the graph.
+
+- **Decompose.** One action per bounded outcome a single worker can finish
+  alone. Every writer gets an `ownedFiles` territory. All workers share one
+  tree, so tell each to preserve others' edits and to report any file it needs
+  outside its territory instead of editing it.
+- **Dependencies are inputs, not phases.** `dependsOn` lists the actions whose
+  outputs this action reads. Everything with no unmet dependency runs at once.
+  A phase is simply the set of actions that become ready together; never add a
+  dependency to fake one.
+- **Integrate after parallel writers.** One `integration` action that depends
+  on all of them, directly or through a digest, with `ownedFiles: []`, which
+  on a build-lane action means no territory limit. It reads their outputs,
+  resolves shared-file requests, and runs the repository's acceptance checks.
+  It runs alone.
+- **Check independently when acceptance matters.** One `adversarial-acceptance`
+  action with empty `affects` and `ownedFiles`, `evidenceFor` set to the
+  requirement IDs it judges, depending on every writer that affects them.
+  Describe what to inspect; the kernel supplies the evidence format. A
+  requirement may be covered by evidence alone: a "verification" deliverable
+  is the evidence report in the run result, not a file.
+- **Digest when outputs pile up.** A `digest` action when three or more outputs
+  feed one reader, or a reader's inputs exceed about 20 KB. The reader depends
+  on the digest instead of the raw writers and gets `digestOf` links to them;
+  the digest keeps every shared-file request. Evidence never depends on a
+  digest.
+- **Effort.** Writers are `implement`. High belongs to exactly three kinds:
+  `integration` (the sole writer after parallel work), `architecture` (a
+  read-only judgment whose report a later action consumes), and
+  `adversarial-acceptance` (independent evidence). A study that reads code and
+  writes markdown is `implement`. When a judgment must land in a file, keep it
+  `implement`, or split it into an `architecture` action plus a writer that
+  records its report. Never set `defaults.effort` to `high`, and do not
+  restate `lane` or `effort` on an action that has a `kind`.
+- **Prompts are self-contained.** Each names the absolute workspace path
+  (nothing is substituted), the outcome, the relevant files, the dependency
+  outputs to read, and the concrete checks to run.
+
+### Validate, read, adjust, then launch
+
+Keep the goal in a file and pass it as `"$(cat goal.txt)"` to both commands,
+so validate and launch get identical text, apostrophes and line breaks
+included.
 
 ```bash
-bullswarm workflow plan contract '<goal>' --cwd=<abs-dir> --json
+bullswarm workflow plan validate "$(cat goal.txt)" --cwd=<abs-dir> --program=<abs-dir>/plan.json --json
 ```
 
-Use exactly the same goal when validating and launching. Keep `--cwd` fixed to
-the absolute target directory even when generating the plan elsewhere. Preserve
-the requested outcomes; numbered deliverables produce separate requirement IDs. The contract
-contains the current schema, IDs, rules, and a worked program example.
-
-Write `plan.json` from the contract's worked example. The bare program has
-`schemaVersion: "bullswarm.workflow.program.v2"` and a populated `actions` array.
-Each action needs `id`, `purpose`, `dependsOn`, `affects`, `ownedFiles`,
-`prompt`, and `evidenceFor`, plus either `kind` or an explicit `lane`. Copy
-requirement IDs from the contract. Optional `inputs`/`produces` describe actual
-artifacts; ordinary dependencies do not need them. Never put provider/model
-fields into the program.
-
-Set `kind` on every action and it fills `lane` and `effort`: `mechanical`
-(chore/low), `io-read` (analyze/low), `digest` (analyze/low), `check`
-(analyze/medium), `implement` (build/medium), `integration` (build/high),
-`architecture` (analyze/high),
-`adversarial-acceptance` (analyze/high). An explicit `lane` or `effort` still
-wins, then the kind table, then an optional program-level `defaults` object
-(`effort` and `reasoning` only), then the per-lane default. A kind outside that
-list is rejected before anything runs. `plan validate` and `workflow goal` also
-print non-blocking `advisory:` lines — `all-writers-high` and `docs-at-high` —
-which never change acceptance or the exit code.
-
-Author the graph around these rules:
-
-- **Shared tree:** give each writer an intended `ownedFiles` territory. New
-  files survive; territories guide scheduling, not file rejection. Tell workers
-  others share the tree, preserve their edits, and report shared-file requests.
-- **Real dependencies:** independent actions run concurrently. After parallel
-  writers, add a sole integrator depending on all of them, with `lane: "build"`
-  and `ownedFiles: []`. It reads their outputs, handles shared-file requests,
-  and runs repository acceptance checks. This unrestricted integrator runs alone.
-- **Optional digest:** `kind: "digest"` condenses its dependencies' outputs into
-  one artifact so an expensive consumer reads a digest instead of many raw
-  files. It is extractive — the kernel writes the task and it quotes verbatim,
-  never judges. Add one when three or more writers feed a single integrator, or
-  when any consumer's dependency outputs exceed roughly 20 KB. It needs at least
-  one `dependsOn`, empty `evidenceFor` and empty `ownedFiles`; `affects` may be
-  empty. Never let an evidence action depend on a digest — evidence reads the
-  real artifacts, and the validator exits 2 if it does. Consumers still get a
-  `digestOf` list naming each digested source, so they can drill down.
-- **Self-contained work:** each prompt names the exact workspace, outcome,
-  relevant files, and concrete checks. Use `medium` effort for ordinary build
-  or analysis, `low` for mechanical chores, and `high` for difficult judgment.
-- **Optional evidence:** an independent check uses `lane: "analyze"`, empty
-  `affects`/`ownedFiles`, and `evidenceFor` requirement IDs. Depend on every
-  writer affecting those requirements. Describe the checks; the kernel adds
-  the evidence JSON instructions. Evidence is optional for graph completion.
-- **Optional reasoning depth:** `effort` picks the model tier; the optional
-  `reasoning` field picks how hard that model thinks. Values are
-  `low|medium|high|xhigh|max`, or `default` to pass nothing and let the worker
-  CLI's own setting decide. It applies to that one action and outranks every
-  configured level for it — so a `low`-effort integrator can still get `xhigh`
-  thinking. Omit it and the configured level applies; it never changes the
-  pool, model, or effort tier, and a connector that does not accept the exact
-  level gets the nearest level it supports. Set it only when an action needs
-  deeper thinking than its tier implies (a tricky shared-file integrator,
-  ambiguous acceptance judgment) or cheaper thinking for mechanical work.
-  For the whole run instead of one action, pass
-  `--worker-reasoning <level>` (and `--planner-reasoning <level>` with
-  `--orchestrator`) to `workflow goal`; the contract's `reasoning` block
-  echoes what a launch will apply.
-
-Validate, then launch:
+Exit 2 means the program is invalid: the JSON lists `issues`; fix them and
+validate again. Exit 0 always carries an `advisories` array. Each entry names
+an action whose effort is above what its work warrants (`all-writers-high`,
+`docs-at-high`): lower that action's kind and validate again, or write the
+reason it needs high into its `purpose`. An empty array means launch now, with
+the same goal, `--cwd` and absolute `--program` (validate's `next.launch` line
+is this command):
 
 ```bash
-bullswarm workflow plan validate '<goal>' --cwd=<abs-dir> --program=plan.json --json
-bullswarm workflow goal '<goal>' --cwd=<abs-dir> --program=plan.json --json
+bullswarm workflow goal "$(cat goal.txt)" --cwd=<abs-dir> --program=<abs-dir>/plan.json --json
 ```
 
-An invalid program exits 2 and launches nothing. Fix the reported issues and
-validate again. A valid launch detaches and returns `shortId`; report it.
+The launch detaches and returns `shortId`; report it.
 
-## 3. Observe and judge the result
+## 3. Observe and judge
 
 ```bash
 bullswarm workflow watch <shortId> --next
-bullswarm workflow watch <shortId> --next --after <sequence> --since <iso-timestamp>
 bullswarm workflow runs result <shortId> --json --summary
 ```
 
-Use the compact summary in the status loop. Read the full envelope with `--json` alone when the run is failed or partial, or before judging evidence.
-
-When the user asked you to complete the work, follow the run through its result.
-Launch `bullswarm workflow watch <shortId> --next` in a background terminal, act
-on the printed event when it exits, and relaunch until the outcome line reports
-a pause or a terminal status. Each exit that leaves the run going ends with
-`next: bullswarm workflow watch <shortId> --next --after <sequence> --since <iso>`:
-relaunch with exactly those two values, so events committed while you were
-acting are printed instead of skipped and a stall you already saw does not
-report twice. In `--jsonl` mode there is no such line — take `--after` from the
-`sequence` field of the last object. V2 watch prints one line per notable event
-and stays silent while work is merely in progress; `--heartbeat` is opt-in and
-`--stall-after` (default 300s) reports a silent running agent. A usage-limit
-failure always prints — `⚠ ... usage limit on <pool> · paused until <deadline>
-· retrying on another pool`, then `↺ ... now on <pool> · <model>` once the
-mechanical retry lands — even without `--verbose`. Pass `--classic` for the
-older heartbeat-based watcher instead (V2 only; it cannot combine with
-`--next`). A legacy authored-graph run cannot be watched: the watcher prints
-the legacy line and exits 2.
-`watch` also exits at a durable planning pause; that is not completion.
-
-Read action outputs and actual artifacts, and probe important edge cases yourself.
-`completed` means the graph succeeded; `verified` means the evidence agents
-returned passing verdicts, which can still miss bugs. A `partial` result
-exposes failed or skipped branches. Negative evidence remains negative and does
-not trigger automatic gap-planning rounds. Author follow-up work explicitly
-when the requested outcome still needs repairs.
-
-Shared files remain after failure or cancellation. Saved older runs keep their
-original execution behavior. Exit 0 can mean launched, paused, or completed;
-always inspect the returned status.
-
-Read [operations.md](references/operations.md) only when you need **steering,
-cancellation, resume, scouting, a dispatched planner, explicit isolation,
-routing diagnosis**. Ordinary work needs only the flow above.
+Run `watch --next` in a background terminal. When it exits, act on the printed
+event and relaunch with the exact `next: bullswarm workflow watch <shortId>
+--next --after <sequence> --since <iso>` line it printed, until the outcome
+line reports a pause or a terminal status. A pause is not completion.
+
+Then read the real outputs and artifacts and probe the important edge cases
+yourself. `completed` means the graph ran. `verified` means evidence passed,
+which can still miss bugs. `partial` exposes failed or skipped branches; author
+follow-up work explicitly when the outcome still needs repair. Shared files
+remain after failure or cancellation. Exit 0 can mean launched, paused, or
+completed, so always inspect the returned status.
+
+[operations.md](references/operations.md) covers steering, cancellation,
+resume, scouting, a dispatched planner, isolation, watch flags, reasoning
+depth, digest details, the live planning contract, and routing diagnosis.

package/skill/references/operations.md

@@ -91,6 +91,20 @@ commands fail closed with their short ID and retained run directory.
 
 ## Program actions: `kind`, `defaults`, and advisories
 
+The program format itself — fields, kinds, requirement IDs, enforced rules
+and an example — is in [program.md](program.md). The same rules are also served
+live by the running kernel:
+
+```bash
+bullswarm workflow plan contract '<goal>' --cwd=<abs-dir> --json
+```
+
+That contract carries the goal's derived requirement IDs, the exact validate
+and launch commands with goal and `--cwd` filled in, and any run-wide
+`reasoning` override. It is the brief a dispatched planner receives, and the
+fallback for a caller whose `plan validate` rejects field names or kinds after
+an upgrade.
+
 An action's `kind` names what the work IS and derives its `lane` and `effort`,
 so a program states the nature once instead of re-deciding two routing fields:
 

package/skill/references/program.md

@@ -0,0 +1,134 @@
+# Workflow program format
+
+`plan.json` is the program that `bullswarm workflow goal` executes. Before
+launch, `bullswarm workflow plan validate` checks it against the running
+kernel. Exit 2 returns `issues` and a `next` block; fix the issues yourself.
+Exit 0 returns the resolved program and an `advisories` array. This file
+ships with the kernel it describes; fetch the live contract only when an issue
+names an unknown field, kind, or `schemaVersion`, which can only happen after
+an upgrade this file has not followed:
+
+```bash
+bullswarm workflow plan contract '<goal>' --cwd=<abs-dir> --json
+```
+
+## Program
+
+| field | required | value |
+|---|---|---|
+| `schemaVersion` | yes | exactly `bullswarm.workflow.program.v2` |
+| `actions` | yes | non-empty array of actions |
+| `defaults` | no | object with only `effort` (`high`, `medium`, `low`) and `reasoning` (`low`, `medium`, `high`, `xhigh`, `max`, `default`); applies where neither the action nor its kind sets the field |
+
+No other top-level field is accepted.
+
+## Action
+
+| field | required | value |
+|---|---|---|
+| `id` | yes | kebab-case, unique in the program |
+| `purpose` | yes | one line: what this action delivers |
+| `dependsOn` | yes | ids of the actions whose outputs this one reads; `[]` if none |
+| `affects` | yes | requirement IDs this action's work contributes to; an action with `ownedFiles` must list at least one |
+| `ownedFiles` | yes | repo-relative paths this action may edit; `[]` on a build-lane action means no territory limit (the integrator); analyze-lane actions edit nothing |
+| `prompt` | yes | the self-contained task text with the absolute workspace path written in (nothing is substituted; `<cwd>` in the example is a placeholder); for a `digest`, one line of focus appended to the kernel-written task |
+| `evidenceFor` | yes | requirement IDs this action judges; `[]` unless it is evidence |
+| `kind` | kind or lane | one of the kinds below |
+| `lane` | kind or lane | `analyze` (read-only), `build` (edits), `chore` (mechanical edits); only when there is no kind |
+| `effort` | no | `high`, `medium`, `low`; overrides the kind's effort |
+| `reasoning` | no | `low`, `medium`, `high`, `xhigh`, `max`, `default`; how hard the picked model thinks, outranks every configured level |
+| `inputs`, `produces` | no | artifact IDs, kebab-case: the producer lists an ID in `produces`, its consumer in `inputs`; omit for ordinary dependencies |
+
+Any other field is rejected. Resolution per field: the action's own `lane` or
+`effort`, then the kind table, then `defaults`, then the lane's default.
+
+## Kinds
+
+| kind | lane | effort | use for |
+|---|---|---|---|
+| `mechanical` | chore | low | renames, formatting, generated edits |
+| `io-read` | analyze | low | fetch or read something and report it |
+| `digest` | analyze | low | condense dependency outputs verbatim; the kernel writes its task |
+| `check` | analyze | medium | a read-only inspection with a report |
+| `implement` | build | medium | ordinary edits and writing, including docs written from code study |
+| `integration` | build | high | the sole writer after parallel writers; `ownedFiles: []` |
+| `architecture` | analyze | high | a read-only cross-cutting judgment; its report feeds a later action |
+| `adversarial-acceptance` | analyze | high | independent evidence; empty `affects` and `ownedFiles`, `evidenceFor` set |
+
+An analyze-lane action edits nothing; its deliverable is the report a
+dependent reads.
+
+## Requirement IDs
+
+The kernel derives requirements from the goal text. Each numbered item, `1.`
+or `1)` at the start of a line or inline in one line counting from 1, becomes
+`requirement-N` in order. A goal with no numbered items is one
+`requirement-1`. Number distinct deliverables in the goal to get one verdict
+each, and use exactly the same goal text for validate and launch.
+
+## Enforced rules
+
+- A goal that starts with `read-only`, or says repository files must not be
+  modified, forbids mutation: every `ownedFiles` must be `[]`.
+- A `digest` needs at least one `dependsOn`, empty `evidenceFor`, empty
+  `ownedFiles`, and no evidence action may list it in `dependsOn`. Only the
+  direct dependency is checked; evidence may depend on an action that itself
+  read a digest.
+- A requirement needs no writer: coverage by `evidenceFor` alone is accepted,
+  and evidence itself is optional.
+- An evidence action's prompt describes what to inspect only. A directive such
+  as "return only JSON" is rejected; the kernel owns the evidence format.
+- A kind outside the table, a lane outside `analyze|build|chore`, or an effort
+  outside `high|medium|low` exits 2 before anything runs.
+
+## Example
+
+Goal: `1. Add --since to runs list. 2. Document it in README.`
+
+```json
+{
+  "schemaVersion": "bullswarm.workflow.program.v2",
+  "actions": [
+    {
+      "id": "since-flag",
+      "kind": "implement",
+      "purpose": "Add --since to runs list with a unit test",
+      "dependsOn": [],
+      "affects": ["requirement-1"],
+      "ownedFiles": ["src/workflow/runs-cli.js", "tests/runs-list.test.js"],
+      "evidenceFor": [],
+      "prompt": "In <cwd>, add a --since <time> flag to `bullswarm workflow runs list` in src/workflow/runs-cli.js with a unit test in tests/runs-list.test.js. Others share this tree: preserve their edits and report any file you need outside your territory. Run `npm test` and quote the summary line."
+    },
+    {
+      "id": "readme",
+      "kind": "implement",
+      "purpose": "Document --since in README",
+      "dependsOn": [],
+      "affects": ["requirement-2"],
+      "ownedFiles": ["README.md"],
+      "evidenceFor": [],
+      "prompt": "In <cwd>, document the --since <time> flag of `bullswarm workflow runs list` in the runs section of README.md, matching the style of the neighbouring flags. Edit README.md only."
+    },
+    {
+      "id": "integrate",
+      "kind": "integration",
+      "purpose": "Reconcile both edits and run the full suite",
+      "dependsOn": ["since-flag", "readme"],
+      "affects": ["requirement-1", "requirement-2"],
+      "ownedFiles": [],
+      "evidenceFor": [],
+      "prompt": "In <cwd>, read both dependency outputs, resolve any shared-file requests they raised, make the README wording match the flag as implemented, run `npm test`, and quote the summary line."
+    },
+    {
+      "id": "verify",
+      "kind": "adversarial-acceptance",
+      "purpose": "Independently confirm the flag works and is documented",
+      "dependsOn": ["since-flag", "readme", "integrate"],
+      "affects": [],
+      "ownedFiles": [],
+      "evidenceFor": ["requirement-1", "requirement-2"],
+      "prompt": "In <cwd>, exercise `bullswarm workflow runs list --since <time> --json` against a fixture home with runs on both sides of the bound, and check that README.md describes the flag and its accepted time forms. Inspect only; try to break it."
+    }
+  ]
+}
+```

package/src/setup.js

@@ -269,6 +269,34 @@ export function upgradeConnectorMetadata(bullswarmDir, {
           changed = true;
         }
       }
+      // A packaged profile the installed connector has never seen (keyed by
+      // its `match` pattern or `id`) is inserted where the packaged order puts
+      // it: right before the first installed entry that comes later in the
+      // packaged list, else at the end. So a new specific entry lands ahead of
+      // the packaged generic catch-all it was written to precede, but never
+      // ahead of a profile the operator authored themselves. Entries the
+      // installed connector already holds, edited or not, are never touched;
+      // recommendation guards were handled above.
+      if (Array.isArray(installed.modelProfiles) && Array.isArray(packaged.modelProfiles)) {
+        const keyOf = (profile) => (profile?.match != null ? `match:${profile.match}`
+          : profile?.id != null ? `id:${profile.id}` : null);
+        // Guards are prepended by policy above, so they never anchor order.
+        const packagedIndex = new Map(packaged.modelProfiles
+          .map((profile, index) => [keyOf(profile), index])
+          .filter(([key], index) => key != null && typeof packaged.modelProfiles[index].autoRecommend !== 'boolean'));
+        packaged.modelProfiles.forEach((profile, index) => {
+          const key = keyOf(profile);
+          if (key == null || typeof profile.autoRecommend === 'boolean') return;
+          if (installed.modelProfiles.some((entry) => keyOf(entry) === key)) return;
+          let at = installed.modelProfiles.length;
+          for (let j = 0; j < installed.modelProfiles.length; j += 1) {
+            const laterInPackage = packagedIndex.get(keyOf(installed.modelProfiles[j]));
+            if (laterInPackage != null && laterInPackage > index) { at = j; break; }
+          }
+          installed.modelProfiles.splice(at, 0, profile);
+          changed = true;
+        });
+      }
       if (changed) {
         writeFileSync(dst, `${JSON.stringify(installed, null, 2)}\n`);
         upgraded.push(f);