instar 0.28.125 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.125",
+  "version": "1.0.8",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/resolve-publish-version.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * resolve-publish-version — reconcile package.json (operator authority) with
+ * the npm registry (shipped truth) and print the version the release workflow
+ * should publish.
+ *
+ * Added 2026-05-19 after the v1.0.0 deployment misalignment incident
+ * (docs/incidents/2026-05-19-v1-deployment-misalignment.md). The old workflow
+ * always derived the next version from npm and ignored package.json, which
+ * made an operator-intended major bump structurally impossible. That is the
+ * exact failure this script closes.
+ *
+ * Policy:
+ *   LOCAL  > NPM  → publish at LOCAL (operator-intended leap: major/minor/
+ *                   explicit-patch jump). This is how a v1.0.0 cut happens.
+ *   LOCAL == NPM  → routine patch: NPM with patch+1. The common case — a PR
+ *                   that does not touch package.json leaves LOCAL equal to the
+ *                   last released version.
+ *   LOCAL  < NPM  → stale package.json (a queued run that landed after an
+ *                   earlier publish already bumped). Never downgrade — NPM
+ *                   with patch+1.
+ *
+ * Usage:
+ *   node scripts/resolve-publish-version.mjs <localVersion> <npmVersion>
+ *   → prints the resolved version to stdout, nothing else.
+ *
+ * Exported as a function for unit testing.
+ */
+
+/**
+ * @param {string} a semver "x.y.z"
+ * @param {string} b semver "x.y.z"
+ * @returns {"gt"|"eq"|"lt"} a compared to b
+ */
+export function compareSemver(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 'gt';
+    if (x < y) return 'lt';
+  }
+  return 'eq';
+}
+
+/**
+ * @param {string} localVersion package.json version
+ * @param {string} npmVersion `npm view instar version` (or "0.0.0" if unpublished)
+ * @returns {{version: string, reason: "operator-intended"|"routine-patch"}}
+ */
+export function resolvePublishVersion(localVersion, npmVersion) {
+  const cmp = compareSemver(localVersion, npmVersion);
+  if (cmp === 'gt') {
+    return { version: localVersion, reason: 'operator-intended' };
+  }
+  const [major, minor, patch] = String(npmVersion).split('.').map(Number);
+  return {
+    version: `${major || 0}.${minor || 0}.${(patch || 0) + 1}`,
+    reason: 'routine-patch',
+  };
+}
+
+// CLI entrypoint — only runs when invoked directly, not when imported.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [, , localVersion, npmVersion] = process.argv;
+  if (!localVersion || !npmVersion) {
+    console.error('usage: resolve-publish-version.mjs <localVersion> <npmVersion>');
+    process.exit(2);
+  }
+  const { version } = resolvePublishVersion(localVersion, npmVersion);
+  process.stdout.write(version);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-19T17:35:42.321Z",
-  "instarVersion": "0.28.125",
+  "generatedAt": "2026-05-19T19:32:42.283Z",
+  "instarVersion": "1.0.8",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {

package/upgrades/1.0.8.md

@@ -1,40 +1,93 @@
-# Upgrade Guide — v1.0.8
+# Upgrade Guide — v1.0.8 (the v1.0 milestone)
 
 <!-- bump: patch -->
 
 ## What Changed
 
-Restores Migration Parity §4 conformance for canonical (built-in) hooks. The Hook primitive shipped in PR #253 with a stamp-and-refuse-on-conflict pattern that resurrected the install-if-missing wedge §4 was written to prevent. This release inverts the policy so that built-in hooks are once again always overwritten on every migration run.
-
-Three small code changes:
-
-- The ParityRule interface gained an optional alwaysOverwrite field.
-- hookParityRule sets alwaysOverwrite to true.
-- FrameworkParitySentinel honors alwaysOverwrite and emits a new parity:user-edit-overwritten audit event when overwriting a user-edited rendering.
-
-The user-edit detection stays as a signal in verify output; only the blocking authority moves from the rule to the higher-context Migration Parity policy. skillParityRule does NOT opt in because Migration Parity §5 explicitly carves out skills as refuse-on-conflict with PostUpdateMigrator override.
+This is the official v1.0 milestone release. Two things land together because
+they are causally linked:
+
+1. **Versioning is now truthful.** The release workflow honors the version in
+   `package.json` as the operator's authority for an intended release. It used
+   to derive the next version solely from the npm registry and ignore
+   `package.json`, which made a deliberate major/minor release structurally
+   impossible. That gap is the documented root cause of the 2026-05-19
+   deployment misalignment, where v1.0 framework-parity work shipped to npm
+   under v0.28.x patch numbers. The release that makes truthful versioning
+   possible is, fittingly, the release that stamps v1.0.
+
+2. **The v1.0 milestone is the framework-portability architecture.** Instar is
+   no longer tied to Claude Code as a runtime. The eleven Layer-3 primitives
+   (skill, hook, agent, tool, memory, instruction-file, session-resume,
+   slash-command, outbound-relay, conversational-action, MCP-server) are
+   abstracted behind a parity-rule registry. Identity renders per framework
+   (Claude Code, Codex, Gemini) from a single canonical source. Session-launch
+   builders, the intelligence-provider factory, and the post-update migrator
+   are all framework-aware.
+
+The version-resolution policy was extracted from inline workflow scripting
+into `scripts/resolve-publish-version.mjs` so it is unit-tested.
 
 ## Evidence
 
-Reproduction prior to this release: render a canonical hook to .claude/hooks/session-start/inject.sh, append a user edit (e.g. echo "user added"), then run the parity scan. The verify pass reports user-edit-conflict, and the sentinel skips remediation. On the next instar update where the canonical hook source changes (the typical fix-broken-template scenario), the agent stays stuck on the user-edited stale rendering.
+Reproduction prior to this change: set `package.json` to a higher version
+while npm is behind, merge to main. The workflow published the npm-derived
+patch and silently discarded the intended version. This is the documented
+root cause in `docs/incidents/2026-05-19-v1-deployment-misalignment.md`.
 
-Observed after this release: same setup, same parity scan, the sentinel now calls remediate, the rendering is overwritten with the new canonical body, and the operator sees parity:user-edit-overwritten in the audit stream. Recovery of the user edit is available via git history if needed.
+Observed after this change: a higher `package.json` version than npm publishes
+at the intended version (this is how v1.0.8 itself ships). A routine PR that
+does not touch `package.json` still resolves to the next patch. A stale lower
+`package.json` resolves to npm patch-plus-one, never a downgrade.
 
-Unit-test verification: tests/unit/providers/parity/hookParityRule.test.ts now asserts remediate ALWAYS OVERWRITES user-edits per Migration Parity §4. tests/unit/monitoring/FrameworkParitySentinel.test.ts asserts the new audit event fires for alwaysOverwrite rules.
+Unit verification: `tests/unit/resolve-publish-version.test.ts` — nine cases
+covering greater-than, equal, and less-than across each semver field,
+operator-intended major and minor bumps, routine patch, stale no-downgrade,
+unpublished-package, and a regression replaying the exact 2026-05-19 incident
+input and asserting it now resolves to the intended version.
 
 ## What to Tell Your User
 
-- "When Instar ships a built-in hook, the canonical version always wins on the next update. A subtle regression in the Hook primitive was making us refuse to overwrite hooks that anyone had edited locally — which is exactly the pattern that left us stuck on a broken template once before. This release puts the always-overwrite policy back in place, and adds an audit signal so any clobbered edit is visible and recoverable from git."
+- "Instar v1.0 is here. The headline is portability: your agent is no longer locked to one runtime. The same agent identity, skills, hooks, and memory now render correctly whether the runtime is Claude Code, Codex, or another supported framework. This release also fixes the versioning process so the published version always matches what we intend to ship."
+- "If you are updating an existing agent, there is nothing you need to do. The framework-portability code already reached you through earlier patch updates; this release stamps the milestone and corrects the version number. Six narrow hardening improvements ship as quick follow-up patches over the next few releases."
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| ParityRule alwaysOverwrite field | Set alwaysOverwrite to true on rules covered by Migration Parity §4. Defaults to false (refuse-on-conflict for §5 rules like skills). |
-| parity:user-edit-overwritten audit event | Sentinel emits this whenever an alwaysOverwrite rule clobbers a user-edited rendering. Listen via FrameworkParitySentinel events. |
-| Canonical hook always-overwrite restored | No action required; built-in hooks are now once again always overwritten on every migration cycle. Custom hooks in .claude/hooks/custom/ continue to be untouched. |
+| Truthful versioning | Automatic. The release workflow honors the intended version. Routine patches are unchanged. |
+| Framework portability | Automatic. Agent identity and the eleven primitives render per runtime from a single canonical source. |
+| Per-framework identity | Canonical identity lives in one place; the runtime-specific shadow file is regenerated on demand. |
+
+## Agent Migration Notes
+
+For an agent updating from any v0.28.x to v1.0.8:
+
+- **Required actions: none.** The framework-portability code shipped
+  incrementally under v0.28.122–v0.28.125. This release stamps the milestone
+  and corrects the version label. No canonical-file migration is required.
+- **What is new on disk after update:** the post-update migrator continues to
+  refresh framework-rendered copies of canonical primitives. The
+  conversational-action catalog is reachable through its on-demand loaders
+  (context segment, knowledge-tree probe, playbook item). No always-loaded
+  identity-prompt growth.
+- **Verification an agent can run on itself:** confirm the installed version
+  reads 1.0.8 or higher; confirm the canonical identity file is the source of
+  truth and the runtime shadow carries the auto-generated banner.
+- **If an agent runs a non-Claude-Code runtime:** six narrow portability gaps
+  (documented in the v1.0.0 cross-framework audit) ship as v1.0.9–v1.0.14
+  patches immediately after this release. Until then, dual-framework installs
+  are unaffected; the gaps only touch single-runtime non-Claude-Code installs.
 
 ## Deferred (Tracked Follow-ups)
 
-- Wire parity:user-edit-overwritten into a Dashboard view so operators see clobber events without grepping logs.
-- Audit the remaining merged primitive PRs (#254 Agent/Tool/Memory and #255 Sentinel ship-order) using the lessons-aware reviewer; corrective amendments per finding.
+- Six audit-flagged portability hardening gaps ship as v1.0.9–v1.0.14 patches:
+  init routing through the identity renderer, framework-aware connector-server
+  registration, a framework-session-store abstraction, neutral relay-script
+  path, post-update-migrator framework guards, and migrator/identity-renderer
+  unification. Each has a documented fix from the cross-framework audit.
+- The broader deployment-lockdown infrastructure (release-tier config,
+  multi-signature for major bumps, major-work branch isolation, hold-signal,
+  incident-memory injection) is designed separately and tracked in the
+  deployment-lockdown topic. This release is only the version-truth
+  prerequisite plus the milestone stamp.

package/upgrades/side-effects/feat-publish-version-truth.md

@@ -0,0 +1,68 @@
+# Side-effects review — Publish version-truth
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+**Before.** UNDER: the workflow could not express an operator-intended major
+bump at all — every release was a patch. This is the incident root cause.
+
+**After.** No over-block. Routine patch PRs (the overwhelming majority, which
+don't touch package.json) behave identically — LOCAL == NPM → patch+1. The
+only new path is "LOCAL > NPM → honor LOCAL," which is exactly the
+intentional-leap case. The LOCAL < NPM guard prevents an accidental downgrade
+(a queued-run stale-package scenario), so there's no new under-block either.
+
+## 2. Level-of-abstraction fit
+
+The resolution policy lives in `scripts/resolve-publish-version.mjs` — a pure
+function with a CLI shim, unit-tested. The workflow calls it. This is the
+right altitude: decision logic in testable code, orchestration in the
+workflow. No logic buried in inline bash.
+
+## 3. Signal vs Authority compliance
+
+package.json is the SIGNAL of operator intent. The npm registry is the
+AUTHORITY for what shipped. The script reconciles them deterministically with
+a documented precedence. No brittle filter is granted blocking authority; the
+script never *blocks* a publish, it only *resolves the number*. (The loud
+refusal-on-mismatch behavior is part of the separate lockdown spec, not this
+PR.)
+
+## 4. Interactions with adjacent systems
+
+- **Release workflow.** Only the "Determine next version" step changes. The
+  NEXT.md skip-gate, the guide-check, the publish, and the tag/commit steps
+  are untouched.
+- **Routine patch line.** Unchanged. Verified by the `eq` test case.
+- **Queued concurrent runs.** The original concern ("queued runs leave
+  package.json out of sync") is preserved: a queued run that lands after an
+  earlier publish bumped will see LOCAL <= NPM and patch-bump cleanly, not
+  collide.
+- **The v1.0.0 cut.** This is the enabling change — the alignment PR will set
+  package.json to 1.0.0 and the workflow will, for the first time, honor it.
+
+## 5. Rollback cost
+
+Low. Three files (workflow step, new script, new test). `git revert` restores
+the npm-derived behavior. No state migration, no deployed-agent impact (this
+is build-time infra, not shipped runtime code).
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible for the patch line. The only behavioral delta is
+the previously-impossible major/minor leap. No config, no schema, no agent
+files touched. Drift surface: none — the script has no persistent state.
+
+## 7. Authorization / Trust posture
+
+No new authority. The script reads two version strings and prints one. It
+cannot publish, cannot mutate state, cannot escalate. The actual publish
+authority (NPM_TOKEN) is unchanged and still gated by the same CI required
+checks via branch protection.
+
+## Outcome
+
+Ship. Minimal, incident-driven, fully tested, no over-block, trivial
+rollback. Unblocks the v1.0.0 cut without pulling in the broader lockdown
+scope.