harness-everything 0.24.0 → 0.25.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.24.0",
+      "version": "0.25.1",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.25.1](https://github.com/dyphn1/Harness-everything/compare/v0.25.0...v0.25.1) (2026-09-24)
+
+### Bug Fixes
+
+* **skills:** document worktree submodule reachability ([024185a](https://github.com/dyphn1/Harness-everything/commit/024185ab29363968bbe30d648cf2ef902751e9b9))
+* **skills:** keep worktree contract within token budget ([c41903d](https://github.com/dyphn1/Harness-everything/commit/c41903d2c37e3af127b84b0ba9c5a82cd4fab3ee))
+* **skills:** preserve isolation contract wording ([b14ea2a](https://github.com/dyphn1/Harness-everything/commit/b14ea2a6e6417f4103f16e5d2cf04e6fc994e583))
+* **skills:** require submodule reachability reference ([5c61c2b](https://github.com/dyphn1/Harness-everything/commit/5c61c2bbae0f2e29818579bd2ebcd7d45a76c1b0))
+* **skills:** sync compact worktree contract ([cd4e3a8](https://github.com/dyphn1/Harness-everything/commit/cd4e3a8db276083ac11346031f626058cd02bed3))
+* **skills:** sync isolation contract wording ([7f59b1c](https://github.com/dyphn1/Harness-everything/commit/7f59b1c4e66d00ec84c225ad161e503a443ad1cd))
+* **skills:** sync worktree submodule reference ([b3fdf5d](https://github.com/dyphn1/Harness-everything/commit/b3fdf5dff8b2c22ff02cc39510d23dc60c2489ae))
+* **skills:** sync worktree submodule skill ([08dffec](https://github.com/dyphn1/Harness-everything/commit/08dffec0aa69602b61a1a90b6d10cbf97cea0dcb))
+
+## [0.25.0](https://github.com/dyphn1/Harness-everything/compare/v0.24.0...v0.25.0) (2026-09-23)
+
+### Features
+
+* **router:** bound system one labeling runs with --max-batches ([e69b596](https://github.com/dyphn1/Harness-everything/commit/e69b5962888ad9e53ca189f36e67ccf6ada03290)), closes [#233](https://github.com/dyphn1/Harness-everything/issues/233)
+
+### Bug Fixes
+
+* **router:** drop agent-authored prompts from system one training data ([8a2f959](https://github.com/dyphn1/Harness-everything/commit/8a2f959bb2ffd56c64d7e9eb2342b1178cd559dd)), closes [#233](https://github.com/dyphn1/Harness-everything/issues/233)
+
 ## [0.24.0](https://github.com/dyphn1/Harness-everything/compare/v0.23.0...v0.24.0) (2026-09-23)
 
 ### Features

package/ci/mechanism-system-one-collect.test.js

@@ -25,11 +25,13 @@ function fakeHome() {
     { type: 'assistant', message: { content: 'assistant text must be skipped' } },
   ]));
   write('.codex/sessions/2026/09/01/rollout-a.jsonl', jsonl([
+    { type: 'session_meta', payload: { originator: 'codex_vscode', source: 'vscode' } },
     { type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: '<environment_context>cwd</environment_context>' }] } },
     { type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'duplicate of the event message' }] } },
     { type: 'event_msg', payload: { type: 'user_message', message: 'add a --verbose flag with tests' } },
   ]));
   write('.codex/sessions/2026/09/02/rollout-b.jsonl', jsonl([
+    { type: 'session_meta', payload: { originator: 'Codex Desktop', source: 'vscode' } },
     { type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: '<user_instructions>agents</user_instructions>' }] } },
     { type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'older session without event messages' }] } },
   ]));
@@ -69,6 +71,33 @@ test('S1-C101 each source yields only owner-typed text', () => {
   } finally { fs.rmSync(home, { recursive: true, force: true }); }
 });
 
+test('S1-C106 only interactive Codex sessions count, and VS Code terminal notifications are dropped', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-s1-collect-'));
+  const appdata = path.join(home, 'AppData', 'Roaming');
+  const session = (name, meta, text) => {
+    const p = path.join(home, '.codex', 'sessions', '2026', '09', '03', `${name}.jsonl`);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, jsonl([{ type: 'session_meta', payload: meta }, { type: 'event_msg', payload: { type: 'user_message', message: text } }]));
+  };
+  try {
+    session('ide', { originator: 'codex_vscode', source: 'vscode' }, 'typed in the IDE');
+    session('desktop', { originator: 'Codex Desktop', source: 'vscode' }, 'typed in the desktop app');
+    session('tui', { originator: 'codex-tui', source: 'cli' }, 'typed in the terminal');
+    session('from-claude', { originator: 'Claude Code', source: 'vscode' }, 'dispatched by another agent');
+    session('exec', { originator: 'codex_exec', source: 'exec' }, 'an exec lane prompt');
+    session('ide-exec', { originator: 'codex_vscode', source: 'exec' }, 'another exec prompt');
+    session('subagent', { originator: 'codex_vscode', source: { subagent: { thread_spawn: {} } } }, 'a sub-agent prompt');
+    session('no-meta', null, 'a session without metadata');
+    const chat = path.join(appdata, 'Code', 'User', 'workspaceStorage', 'w', 'chatSessions', 's.jsonl');
+    fs.mkdirSync(path.dirname(chat), { recursive: true });
+    fs.writeFileSync(chat, jsonl([{ kind: 0, v: { requests: [
+      { message: { text: '[Terminal 808808ce-309f notification: command completed with exit code 0]' } },
+      { message: { text: 'a real chat prompt' } }] } }]));
+    assert.deepEqual(texts(collect.readSources({ home, appdata })), texts([
+      { text: 'typed in the IDE' }, { text: 'typed in the desktop app' }, { text: 'typed in the terminal' }, { text: 'a real chat prompt' }]));
+  } finally { fs.rmSync(home, { recursive: true, force: true }); }
+});
+
 test('S1-C102 filters, redaction and deduplication', () => {
   assert.equal(collect.keep('go'), true);
   assert.equal(collect.keep('x'.repeat(1024)), true);

package/ci/mechanism-system-one-label.test.js

@@ -89,6 +89,10 @@ test('S1-L05 CLI labels through the configured command, resumes, checks the hold
     const rows = fs.readFileSync(out, 'utf8').trim().split('\n').map(l => JSON.parse(l));
     assert.ok(rows.every(r => r.gold === 'tier2' && r.labeler.model === 'sonnet' && /^[0-9a-f]{16}$/.test(r.labeler.rulesSha256)));
     assert.deepEqual(JSON.parse(cli(['label', '--in', input, '--out', out]).stdout), { labeled: 0, failed: 0, total: 5 });
+    const partial = path.join(dir, 'partial.jsonl');
+    assert.deepEqual(JSON.parse(cli(['label', '--in', input, '--out', partial, '--batch', '2', '--max-batches', '1']).stdout), { labeled: 2, failed: 0, total: 5 });
+    assert.deepEqual(JSON.parse(cli(['label', '--in', input, '--out', partial, '--batch', '2', '--max-batches', '1']).stdout), { labeled: 2, failed: 0, total: 5 }, 'resumes with the next batch');
+    assert.equal(fs.readFileSync(partial, 'utf8').trim().split('\n').length, 4);
     const report = path.join(dir, 'check.json');
     const check = cli(['check-holdout', '--out', report]);
     assert.equal(check.status, 0, check.stderr);

package/docs/system-one-corpus.md

@@ -27,6 +27,10 @@ Rules:
 2. Label the work requested, not the words used. Searching every repository and
    reporting is `tier1`; changing every repository is `tier3`.
 3. Pick the smallest tier that covers the whole request.
+   A question, a confirmation, a discussion point, or a request to restate,
+   reformat or extend the assistant's previous answer without changing files is
+   `tier1`. A requested change to code or configuration, however small, is at
+   least `tier2`. Only the smallest doc fixes listed in the table stay `tier1`.
 4. Explicit workflow words ("use fable", "no subagents") do not change the gold.
    Precedence is a router policy, not a label.
 5. Never derive gold from the lexical router or any model output. A reviewer may

package/docs/system-one-training.md

@@ -42,8 +42,11 @@ The following are dropped:
 - Session-continuation summaries ("This session is being continued…").
 - Empty text.
 
-Codex sessions include prompts that another agent dispatched. They are kept and tagged with
-their source, because Harness routes them in Codex too.
+Codex sessions are kept only when they are interactive, meaning `session_meta` has a
+`source` of `vscode` or `cli` and an originator that is neither `Claude Code` nor
+`codex_exec`. Exec sessions, sub-agent threads and sessions another agent started contain
+prompts written by an agent, not by the owner. VS Code terminal notifications
+(`[Terminal … notification …`) are dropped as well.
 
 ## Filters, families and splits
 
@@ -80,7 +83,9 @@ their source, because Harness routes them in Codex too.
     sessions never become collectable history), `--tools ""` and a JSON schema.
   - The instructions contain the gold table and rules from
     [system-one-corpus.md](system-one-corpus.md).
-  - Prompts go in batches of 100. Every returned index must be labeled exactly once with
+  - Prompts go in batches of 100. `--max-batches N` stops after N batches so a
+    memory-constrained host can label in short foreground runs that resume from the
+    labels already written. Every returned index must be labeled exactly once with
     `tier1`, `tier2`, `tier3` or `null`. A malformed batch is retried once and then
     recorded as failed. It is never partially accepted.
 - **Labeler check**: the labeler labels the 215 holdout prompts once, before any training
@@ -88,9 +93,14 @@ their source, because Harness routes them in Codex too.
   - Labeling proceeds only when agreement is at least 80%.
   - The instructions are never tuned on the holdout. If the check fails, the owner reviews
     the disagreements and decides how to proceed.
-- **Owner spot-check**: a random 5% sample of the labeled training data is reviewed on the
-  review page, and the disagreement rate is reported. The owner's decisions replace the LLM
-  labels for those cases.
+- **Owner spot-check**: a deterministic sample of the labeled training data is reviewed on
+  the review page, and the disagreement rate is reported.
+  - Each case shows the preceding prompts from the same session as read-only context.
+    Without it, short replies read as confirmations: the first spot-check (103 cases,
+    no context) disagreed 51% and was not used to override labels.
+  - A checkpoint may be trained before the spot-check, but it is released only when
+    disagreement is below 20%.
+  - Decisions made with context replace the LLM labels for those cases.
 
 ## Training and calibration
 

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/skills/using-git-worktrees/SKILL.md

@@ -4,44 +4,45 @@ description: Use when work needs isolation or before major implementation plans
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.19.1
+  version: 0.25.1
 ---
 
 # Using Git Worktrees
 
-Use native worktree support first; raw Git is the fallback.
+Use native worktree support first; raw Git is fallback.
 
 ## Contract
 
-- **Tier 3 / Fable (MUST resolve)** — before broad source/artifact mutation, reuse/create a verified linked worktree. If isolation is unavailable or the user explicitly chooses to stay in place, MUST report an explicit degraded fallback/risk before continuing.
-- **Ordinary mode (SHOULD)** — use isolation when it materially reduces collision/risk; explicit user preference may keep work in place.
-- **MUST NOT** nest a worktree inside an already isolated worktree.
+- **Tier 3 / Fable (MUST resolve)** — isolate before broad mutation. If unavailable or explicitly declined, MUST report an explicit degraded fallback/risk.
+- **Ordinary mode SHOULD** isolate when it materially reduces collision/risk.
+- **MUST NOT** nest a worktree inside an isolated worktree.
 
 ## Workflow
 
-**Step 0 — Detect isolation** (adapt per `environment-detection`):
+**Step 0 — Detect**:
 ```bash
 git rev-parse --git-dir
 git rev-parse --git-common-dir
 git branch --show-current
 git rev-parse --show-superproject-working-tree
+git submodule status --recursive
 ```
-Different git/common dirs and no superproject => already isolated; continue to Step 2. A submodule is a normal repo for this check.
+Different git/common dirs and no superproject => already isolated. If submodules exist, **MUST** read `<this-skill-dir>/references/submodules-in-worktrees.md` before committing inside them.
 
-**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree` first; otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Use an already-ignored or external/sibling path when possible. If creation/entry fails, MUST surface the degraded isolation disposition before continuing.
+**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree`; otherwise `git worktree add "$path" -b "$BRANCH_NAME"`. On failure, MUST surface the degraded disposition.
 
-**Step 2 — Setup**: install project dependencies as needed.
+**Step 2 — Setup**: install dependencies as needed.
 
-**Step 3 — Baseline**: run relevant tests/build before implementation when useful; surface existing failures before relying on the baseline.
+**Step 3 — Baseline**: run relevant tests/build when useful; surface existing failures.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md
 
 ## USE FOR:
-- Tier 3 / Fable-class mutable engineering
+- Tier 3 / Fable mutable engineering
 - feature work needing isolation
 - pre-implementation-plan setup
 
 ## DO NOT USE FOR:
 - nesting inside an existing worktree
-- read-only analysis with no mutation
-- branch/merge workflows unrelated to workspace isolation
+- read-only analysis
+- unrelated branch/merge workflows

package/plugins/harness-everything/skills/using-git-worktrees/references/submodules-in-worktrees.md

@@ -0,0 +1,135 @@
+# Submodules inside linked worktrees
+
+A linked worktree of a superproject does **not** share the primary checkout's submodule object store. After `git submodule update --init`, each submodule normally uses a worktree-specific git dir such as:
+
+```text
+<super>/.git/worktrees/<worktree-id>/modules/<submodule>
+```
+
+The primary checkout uses:
+
+```text
+<super>/.git/modules/<submodule>
+```
+
+A superproject gitlink records only a commit SHA. It does not publish or copy that commit into the primary checkout. Therefore a submodule commit made only on detached HEAD in a linked worktree can become unreachable when that worktree is removed.
+
+## Required rules
+
+1. **MUST use a named branch before committing in the submodule.** `git submodule update` normally leaves the submodule detached.
+2. **MUST make the new submodule commit reachable outside the linked worktree before treating the superproject gitlink bump as deliverable.** Publish it to the submodule remote, or fetch it into the primary checkout's submodule repository.
+3. **MUST verify external reachability before removing the linked worktree.** A branch that exists only inside the linked worktree is not sufficient publication evidence.
+
+## Detect the situation
+
+From the superproject worktree:
+
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git submodule status --recursive
+git -C <submodule> rev-parse --absolute-git-dir
+git -C <submodule> branch --show-current
+```
+
+A linked superproject has different git/common dirs. A blank submodule branch means detached HEAD.
+
+PowerShell uses the same Git commands; quote paths containing spaces:
+
+```powershell
+git -C "<submodule>" rev-parse --absolute-git-dir
+git -C "<submodule>" branch --show-current
+```
+
+## Prevent the problem
+
+Before editing or committing in the submodule:
+
+```bash
+git -C <submodule> switch -c <task-branch>
+# edit + verify
+git -C <submodule> add <paths>
+git -C <submodule> commit -m "<message>"
+SUB_SHA=$(git -C <submodule> rev-parse HEAD)
+```
+
+PowerShell:
+
+```powershell
+git -C "<submodule>" switch -c "<task-branch>"
+# edit + verify
+git -C "<submodule>" add <paths>
+git -C "<submodule>" commit -m "<message>"
+$SubSha = git -C "<submodule>" rev-parse HEAD
+```
+
+## Publish before the gitlink is considered deliverable
+
+Preferred path when the submodule has a remote:
+
+```bash
+git -C <submodule> push -u origin <task-branch>
+git -C <submodule> branch -r --contains "$SUB_SHA"
+```
+
+```powershell
+git -C "<submodule>" push -u origin "<task-branch>"
+git -C "<submodule>" branch -r --contains $SubSha
+```
+
+If pushing is not appropriate, copy the commit into the primary checkout's submodule repository. From the linked worktree first give a detached commit a name if necessary:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+```powershell
+git -C "<worktree>/<submodule>" branch -f "<task-branch>" "<sha>"
+git -C "<primary>/<submodule>" fetch "<worktree>/<submodule>" "<task-branch>:<task-branch>"
+git -C "<primary>/<submodule>" cat-file -e "<sha>^{commit}"
+```
+
+After the commit is externally reachable, stage the gitlink in the superproject:
+
+```bash
+git add <submodule>
+git diff --cached --submodule=log
+```
+
+## Recovery after an unpublished gitlink was already committed
+
+Do **not** remove the linked worktree. Recover the referenced SHA while its submodule object store still exists:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+git -C <primary> submodule update
+```
+
+The PowerShell form is identical except paths/refs should be quoted as shown above.
+
+## Pre-removal check
+
+For every changed gitlink SHA, prove at least one external home exists:
+
+```bash
+git -C <submodule> branch -r --contains <sha>
+# OR, from the primary checkout:
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+If neither succeeds, **MUST NOT** remove the linked worktree yet.
+
+## Handoff checklist
+
+For each changed submodule record:
+
+- submodule path
+- commit SHA
+- branch name
+- publication location: remote-tracking ref or primary checkout object store
+- superproject gitlink staged/committed state
+- reachability check result before worktree removal

package/sbom.cdx.json

@@ -2,23 +2,23 @@
   "$schema": "https://cyclonedx.org/schema/bom-1.7.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.7",
-  "serialNumber": "urn:uuid:5f8c3ad1-23b9-55c5-a389-ff6c3877f9dd",
+  "serialNumber": "urn:uuid:fb030470-2601-5f76-9c8c-9e7efeb21a03",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-23T13:40:29.695Z",
+    "timestamp": "2026-09-24T12:40:30.113Z",
     "tools": [
       {
         "vendor": "Harness Everything",
         "name": "generate-sbom.js",
-        "version": "0.24.0"
+        "version": "0.25.1"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/harness-everything@0.24.0",
+      "bom-ref": "pkg:npm/harness-everything@0.25.1",
       "name": "harness-everything",
-      "version": "0.24.0",
-      "purl": "pkg:npm/harness-everything@0.24.0"
+      "version": "0.25.1",
+      "purl": "pkg:npm/harness-everything@0.25.1"
     }
   },
   "components": [
@@ -1999,7 +1999,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/harness-everything@0.24.0",
+      "ref": "pkg:npm/harness-everything@0.25.1",
       "dependsOn": [
         "pkg:npm/%40commitlint/cli@19.8.1",
         "pkg:npm/%40commitlint/config-conventional@19.8.1",

package/scripts/system-one-collect.js

@@ -12,7 +12,9 @@ const REPO = path.resolve(__dirname, '..');
 const MAX_BYTES = 1024;
 const VALIDATION_PERCENT = 15;
 // Whole-text wrappers injected by hosts or hooks; text that starts with one is not typed by the owner.
-const WRAPPER = /^<(environment_context|user_instructions|recommended_plugins|send_user_message_question_reply|command-|local-command|task-notification|bash-|turn_aborted|user_shell_command|skill)/i;
+const WRAPPER = /^(<(environment_context|user_instructions|recommended_plugins|send_user_message_question_reply|command-|local-command|task-notification|bash-|turn_aborted|user_shell_command|skill)|\[Terminal [0-9a-f-]+ notification)/i;
+// Codex sessions typed by the owner: interactive IDE/desktop/terminal ones, not exec lanes, sub-agents or agent-started sessions.
+const interactiveCodex = meta => !!meta && ['vscode', 'cli'].includes(meta.source) && !['Claude Code', 'codex_exec'].includes(meta.originator);
 // Blocks a host inserts inside typed text; they are removed and the rest is kept.
 const INSERTED = /<(system-reminder|ide_[a-z_]+)>[\s\S]*?<\/\1>/gi;
 const sha = text => createHash('sha256').update(text, 'utf8').digest('hex');
@@ -61,12 +63,14 @@ function fromClaude(file) {
   return rows;
 }
 function fromCodex(file) {
-  const events = []; const items = [];
+  const events = []; const items = []; let meta = null;
   for (const line of readLines(file)) {
     const e = parse(line); if (!e || !e.payload) continue;
+    if (e.type === 'session_meta' && !meta) { meta = e.payload; if (!interactiveCodex(meta)) return []; continue; }
     if (e.type === 'event_msg' && e.payload.type === 'user_message') { const t = typed(e.payload.message); if (t) events.push(t); }
     if (e.type === 'response_item' && e.payload.role === 'user') for (const c of e.payload.content || []) { const t = typed(c && c.text); if (t) items.push(t); }
   }
+  if (!interactiveCodex(meta)) return [];
   // Event messages are the typed text; response items repeat it with injected context, so they are a fallback only.
   return events.length ? events : items;
 }

package/scripts/system-one-label.js

@@ -39,9 +39,9 @@ function validateReply(batch, reply) {
   }
   return out;
 }
-async function labelAll(data, { run, rules, batchSize = 100, concurrency = 4, done = new Set(), onBatch = () => {}, onFailure = () => {}, retryDelayMs = 30000 }) {
+async function labelAll(data, { run, rules, batchSize = 100, concurrency = 4, done = new Set(), onBatch = () => {}, onFailure = () => {}, retryDelayMs = 30000, maxBatches = Infinity }) {
   const todo = data.filter(d => !done.has(d.id));
-  const batches = []; for (let i = 0; i < todo.length; i += batchSize) batches.push(todo.slice(i, i + batchSize));
+  const batches = []; for (let i = 0; i < todo.length && batches.length < maxBatches; i += batchSize) batches.push(todo.slice(i, i + batchSize));
   const labeled = []; const failed = []; let next = 0;
   // Every failed attempt is reported with its reason; a thrown run (rate limit, timeout) waits before the retry.
   const attempt = async batch => {
@@ -127,7 +127,8 @@ async function main(argv) {
     const onBatch = rows => fs.appendFileSync(out, rows.map(r => `${JSON.stringify({ ...r, labeler })}\n`).join(''), { mode: 0o600 });
     // Failure log: first ID, size and reason only, never prompt text.
     const onFailure = (batch, reason) => fs.appendFileSync(`${out}.failures.jsonl`, `${JSON.stringify({ firstId: batch[0].id, size: batch.length, reason, at: new Date().toISOString() })}\n`);
-    const { labeled, failed } = await labelAll(data, { run, rules, batchSize, concurrency, done, onBatch, onFailure });
+    const maxBatches = Number(opt('--max-batches', 'Infinity'));
+    const { labeled, failed } = await labelAll(data, { run, rules, batchSize, concurrency, done, onBatch, onFailure, maxBatches });
     console.log(JSON.stringify({ labeled: labeled.length, failed: failed.length, total: data.length }));
   } else if (op === 'check-holdout') {
     const out = opt('--out'); if (!out) throw new Error('check-holdout needs --out');

package/using-git-worktrees/SKILL.md

@@ -4,44 +4,45 @@ description: Use when work needs isolation or before major implementation plans
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.19.1
+  version: 0.25.1
 ---
 
 # Using Git Worktrees
 
-Use native worktree support first; raw Git is the fallback.
+Use native worktree support first; raw Git is fallback.
 
 ## Contract
 
-- **Tier 3 / Fable (MUST resolve)** — before broad source/artifact mutation, reuse/create a verified linked worktree. If isolation is unavailable or the user explicitly chooses to stay in place, MUST report an explicit degraded fallback/risk before continuing.
-- **Ordinary mode (SHOULD)** — use isolation when it materially reduces collision/risk; explicit user preference may keep work in place.
-- **MUST NOT** nest a worktree inside an already isolated worktree.
+- **Tier 3 / Fable (MUST resolve)** — isolate before broad mutation. If unavailable or explicitly declined, MUST report an explicit degraded fallback/risk.
+- **Ordinary mode SHOULD** isolate when it materially reduces collision/risk.
+- **MUST NOT** nest a worktree inside an isolated worktree.
 
 ## Workflow
 
-**Step 0 — Detect isolation** (adapt per `environment-detection`):
+**Step 0 — Detect**:
 ```bash
 git rev-parse --git-dir
 git rev-parse --git-common-dir
 git branch --show-current
 git rev-parse --show-superproject-working-tree
+git submodule status --recursive
 ```
-Different git/common dirs and no superproject => already isolated; continue to Step 2. A submodule is a normal repo for this check.
+Different git/common dirs and no superproject => already isolated. If submodules exist, **MUST** read `<this-skill-dir>/references/submodules-in-worktrees.md` before committing inside them.
 
-**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree` first; otherwise use `git worktree add "$path" -b "$BRANCH_NAME"`. Use an already-ignored or external/sibling path when possible. If creation/entry fails, MUST surface the degraded isolation disposition before continuing.
+**Step 1 — Create/enter**: use native `EnterWorktree`, `/worktree`, or `--worktree`; otherwise `git worktree add "$path" -b "$BRANCH_NAME"`. On failure, MUST surface the degraded disposition.
 
-**Step 2 — Setup**: install project dependencies as needed.
+**Step 2 — Setup**: install dependencies as needed.
 
-**Step 3 — Baseline**: run relevant tests/build before implementation when useful; surface existing failures before relying on the baseline.
+**Step 3 — Baseline**: run relevant tests/build when useful; surface existing failures.
 
 Deep dive: <this-skill-dir>/references/workflow-details.md
 
 ## USE FOR:
-- Tier 3 / Fable-class mutable engineering
+- Tier 3 / Fable mutable engineering
 - feature work needing isolation
 - pre-implementation-plan setup
 
 ## DO NOT USE FOR:
 - nesting inside an existing worktree
-- read-only analysis with no mutation
-- branch/merge workflows unrelated to workspace isolation
+- read-only analysis
+- unrelated branch/merge workflows

package/using-git-worktrees/references/submodules-in-worktrees.md

@@ -0,0 +1,135 @@
+# Submodules inside linked worktrees
+
+A linked worktree of a superproject does **not** share the primary checkout's submodule object store. After `git submodule update --init`, each submodule normally uses a worktree-specific git dir such as:
+
+```text
+<super>/.git/worktrees/<worktree-id>/modules/<submodule>
+```
+
+The primary checkout uses:
+
+```text
+<super>/.git/modules/<submodule>
+```
+
+A superproject gitlink records only a commit SHA. It does not publish or copy that commit into the primary checkout. Therefore a submodule commit made only on detached HEAD in a linked worktree can become unreachable when that worktree is removed.
+
+## Required rules
+
+1. **MUST use a named branch before committing in the submodule.** `git submodule update` normally leaves the submodule detached.
+2. **MUST make the new submodule commit reachable outside the linked worktree before treating the superproject gitlink bump as deliverable.** Publish it to the submodule remote, or fetch it into the primary checkout's submodule repository.
+3. **MUST verify external reachability before removing the linked worktree.** A branch that exists only inside the linked worktree is not sufficient publication evidence.
+
+## Detect the situation
+
+From the superproject worktree:
+
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git submodule status --recursive
+git -C <submodule> rev-parse --absolute-git-dir
+git -C <submodule> branch --show-current
+```
+
+A linked superproject has different git/common dirs. A blank submodule branch means detached HEAD.
+
+PowerShell uses the same Git commands; quote paths containing spaces:
+
+```powershell
+git -C "<submodule>" rev-parse --absolute-git-dir
+git -C "<submodule>" branch --show-current
+```
+
+## Prevent the problem
+
+Before editing or committing in the submodule:
+
+```bash
+git -C <submodule> switch -c <task-branch>
+# edit + verify
+git -C <submodule> add <paths>
+git -C <submodule> commit -m "<message>"
+SUB_SHA=$(git -C <submodule> rev-parse HEAD)
+```
+
+PowerShell:
+
+```powershell
+git -C "<submodule>" switch -c "<task-branch>"
+# edit + verify
+git -C "<submodule>" add <paths>
+git -C "<submodule>" commit -m "<message>"
+$SubSha = git -C "<submodule>" rev-parse HEAD
+```
+
+## Publish before the gitlink is considered deliverable
+
+Preferred path when the submodule has a remote:
+
+```bash
+git -C <submodule> push -u origin <task-branch>
+git -C <submodule> branch -r --contains "$SUB_SHA"
+```
+
+```powershell
+git -C "<submodule>" push -u origin "<task-branch>"
+git -C "<submodule>" branch -r --contains $SubSha
+```
+
+If pushing is not appropriate, copy the commit into the primary checkout's submodule repository. From the linked worktree first give a detached commit a name if necessary:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+```powershell
+git -C "<worktree>/<submodule>" branch -f "<task-branch>" "<sha>"
+git -C "<primary>/<submodule>" fetch "<worktree>/<submodule>" "<task-branch>:<task-branch>"
+git -C "<primary>/<submodule>" cat-file -e "<sha>^{commit}"
+```
+
+After the commit is externally reachable, stage the gitlink in the superproject:
+
+```bash
+git add <submodule>
+git diff --cached --submodule=log
+```
+
+## Recovery after an unpublished gitlink was already committed
+
+Do **not** remove the linked worktree. Recover the referenced SHA while its submodule object store still exists:
+
+```bash
+git -C <worktree>/<submodule> branch -f <task-branch> <sha>
+git -C <primary>/<submodule> fetch <worktree>/<submodule> <task-branch>:<task-branch>
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+git -C <primary> submodule update
+```
+
+The PowerShell form is identical except paths/refs should be quoted as shown above.
+
+## Pre-removal check
+
+For every changed gitlink SHA, prove at least one external home exists:
+
+```bash
+git -C <submodule> branch -r --contains <sha>
+# OR, from the primary checkout:
+git -C <primary>/<submodule> cat-file -e <sha>^{commit}
+```
+
+If neither succeeds, **MUST NOT** remove the linked worktree yet.
+
+## Handoff checklist
+
+For each changed submodule record:
+
+- submodule path
+- commit SHA
+- branch name
+- publication location: remote-tracking ref or primary checkout object store
+- superproject gitlink staged/committed state
+- reachability check result before worktree removal