instar 1.3.358 → 1.3.360

package/upgrades/projects-mergebranch-resolve.eli16.md

@@ -0,0 +1,11 @@
+# Projects "merged" check now works on dev-agent homes too
+
+Tonight's #866 fix wired the GitHub-PR verification into the projects pipeline's "building → merged" step — and it works: it resolves the PR, confirms it merged, gets the merge commit. But the very next check then failed on a dev-agent machine: the validator confirms the merge commit is actually on the main branch by checking "origin/main". On a normal install that's right. On a developer agent's home checkout, though, "origin" points at the agent's personal FORK, while the real merges land on the UPSTREAM repo under a differently-named remote. So origin/main never contains the commit, and every attempt to record a step as merged failed with "commit not reachable from origin/main" — even though the PR genuinely merged.
+
+This is a sibling of the same class as #866: code that assumed the common-case environment and broke on the dev-agent's fork-origin layout. I hit it the moment #866's fix let me get that far — trying to mark this very initiative's own rounds merged.
+
+The fix: instead of hardcoding "origin/main", the route now asks GitHub which repo it's actually talking to (the same repo the PR-view reads), finds the LOCAL remote whose URL points at that repo, and checks "<that-remote>/main". On a normal install that resolves right back to origin/main (unchanged behavior); on a fork-origin agent home it correctly resolves to the upstream remote where the merges live. Both lookups are read-only (a GitHub repo-view and a git remote listing).
+
+With this, the projects pipeline can finally record merged steps on the machines we actually develop on — which is the whole point of being able to track an initiative through to "merged."
+
+_Follow-up note: on any lookup error the resolver simply uses the standard default — by design, not as a failure._

package/upgrades/side-effects/operator-binding-awareness.md

@@ -0,0 +1,60 @@
+# Side-effects review — Operator Binding agent-awareness CLAUDE.md section
+
+## What this change does
+Adds the Agent Awareness Standard surface for the now-feature-complete Operator
+Binding (Know Your Principal) loop (shipped across #904/#906/#908/#909/#910). It is
+PURE DOCUMENTATION — a new CLAUDE.md capability section, no logic/behavior/data
+change. Wired into all three required awareness surfaces so the parity gate stays
+green:
+
+- `src/scaffold/templates.ts` (`generateClaudeMd`): the `**Operator Binding (Know
+  Your Principal)**` section for NEW agents, inserted before the Commitments section.
+- `src/core/PostUpdateMigrator.ts` (`migrateClaudeMd`): the SAME section for EXISTING
+  agents, appended only when absent (content-sniffed on `**Operator Binding (Know
+  Your Principal)**`), idempotent, with a `result.upgraded.push`.
+- `src/core/PostUpdateMigrator.ts` (`migrateFrameworkShadowCapabilities` markers[]):
+  the `**Operator Binding (Know Your Principal)**` marker so Codex/Gemini agents
+  learn it too (no improvised weaker workaround).
+- `tests/unit/feature-delivery-completeness.test.ts`: the `featureSections` entry
+  (the `**`-wrapped form, matching the migrator guard + markers like Session Boot
+  Self-Knowledge) so the three-surface parity is enforced going forward.
+
+## Blast radius
+- **Additive, idempotent, no behavior change.** The migrator branch only appends
+  when the heading is absent; re-running migration is harmless. No config key, no
+  route, no class, no dependency.
+- **Migration parity satisfied by construction** — this change exists BECAUSE of the
+  Migration Parity Standard: new agents (templates.ts) + existing agents (migrator)
+  + shadow frameworks (markers) all get the section. The parity gate
+  (feature-delivery-completeness) fails CI if any surface is missing — it passed
+  (77/77) after the `**`-wrapped featureSections fix (the auto-detect captures the
+  migrator's content-sniff string verbatim, so the tracked entry must match it
+  exactly — same precedent as `**Session Boot Self-Knowledge**`).
+
+## Content accuracy (verified against the merged feature)
+- `/topic-operator`, `/topic-operator/:topicId`, `/topic-operator/session-context`
+  routes exist (merged #906). POST refuses a blank/unverifiable uid with 400 (#904
+  establishOperator). Auto-bind from authenticated sender on inbound (#909). The
+  observe-only guard writes `state/principal-coherence.jsonl` behind
+  `monitoring.principalCoherence.enabled`, signal-only (#910). The CLAUDE.md text
+  describes exactly these — no aspirational claims.
+
+## Framework generality
+The documented capability is framework-agnostic (HTTP routes + an identity
+disposition), which is why it carries a shadow marker. Codex/Gemini agents get the
+same awareness; nothing here is Claude-specific.
+
+## Migration parity
+This IS the migration-parity work. Covered: templates.ts (new), migrateClaudeMd
+(existing), markers[] (shadow). No `.claude/settings.json`/hook/config changes.
+
+## Tests
+- `tests/unit/feature-delivery-completeness.test.ts` — the three-surface parity gate,
+  77/77 (the section is tracked in featureSections and present in templates.ts, the
+  migrator, and markers[]). Clean `tsc --noEmit`; lint clean; docs-coverage `--check`
+  passes (no new route); repo-invariants hold.
+
+## Rollback
+Revert the templates.ts section, the migrator section + marker, and the
+featureSections entry. The on-disk CLAUDE.md of already-migrated agents is inert
+extra documentation; no data to unwind.

package/upgrades/side-effects/projects-mergebranch-resolve.md

@@ -0,0 +1,53 @@
+# Side-Effects Review — projects merge-base branch resolution (#866 sibling)
+
+**Version / slug:** `projects-mergebranch-resolve`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — small read-only environment fix + unit coverage`
+
+## Summary of the change
+
+After #866 wired ghPrView, the `building → merged` gate's NEXT check —
+`gitMergeBaseIsAncestor(oid, 'origin/main')` — failed on fork-origin dev-agent
+homes: `origin` is the agent's fork (instar-echo) while merges land on the
+upstream remote (JKHeadley/instar), so origin/main never contains the merge
+commit (MERGE_COMMIT_UNREACHABLE). Fix: `StageTransitionValidator` reads the
+branch from a new `ctx.mergeBaseBranch` (default `origin/main`, behavior
+preserved); the route computes it via `resolveCanonicalMainRef()` — asks gh
+which repo it resolves for the cwd, maps that to the local remote whose URL
+matches, returns `<remote>/main`, falling back to `origin/main`.
+
+## Decision-point inventory
+- `building → merged` merge-base check — was hardcoded `origin/main`, now uses the resolved canonical-main ref. The check's logic is unchanged; only the ref it compares against is now environment-correct.
+
+## 1. Over-block
+Before: fork-origin homes 100% over-blocked (every merged transition rejected though the PR merged). After: rejects only when the commit truly isn't on the canonical main. Strict improvement. Canonical-origin installs unchanged (resolves to origin/main).
+
+## 2. Under-block
+If gh/remote resolution misfires it falls back to `origin/main` (the prior behavior) — never a more-permissive ref, so no new under-block. The resolved remote must actually contain the commit or the gate still rejects.
+
+## 3. Level-of-abstraction fit
+Validator stays pure (takes the branch as input); the environment resolution lives in the route (where gh/git + cwd are). Right seam — mirrors how #866 injected the helpers.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+- [x] No — the gate remains a real check (commit reachability on canonical main); this only supplies the correct ref.
+
+## 5. Interactions
+- `resolveCanonicalMainRef` is read-only: `gh repo view` (gh, not funnel-gated) + `git remote -v` via SafeGitExecutor.readSync (`remote` is a READONLY_GIT_VERB, shape-checked list/get-url only).
+- Any failure → fallback `origin/main`; never throws into the route.
+- No interaction with the other advance edges (outline→spec, etc.) — only the merged edge reads mergeBaseBranch.
+
+## 6. External surfaces
+- Spawns `gh repo view` + `git remote -v` against the project target repo when a merged transition is attempted. No persistent state, no messaging, no fleet surface.
+
+## 7. Rollback cost
+Pure code revert + patch. No state.
+
+## Conclusion
+Completes the #866 chain: the projects pipeline can now record merged steps on dev-agent homes (fork-origin) as well as canonical-origin installs. Clear to ship.
+
+## Evidence pointers
+- `tests/unit/StageTransitionValidator.test.ts` — new cases: helper called with the configured `mergeBaseBranch` (not origin/main); unreachable error names the configured branch. 28 validator tests + 45 projects-api green; tsc + destructive-lint clean.
+
+_Follow-up: the resolver catch carries an `@silent-fallback-ok` note — falling back to the `origin/main` default is the conservative behavior this resolver refines, not a swallowed error._