feat(meta-mode): harden portable workflow tooling

README.md

@@ -115,6 +115,7 @@ The available installable artifacts are:
 | `agents` | Codex: `$CODEX_HOME/agents/` as TOML; other harnesses: their native `agents/` directory as Markdown |
 | `meta-mode-tools` | `tools/meta-mode/` beside the resolved skill root; shared consumers use `~/.agents/tools/meta-mode/` |
 | `guide` | `docs/guide/` beside the resolved skill root |
+| `session-context` | `session-context/` beside the resolved skill root; plain-text routing guidance, never implicit |
 
 Codex skills default to `~/.agents/skills/`, while Codex agents default to
 `~/.codex/agents/`. An unset or empty `CODEX_HOME` uses `~/.codex`.
@@ -155,7 +156,11 @@ reviewed and copied into a project repository's committed
 `.cursor/automations/benny/` directory using its own setup instructions.
 mstack does not ship portable `commands/`, `hooks/`, or `settings/` trees:
 those are harness- and project-owned configuration surfaces and must be
-written or merged explicitly by the user.
+written or merged explicitly by the user. The optional `session-context`
+artifact is plain-text guidance only; select it with `--artifact session-context`
+and configure the harness's own session surface explicitly. It does not register
+a startup hook, grant permissions, or make session routing implicit. Hooks remain
+unsupported unless explicitly configured outside mstack.
 
 ## Choose installation directories
 
@@ -386,7 +391,7 @@ workflow even when no native skill creator or repository validator is installed.
 - `automations/benny/` keeps the optional Cursor automation pack from pstack.
 - `docs/guide/` contains the adapted upstream workflow guide.
 - `tools/meta-mode/` contains the optional Bun orchestration and PR watcher
-  tools.
+  tools, plus the project-playbook checker.
 - `scripts/install.mjs` stages, validates, and commits an installation.
 - `scripts/remote-install.mjs` stages and transfers an SSH environment install.
 - `scripts/validate.mjs` checks inventory, frontmatter, links, and portability.
@@ -461,6 +466,18 @@ review the source-to-adaptation patches, then use `--write` to update
 content changes. The hashes detect drift; they do not establish that an adapted
 workflow behaves like its source. See [the baseline review process](docs/skill-integrity.md).
 
+To validate project playbooks that extend the bundled `meta-mode` playbooks, run:
+
+```bash
+node tools/meta-mode/check-playbooks.mjs <project-root>
+```
+
+A project playbook belongs in `<project-root>/.agents/playbooks/`. Its frontmatter
+must contain `when:` and may contain a comma-separated `extends:` list. Changes
+must quote the exact bundled step they anchor to with `After`, `Before`, `Replace`,
+or `In`. Use `--bundled <path>` when checking a staged skill installation instead
+of this checkout.
+
 To compare the pstack inventory and non-skill artifacts, run:
 
 ```bash

docs/guide/03-understand.md

@@ -46,7 +46,7 @@ When another agent (or you, last week) left a branch mid-flight:
 /meta-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work.
 ```
 
-The [Session pickup playbook](../../skills/meta-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch.
+The [Session pickup playbook](../../skills/meta-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It first reads the latest project-local checkpoint with `node tools/meta-mode/resume.mjs read --project .`, follows its note and evidence paths, reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch. Checkpoints live under Git metadata, so this workflow does not depend on a particular Harness or vendor path.
 
 **Pitfall:** don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. `/how` first is cheaper than the second bug.
 

docs/session-context/SESSION-CONTEXT.md

@@ -0,0 +1,32 @@
+# Optional session context
+
+This file is an explicit, user-selected routing artifact for sessions that should
+start with mstack's `/meta-mode` workflow. Load or reference it from the active
+harness configuration when you want that behavior; the mstack installer never
+registers it as a hook, startup command, or implicit instruction.
+
+## Opt-in contract
+
+1. Select this artifact explicitly with `--artifact session-context`.
+2. Configure the active harness to read this file using its documented,
+   user-owned session or project configuration surface.
+3. Confirm the harness configuration and review the file before using it in a
+   sensitive repository.
+
+When loaded, route the user's request through `/meta-mode` at session start.
+Keep routing advisory: do not execute commands, modify files, install hooks, or
+send data without the harness's normal approval and tool policy. If the file is
+not explicitly selected and configured, do nothing.
+
+## Security and portability boundary
+
+This is plain text, not executable configuration. It does not grant tools,
+permissions, network access, or persistence. Harnesses differ in whether they
+support session context, startup instructions, or project configuration, so
+mstack does not provide an adapter that silently wires this file into any of
+them. A harness-specific integration must be configured and reviewed by the
+user. Hooks remain unsupported unless explicitly configured outside mstack.
+
+Do not put secrets, credentials, transcript contents, or machine-specific paths
+in this file. Keep the canonical skill tree Harness-neutral; this artifact is a
+separate optional boundary for users who choose session routing.

package.json

@@ -20,6 +20,8 @@
     "check-models": "node scripts/model-config.mjs",
     "model-budget": "node scripts/model-budget.mjs",
     "check-upstream": "node scripts/check-upstream.mjs",
+    "check-playbooks": "node tools/meta-mode/check-playbooks.mjs",
+    "audit-worktrees": "node tools/meta-mode/worktree-audit.mjs",
     "check-harness-policy": "node scripts/check-harness-policy.mjs",
     "skill-baseline": "node scripts/skill-baseline.mjs",
     "run-role": "node scripts/run-role.mjs",
@@ -30,7 +32,7 @@
     "install-skills": "node scripts/install.mjs",
     "optimize-context": "node scripts/optimize-context.mjs",
     "reconcile-context": "node scripts/reconcile-context.mjs",
-    "test": "node scripts/validate.mjs && node scripts/skill-baseline.mjs --check && node --test scripts/install.test.mjs scripts/install-migration.test.mjs scripts/migration-integration.test.mjs scripts/skill-discovery.test.mjs scripts/harness-targets.test.mjs scripts/remote-discovery.test.mjs scripts/context.test.mjs scripts/model-config.test.mjs scripts/model-budget.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs scripts/skill-integrity.test.mjs scripts/skill-baseline.test.mjs scripts/version-integrity.test.mjs scripts/agent-format.test.mjs scripts/history.test.mjs scripts/harness-policy.test.mjs scripts/harness-project.test.mjs scripts/check-upstream-adaptations.test.mjs scripts/pack-claude-skills.test.mjs"
+    "test": "node scripts/validate.mjs && node scripts/skill-baseline.mjs --check && node --test scripts/install.test.mjs scripts/install-migration.test.mjs scripts/migration-integration.test.mjs scripts/skill-discovery.test.mjs scripts/harness-targets.test.mjs scripts/remote-discovery.test.mjs scripts/context.test.mjs scripts/model-config.test.mjs scripts/model-budget.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs scripts/skill-integrity.test.mjs scripts/skill-baseline.test.mjs scripts/version-integrity.test.mjs scripts/agent-format.test.mjs scripts/history.test.mjs scripts/harness-policy.test.mjs scripts/harness-project.test.mjs scripts/check-upstream-adaptations.test.mjs scripts/check-playbooks.test.mjs scripts/pack-claude-skills.test.mjs"
   },
   "bin": {
     "mstack": "scripts/install.mjs",

profiles/artifacts.json

@@ -22,6 +22,11 @@
       "path": ["docs", "guide"],
       "description": "The adapted mstack workflow guide and its images."
     },
+    "session-context": {
+      "source": "docs/session-context",
+      "path": ["session-context"],
+      "description": "Optional plain-text session routing guidance; never installed implicitly or registered as a hook."
+    },
     "benny": {
       "source": "automations/benny",
       "installable": false,

profiles/skill-manifest.json

@@ -5,6 +5,11 @@
     "mattpocock/skills": "6654f6b60cd9d5be8b54c6fafe44346dabeb3b76"
   },
   "files": {
+    "scripts/worktree-audit.test.mjs": {
+      "upstream": null,
+      "reason": "Focused portability and safety behavior tests for the worktree audit.",
+      "targetDigest": "2b854de22c6029cd6746932b81be93d4eff23a29618d4a7624cf76b7f481b330"
+    },
     "skills/architect/references/design-red-flags.md": {
       "upstream": "pstack",
       "source": "skills/architect/references/design-red-flags.md",
@@ -266,13 +271,13 @@
       "upstream": "pstack",
       "source": "skills/poteto-mode/playbooks/orchestrate.md",
       "sourceDigest": "d42b4375f1bd4ce23da0b575a198571a2117df7eea10c3c9fc6d92ae1053f7be",
-      "targetDigest": "c25dcc2662e15ccb91ff19fbe1a156b7fb97d7d49d0c3478dcd9f001e643e398"
+      "targetDigest": "eb7b5b4d8d3f6366546216d136afe6f3028cac3e31ac897a69af64aa463815b3"
     },
     "skills/meta-mode/playbooks/pause-safely.md": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/playbooks/pause-safely.md",
       "sourceDigest": "7d5fc10e144265f1b35f8157926541e738c1de64b6a85b3e61b51cf268c3dffd",
-      "targetDigest": "77968cfe5f4a71a8cd33e0ae8ffcdbd88dd693a212c240457773e6c40c96c21d"
+      "targetDigest": "0deee327d325a4c175614d3df581f388fbcbeb5c67dfc62a8ba517937a5b3338"
     },
     "skills/meta-mode/playbooks/perf-issue.md": {
       "upstream": "pstack",
@@ -302,13 +307,13 @@
       "upstream": "pstack",
       "source": "skills/poteto-mode/playbooks/session-pickup.md",
       "sourceDigest": "1604fb463f7c7410d43fa024ca76c1c1824c166a01fd69d61f073d06fdca2a47",
-      "targetDigest": "97a3d7b0fcecf53c5c3fce9ec17f105196745086911c363d2dc7841bc56e40e2"
+      "targetDigest": "7ea205c7394469d61c9a4f234be7f7a426044412ecdb210bc08d43ef7cb554fe"
     },
     "skills/meta-mode/playbooks/shipping.md": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/playbooks/shipping.md",
       "sourceDigest": "c301902136e0a9a0a55403c35374f6f5738e501aee66c27458dc197b87557550",
-      "targetDigest": "0102de98f44f1b9921352fe60dbd3789710985bed2a491fd033bf012a1a812b2"
+      "targetDigest": "d898c5b32402a3e22a213311d33527423c57cb81b050c8e1e36d42cd2d85a24c"
     },
     "skills/meta-mode/playbooks/trace-forensics.md": {
       "upstream": "pstack",
@@ -326,7 +331,7 @@
       "upstream": "pstack",
       "source": "skills/poteto-mode/playbooks/worktree-cleanup.md",
       "sourceDigest": "fc464dc4121926df1704f483c5feca83717c0a40b4651d3e11bd3aedd89441b6",
-      "targetDigest": "db0c8eeef5dc5054e79c1b3b8215159f48e12a4fb81225d551080f8773fe1b2c"
+      "targetDigest": "7963871a1ba7f31929502a864133fad4e20ac4ba62deafee38470f7a5e4e0332"
     },
     "skills/meta-mode/references/bugbot-triage.md": {
       "upstream": "pstack",
@@ -348,7 +353,7 @@
       "upstream": "pstack",
       "source": "skills/poteto-mode/SKILL.md",
       "sourceDigest": "b3c505602b82fb3641a3983e9c46fb974881faa12ece1af804fae27afb7be532",
-      "targetDigest": "4efa5f64e1f6bd01fd08eb6fb720ab4c84c7f3d787fff9df71d0e07ab65b73fe"
+      "targetDigest": "7b536c7484e19cf426e3f382ee58143678bb8c94c1bab33b0b89f1f9b2d62d96"
     },
     "skills/no-comments/SKILL.md": {
       "upstream": "pstack",
@@ -718,25 +723,30 @@
       "targetDigest": "ddcdb05af01b37d7513b2017d44e29c30bdaa79ca360c5913d701c16dde70907",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
+    "tools/meta-mode/check-playbooks.mjs": {
+      "upstream": null,
+      "reason": "Local portability guidance or implementation; review alongside its owning skill.",
+      "targetDigest": "f9d19c79e28ec3ca07626b2f963f2f2de8867c52ad2779f115c3620729a898cf"
+    },
     "tools/meta-mode/orch/orch.test.ts": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/scripts/orch/orch.test.ts",
       "sourceDigest": "174b86d21ff51ccd28d1a8c938cb2e0c6fa287b209d4ca6c03932fcb1b53372e",
-      "targetDigest": "913d5c03ba456de547ec609458a2b14c5a3894d33385b0597ee44315252f870b",
+      "targetDigest": "c0077ee0b31d46a6a6b2b2f3a1391a947d44cd7d636f29969dd0c826fc79e722",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
     "tools/meta-mode/orch/orch.ts": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/scripts/orch/orch.ts",
       "sourceDigest": "f091687df627a0b75fabd54af58945a9cd6c7039ef0622012ac9ed60cd8ec434",
-      "targetDigest": "f091687df627a0b75fabd54af58945a9cd6c7039ef0622012ac9ed60cd8ec434",
+      "targetDigest": "b820c51d3ed13fa62ef5fc969aacf2b0b3c7f471a518f6159d3c3a530a363cd7",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
     "tools/meta-mode/orch/store.ts": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/scripts/orch/store.ts",
       "sourceDigest": "0eae7cf69282e827b1227166f2e32cee3560f2f3e65b3f1f2faf6fb83d3b4c5b",
-      "targetDigest": "39394893aa8191f411a5eee33a554a6232e4568ecf11d7b43f6a21752d4c97cd",
+      "targetDigest": "9e2dbb4d8b41b004a50e2317e6c0fee13da366291821e517108cf323de4ddd65",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
     "tools/meta-mode/package.json": {
@@ -746,10 +756,30 @@
       "targetDigest": "c7ac7fd69bb925415cdc15cd636567304ee40f8d665986e45ed8c0ee658f6caf",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
+    "tools/meta-mode/pr-safety.mjs": {
+      "upstream": null,
+      "reason": "Portable meta-mode runtime tool and focused behavior tests.",
+      "targetDigest": "12c7e37f6148146cf9e5e0cd647f363f01a57e5084627eec72b5e2170c743e77"
+    },
+    "tools/meta-mode/pr-safety.test.mjs": {
+      "upstream": null,
+      "reason": "Portable meta-mode runtime tool and focused behavior tests.",
+      "targetDigest": "c30334f2f837725fba92798d97250dea1dcab8846640a2da894e17135f2a2d33"
+    },
     "tools/meta-mode/README.md": {
       "upstream": null,
       "reason": "Local portability guidance or implementation; review alongside its owning skill.",
-      "targetDigest": "c27f30aa0fa15655a9c8dbd9df698a2c69393778bbe516ad5ebdf82ca0de71bd"
+      "targetDigest": "6957647e879f5cd85386a50fb4fa7fb9d83c6179f6e55d7b9e0d1a33f3912812"
+    },
+    "tools/meta-mode/resume.mjs": {
+      "upstream": null,
+      "reason": "Portable meta-mode runtime tool and focused behavior tests.",
+      "targetDigest": "57c3b067f69ce36d30b9a6c5df0f8cbf2c0cef46777eb4d3c7e40b62f087ec72"
+    },
+    "tools/meta-mode/resume.test.mjs": {
+      "upstream": null,
+      "reason": "Portable meta-mode runtime tool and focused behavior tests.",
+      "targetDigest": "2ed58fbbff1486f7ad0faf0550a825ad4648775b3a12743936247fdb2fbd54eb"
     },
     "tools/meta-mode/watch-pr/cli.test.ts": {
       "upstream": "pstack",
@@ -835,17 +865,17 @@
       "targetDigest": "d955603be6cc0e8b8ffcec722f635192b2261410b1f2929abea94480e47eb5d4",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
     },
+    "tools/meta-mode/worktree-audit.mjs": {
+      "upstream": null,
+      "reason": "Local cross-platform implementation replacing shell-specific audit behavior.",
+      "targetDigest": "f87b0b438dcd6d23c29512b3cc70af1a35049db841d5069298456bf11818281d"
+    },
     "tools/meta-mode/worktree-audit.sh": {
       "upstream": "pstack",
       "source": "skills/poteto-mode/scripts/worktree-audit.sh",
       "sourceDigest": "95b8530f3c0ccada8cabc4b0727c052fbc85c141531375aaace65c427af8aecc",
-      "targetDigest": "68df230b34f10558e021bb6cc9696e4653acc92645a17b35c6b953aa40837fc2",
+      "targetDigest": "6a87d48f5664868537d722e059d4a3807a1283cc0382ec01e7d5f764098dbdbf",
       "reason": "Runtime tools are packaged separately from portable skill instructions."
-    },
-    "tools/meta-mode/worktree-audit.test.sh": {
-      "upstream": null,
-      "reason": "Local portability guidance or implementation; review alongside its owning skill.",
-      "targetDigest": "dfc8c11e867f5000a996e8b4aeafc630319964bb1b2946b1a626996dd4919e0f"
     }
   },
   "omitted": {

profiles/upstream-manifest.json

@@ -109,7 +109,7 @@
     },
     "meta-mode": {
       "source": "d5817d996f6da294c86cacb2bd1b0c40c85968844a6afd194fe69efa8654878f",
-      "target": "4efa5f64e1f6bd01fd08eb6fb720ab4c84c7f3d787fff9df71d0e07ab65b73fe"
+      "target": "7b536c7484e19cf426e3f382ee58143678bb8c94c1bab33b0b89f1f9b2d62d96"
     },
     "no-comments": {
       "source": "5c5b0882297d704c3a9720c52b7a793c68b013eaf717989f0945624efdfe2b05",