instar 1.3.261 → 1.3.263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.261",
+  "version": "1.3.263",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/assemble-next-md.mjs

@@ -91,9 +91,15 @@ export function parseBumpType(content) {
  * is internal-only (see assembleNextMd). The pre-push gate independently verifies
  * the marker against the staged diff (an internal-only fragment whose PR touches
  * runtime `src/` is rejected), so the marker cannot be misused.
+ *
+ * The marker is recognized ONLY as a standalone directive line (like the
+ * `<!-- bump: -->` line) — never an inline mention inside prose or backticks. A
+ * fragment that merely DOCUMENTS the lane (e.g. this lane's own docs fragment,
+ * which quotes the literal `<!-- internal-only -->` marker in backticks) must not
+ * be misread as USING it and trip the §3c src-conflict gate.
  */
 export function hasInternalOnlyMarker(content) {
-  return /<!--\s*internal-only\s*-->/i.test(String(content));
+  return /^[ \t]*<!--\s*internal-only\s*-->[ \t]*$/im.test(String(content));
 }
 
 /** Canonical text auto-filled into the user-facing sections of an all-internal release. */

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T01:20:58.426Z",
-  "instarVersion": "1.3.261",
+  "generatedAt": "2026-06-05T02:04:35.056Z",
+  "instarVersion": "1.3.263",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1530,7 +1530,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.262.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Documented the internal-only release-note lane in the bundled instar-dev skill and added a PostUpdateMigrator backfill so existing agents with stock deployed copies receive the same guidance after update.
+
+The new skill section explains the `<!-- internal-only -->` fragment marker, the ability to omit the two user-facing release-note sections, the assembler's all-internal-only auto-fill rule, and the pre-push gate that rejects the marker when runtime `src/*.ts` files changed.
+
+## What to Tell Your User
+
+Nothing changes in normal product behavior. This update improves the development workflow so agents know when the internal-only release-note lane is valid and existing agents receive that guidance automatically.
+
+## Summary of New Capabilities
+
+Existing agents with stock instar-dev skill installs now learn the internal-only release-note lane through the post-update migration path instead of waiting for a fresh install.
+
+## Evidence
+
+- Added a focused PostUpdateMigrator unit test covering update, idempotency, customized-skill preservation, and missing-skill no-op behavior.
+- Ran the existing build-location migration test and the new internal-only-lane migration test together: 8 tests passed.

package/upgrades/1.3.263.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The generated `src/data/builtin-manifest.json` is no longer committed to git. It was a build artifact (produced by `scripts/generate-builtin-manifest.cjs` during `npm run build` and `prepublishOnly`) that, because every skill/hook PR regenerates it, conflicted on a fast-moving main almost every time main advanced — an unwinnable resolve→CI→re-conflict loop (one docs PR hit it 5×). It is now `.gitignore`d and untracked. The published package still ships it (the `.npmignore` allowlist, not `.gitignore`, governs packing — verified with `npm pack --dry-run`), the build regenerates it before publish, the sole runtime reader already degrades gracefully if it's absent, and the one test that reads it now self-generates it in a `beforeAll`. Net: future skill/hook PRs stop fighting this file; build/publish/CI are unchanged.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `npm pack --dry-run` (with the file gitignored) still lists `src/data/builtin-manifest.json` (61.4kB) in the tarball — the `.npmignore` allowlist governs packing.
+- `vitest run tests/unit/builtin-manifest.test.ts` after deleting the file: regenerates it in `beforeAll`, all 9 assertions pass.
+- `tsc --noEmit` clean; `no-silent-fallbacks` ratchet unchanged.

package/upgrades/side-effects/instar-dev-internal-only-lane-docs.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — instar-dev internal-only release-note lane docs
+
+**Version / slug:** `instar-dev-internal-only-lane-docs`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change documents PR #765's internal-only release-note lane in the bundled `/instar-dev` skill and adds a PostUpdateMigrator backfill so existing deployed stock skill copies receive the same guidance.
+
+The skill text documents four operational facts grounded in #765: `<!-- internal-only -->` opts a fragment into the lane, the marker lets the fragment omit `What to Tell Your User` and `Summary of New Capabilities`, the shared assembler auto-fills those sections only when every contributing fragment is internal-only, and the pre-push gate rejects the marker when runtime `src/*.ts` files changed.
+
+## Decision-point inventory
+
+- `/instar-dev` skill text — modify — teaches agents when the internal-only lane is valid.
+- `PostUpdateMigrator` built-in skill migration — modify — copies the bundled stock skill into existing stock deployed copies when the new marker is missing.
+- Release gates — `hasInternalOnlyMarker` (`scripts/assemble-next-md.mjs`) hardened to match the marker only as a standalone directive line (see §8); pre-push behavior otherwise unchanged.
+
+---
+
+## 1. Over-block
+
+The migration may skip a deployed instar-dev skill that is structurally stock but lacks the conservative fingerprint (`# /instar-dev` and `### Phase 2 — Planning`). That is acceptable because the alternative is clobbering customized local workflows. Fresh installs still receive the bundled skill.
+
+---
+
+## 2. Under-block
+
+This does not enforce correct use of the internal-only marker beyond documenting the already-merged pre-push gate. An agent can still misunderstand the lane, but the guidance now lives in the skill at the point where agents prepare release fragments.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The skill is the right documentation layer because `/instar-dev` owns the release-fragment workflow. PostUpdateMigrator is the right deployment layer because installed skills are untracked agent-local files; package updates alone do not rewrite existing copies.
+
+---
+
+## 4. Signal vs authority compliance
+
+- [x] No new authority is introduced.
+
+This PR changes documentation and migration parity only. The objective authority remains PR #765's existing pre-push gate, which checks the marker against the diff.
+
+---
+
+## 5. Interactions
+
+- **#760 migration:** This mirrors the existing build-location skill migration but uses a new marker phrase, so both migrations are independently idempotent.
+- **Fresh installs:** `installBuiltinSkills` gets the updated bundled skill directly.
+- **Existing installs:** PostUpdateMigrator rewrites only stock deployed copies missing the new phrase.
+- **Customized installs:** The conservative fingerprint check leaves them untouched.
+
+---
+
+## 6. External surfaces
+
+The visible surface is limited to development agents reading `/instar-dev`. End-user behavior does not change. Existing agents with stock skill installs will see the new guidance after update.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal code revert. Agents that already received the updated skill keep a harmless documentation section until a later migration rewrites the file. There is no persistent database migration.
+
+---
+
+## Conclusion
+
+The change closes the deploy-awareness half of #765 without changing the ship-lane mechanism itself. The main risk is overwriting customized skills, and the migration avoids that by using the same conservative content-sniffing pattern as #760.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+This touches development-skill documentation and an idempotent post-update skill migration. It does not alter session lifecycle, messaging gates, sentinels, or runtime block/allow decisions.
+
+---
+
+## 8. Marker-detection hardening (surfaced while building this PR)
+
+Building this docs PR surfaced a false-positive in `hasInternalOnlyMarker`
+(`scripts/assemble-next-md.mjs`): the matcher used a whole-content regex, so a
+fragment that merely *documents* the `<!-- internal-only -->` marker in prose (as
+this PR's own release fragment does, quoting the literal marker in backticks) was
+misread as *using* the internal-only lane — and tripped its own §3c src-conflict
+gate (this PR touches `PostUpdateMigrator.ts`). Hardened the matcher to recognize
+the marker ONLY as a standalone directive line (like `<!-- bump: -->`), never an
+inline/backtick mention. Pure script + test change; no `src/` runtime surface.
+Behavior for genuine internal-only fragments (marker on its own line) is unchanged
+— all three prior `detects the marker` assertions stay green. Regression test
+added (`does NOT detect an inline/backtick mention…`).
+
+---
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/migrate-instar-dev-build-location.test.ts tests/unit/migrate-instar-dev-internal-only-lane.test.ts`
+- `npm test -- --run tests/unit/assemble-next-md.test.ts tests/unit/pre-push-gate.test.ts` (47 tests — marker false-positive regression)

package/upgrades/side-effects/manifest-gitignore-end-conflict-loop.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — gitignore the generated builtin-manifest (end the conflict loop)
+
+**Version / slug:** `manifest-gitignore-end-conflict-loop`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (internal dev-workflow change, no runtime/user surface)`
+
+## Summary of the change
+
+`src/data/builtin-manifest.json` is a GENERATED build artifact (`scripts/generate-builtin-manifest.cjs`, run as the first step of `npm run build` and again by `prepublishOnly`) that was nevertheless committed to git. Because every skill/hook PR regenerates it, it conflicted on git on a fast-moving main almost every time main advanced — a structural, unwinnable resolve→CI→re-conflict loop (one docs PR hit it 5×). This change stops committing it: adds it to `.gitignore`, `git rm --cached`s it (file stays on disk), and makes the single test that reads it self-generate it if absent.
+
+## Decision-point inventory
+
+1. **`.gitignore`** — add `src/data/builtin-manifest.json`. The conflict becomes impossible because nothing commits the file.
+2. **`git rm --cached src/data/builtin-manifest.json`** — untrack it; the on-disk file is untouched.
+3. **`tests/unit/builtin-manifest.test.ts`** — `beforeAll` regenerates the file if missing (it's the only test that reads it).
+
+## 1. Publish path (does the package still ship the manifest?)
+
+YES — verified. A `.npmignore` EXISTS, so npm uses `.npmignore` (not `.gitignore`) when packing; the manifest is not in `.npmignore`, so it remains in the tarball. Confirmed with `npm pack --dry-run` after gitignoring: the tarball still lists `src/data/builtin-manifest.json` (61.4kB). `prepublishOnly: npm run build` regenerates it before publish, so it always exists at pack time. No package.json `files` change needed.
+
+## 2. Runtime path (does anything break if the file is missing?)
+
+NO — `CapabilityMapper.loadBuiltinManifest()` is the only runtime reader; it guards with `if (fs.existsSync(...))` inside a try/catch and `return {}` otherwise — a missing manifest degrades to an empty capability map, never a crash. (Pre-existing behavior, unchanged.)
+
+## 3. Test/CI path
+
+- `builtin-manifest.test.ts` is the only test reading the file; it now regenerates it in `beforeAll`. Verified: `rm` the file → run the test → it regenerates and all 9 assertions pass.
+- CI's "Build" job runs `npm run build` (regenerates the manifest); the unit-test job's `builtin-manifest.test.ts` self-generates. No CI step asserts a clean git tree against the committed manifest, so removing it eliminates (rather than introduces) a drift-failure class.
+- The other files matching "builtin-manifest" in tests reference the unrelated playbook `builtin-manifests/` directory, not this file.
+
+## 4. Reversibility
+
+Fully reversible: `git add -f src/data/builtin-manifest.json`, drop the `.gitignore` line, revert the test `beforeAll`. No state, no format, no migration.
+
+## 5. Blast radius
+
+`.gitignore` (1 line + comment), `tests/unit/builtin-manifest.test.ts` (a `beforeAll`), and the untracking of one generated JSON. NO runtime `src/*.ts` change. Build/publish/CI behavior is identical because the file is still produced at build time.
+
+## Evidence pointers
+
+- `npm pack --dry-run` (with the file gitignored) lists `src/data/builtin-manifest.json` in the tarball.
+- `node_modules/.bin/vitest run tests/unit/builtin-manifest.test.ts` after `rm`-ing the file: 9 passed; file regenerated.
+- `tsc --noEmit` clean; `no-silent-fallbacks` ratchet unchanged (no src catches touched).