synlynk Changelog

Fixed

This release closes gh:#2291 — two live dispatch failures this cycle (grok-code-fast-1 and an Agy model id both rejected as unknown) traced back to synlynk's model catalog being a static, hand-maintained list with no periodic refresh and no enforcement that dispatch actually reads a live-validated value. Both failure modes recurred again live during this same release's own PR review dispatches, underscoring the fix.

Added

Fixed

Historical Note (v0.23.0 / v0.24.0 version arc gap): Changes planned across the v0.23.0 and v0.24.0 arcs (Graphify auto-extraction, unified canvas, boardroom governance, and local oMLX fleet) were consolidated directly into v0.25.0. Per this repo's documented Named-Release version gap policy (CLAUDE.md: "Gaps in the version arc... are acceptable — users see public history, not internal planning slots"), gaps in public release history represent internal planning slots and are preserved without retrofitting synthetic entries.

Added

Fixed

Changed

Added

Fixed

Changed

Highlights

• Visual Workspace Observatory (BS-6 Vizor): Interactive browser dashboard with Product, Logical, and Infra graph views (synlynk viz).
• Workspace Agent Roles & Role Studio: Browser-driven GitHub App role onboarding and SFIA-grounded living charters.
• Adaptive Worktree Lifecycle: Automatic stale worktree detection, blast-radius impact analysis, and safe pruning (synlynk worktree audit/clean).
• Fleet Resilience & State DB Hardening: Fail-closed product identity resolution and crash-recoverable state promotion.

Breaking Changes

• [Draft] The default output format for status commands is now structured JSON instead of human-readable text. Scripts that parse the previous line-oriented output may fail or consume incorrect values after upgrading. Migration: request the documented machine-readable fields explicitly, update parsers to read the JSON schema, and reserve the text format for interactive use.

• [Draft] Commands that operate on a workspace now require an explicit workspace context when run outside the repository root. Automation launched from a different working directory may fail instead of silently reading or writing state for the wrong workspace. Migration: run the command from the intended repository root or pass its --workspace option explicitly, and update wrappers that previously relied on the current directory being inferred.

• [Draft] The command-line configuration flag --config now accepts only a file path, not an inline JSON object. Scripts that pass configuration directly on the command line will fail validation after upgrading instead of being parsed as before. Migration: write inline configuration to a file and pass that file's path to --config, or use the equivalent environment-based configuration mechanism.

• [Draft] The default configuration directory is now resolved relative to the workspace root. Deployments that relied on the process working directory may load a different configuration after upgrading, which can change dispatch and storage behavior. Migration: move workspace configuration into the repository's .synlynk/ directory, or pass an explicit configuration path wherever the command is run from outside the workspace.

• [Draft] Resource lookup commands now exit non-zero when no match is found. Automation that treats an empty result as a successful no-op will begin failing fast, making missing resources visible instead of silently masking typos or stale identifiers. Migration: handle the documented not-found exit code explicitly when an empty result is expected, and reserve other non-zero codes for actual command failures.

• [Draft] List-command responses now return an object with items and next_cursor instead of a bare array. Clients that iterate over the response directly or deserialize it as an array will fail after upgrading, while the wrapper leaves room for pagination and future metadata. Migration: read records from items, treat a missing or null next_cursor as the end of the result set, and follow the cursor when fetching subsequent pages.

• [Draft] JSON output for synlynk jobs --json now wraps records under a jobs key. Consumers that read the previous top-level array will no longer receive a compatible response, making the output extensible without changing its meaning. Migration: read the jobs field and handle an empty list when no jobs are available.

• [Draft] Event payloads now require an explicit event_version. Consumers that omit the field will be rejected instead of receiving a best-effort payload, making incompatible contract changes visible at the boundary. Migration: update producers to send the supported version and update consumers to validate it before processing events.

• [Draft] Dispatch task definitions now require an explicit task_type. Definitions that omit the field will be rejected instead of being inferred from task text, which makes routing failures visible before a job starts. Migration: add the appropriate task_type to each existing definition (for example, implement, test, or review) before upgrading.

• [Draft] Configuration files now require an explicit schema version. Unversioned configuration files will no longer be loaded implicitly, which prevents older layouts from being interpreted as current settings. Migration: add the supported schema_version value to existing files and run synlynk migrate before upgrading; invalid or unsupported versions should be corrected before dispatch can resume.

• [Draft] The default retry policy now fails closed for unknown error types. Jobs that encounter an error not covered by the configured retry policy will stop instead of being retried automatically, preventing non-idempotent work from running more than once. Migration: review custom retry policies, add explicit handling for errors that are safe to retry, and re-run stopped jobs only after confirming that their side effects are safe to repeat.

• Dispatch jobs now distinguish completed work from true zombie termination (#1498). Previously, any exited worker that still had a disposable worktree could be classified as killed_zombie (exit -9) before the reconciler read the {log}.exit marker or inspected real output — including clean design/review jobs. That also deleted worktree-local logs. Migration: treat killed_zombie as a true orphan only (dead PID, no exit marker, no completion receipt / meaningful work). For cleanup and retry, prefer the job's terminal status and exit_code (done / failed). Worker logs now live under the daemon's central .synlynk/logs/ directory and are preserved when a disposable worktree is reaped.

Added

• Cadence-breaker resilience engine: markdown append conflict auto-rebase, active-job circuit breaking at 500k zero-file tokens or $5, startup harness failover, and dead-PID daemon worktree cleanup.

• Charter Content & Structure Schema

  • Charters now require YAML frontmatter (schema_version, role, description, durability, tools, credentials) plus three markdown sections (## Instructions, ## Authority & Escalation, ## Workflow Ownership), enforced via a new synlynk/charter_schema.py validator wired into propose_charter_revision.
  • Retired the dead .synlynk/agents/<id>.yaml projection file and regenerate_agent_projection() — its only field (capability_grants) was write-only, never read.
  • Added synlynk agent sync-routing <id_or_alias> to regenerate a charter's dispatch_routing frontmatter block from .synlynk/policy.json's task-allocation table.
  • Migrated all 7 provisioned charters (dev, qa, architect, pm, tpm, designer, marketing) to schema revision 3; pm's migration restores the competitive-intelligence-sweep / capability-gap-doc content that had been lost in an earlier revision.

Agent vs Harness Terminology — Phase 0 (design 2026-08-09, plan 2026-08-09)

• docs/glossary-agent-vs-harness.md — canonical definition distinguishing Agent (persistent role identity + charter: pm/architect/tpm/dev/designer/qa/marketing/synlynk-bot) from Harness (swappable execution backend: Claude/Agy/Grok/Codex/local).
• Auto-generated ## Capability-Based Task Allocation table (synced into CLAUDE.md/GEMINI.md/AGENTS.md/GROK.md via synlynk doctor --fix) now reads | Role | Harness | Tasks | instead of the conflated | Role | Agent | Tasks |, with a glossary-link note.
• Hand-maintained "Terminology: Agent vs Harness" section added to this repo's own CLAUDE.md.
• .synlynk/roles.yaml, README.md, SYNLYNK_GUIDE.md wording fixed to stop conflating Agent and Harness.
• Not yet a shippable milestone: first phase of a 5-phase roadmap (docs/superpowers/specs/2026-08-09-synlynk-agent-roles-charters-design.md §10). Phase 1 (agent manifests/charter storage) has since shipped — see [0.14.0] below — but Phases 2-4 (memory, capability registry, portability) remain unbuilt. Held out of 0.13.1 and 0.14.0; will ship as its own named release once the full terminology rollout is complete.

Quota-Aware Dispatch Reservation (design 2026-08-08, plan 2026-08-08)

• agent_reservations ledger tracks estimated-token reservations per harness from the moment a job is queued/dispatched until it settles, closing the gap where --force-agent and daemon-queued dispatches could bypass quota checks entirely.
• dispatch_agent() now consults quota unconditionally (including --force-agent calls) and defers (queued, blocked_reason=quota_exhausted) instead of raising when a harness has no headroom; deferred jobs resume automatically once the harness's quota window resets — no manual re-dispatch needed.
• _dispatch_ready_jobs() no longer falls through to an exhausted harness when a job is blocked; it stays queued for the next poll.
• synlynk schedule --execute opens real reservations for the whole batch at commit time via _enqueue_plan().
• _force_exhaust_quota() wires sentinel's existing QUOTA_EXHAUSTED detection into the reservation ledger without ever touching already-running jobs.
• synlynk/tpm_hooks.py — narrow TPM hook surface (tpm_observe_reservations, tpm_reorder_queue, tpm_reallocate) plus a read-only synlynk quota --tpm-view CLI command to inspect open reservations across harnesses.
• Not yet a shippable milestone: no active agents currently exercise the reservation ledger or TPM hooks in production dispatch flow. Held out of 0.13.1 and 0.14.0; will ship once agents actually consume it.

Added

Fixed

Changed

Release pitch: a backlog of already-shipped, undocumented work — QA merge-gate authority, the gh-write broker, harness capability registry v2, and a week of dispatch/gh-write reliability fixes — finally gets a version number, and today's own session shows why that matters: a live datetime-comparison crash (#1184) and a per-connection DB backup storm (#1087) both got root-caused and fixed in the same sitting this release closes out.

Added

QA delegated merge-gate authority + completion tracker + merge-restricted classes (design 2026-08-20/22, gh#1079/#1099/#1100/#1101, PRs #1082-#1104)

• docs/superpowers/specs/2026-08-20-qa-merge-gate-authority-design.md and its implementation plan give QA delegated authority to merge PRs that pass verification, instead of every merge requiring a human or PM-role action.
• Completion tracker (PR #1100) adds a Vizor panel surfacing verified-but-unmerged PRs.
• Merge-restricted classes (PR #1101) carve out PR categories (e.g. release branches, policy.json changes) that stay outside QA's delegated authority regardless of verification status.

GitHub-write broker design (resolves #865 brainstorm, PR #1075)

• Design spec for a centralized gh-write broker consolidating GitHub App token resolution and write-permission checks behind one interface, replacing scattered per-call-site identity resolution.

Harness capability registry v2 — Plan B (gh#786, PRs #1053-#1066)

• harness_models / harness_modes / capability_calibration_* tables replace the old flat capability ledger with per-model, per-mode calibration data.
• Stage 0 explore bonus seeds calibration for thin-data models; single-model sweep entry point and diff-and-queue-new-models helper keep the registry current as harnesses add models.

gh-write identity hardening — Phase 1 closeout (gh#423/#426, PR #1110) and Agent-roles Phase 2 — memory-gated capability routing (PR #1030)

• Round out the identity-hardening and capability-routing work referenced but not yet changelogged from earlier in August.

Dispatch and gh-write reliability hardening (2026-08-24 to 2026-08-27, PRs #1140/#1164/#1166/#1172/#1174/#1175/#1177/#1180/#1182/#1183)

• Daemon-owned GitHub App token cache unblocks headless dispatch (#1140, PR #1174); worktree gh-write dispatch now falls back to the main repo's github_apps when the worktree has none (PR #1164).
• PR-review task type is now inferred from task text (#1166, PRs #1172/#1175); a missing review task_allocation policy entry is added; grok's review-type gh-write authorization is correctly downgraded (PR #1177).
• Codex sandbox network access is now gated per #340 (PR #1180).
• gh-write targets are resolved from task text for #860 (PR #1183); a jobs.py bug in _maybe_open_worktree_pr is fixed (PR #1182).
• Harness capability baseline + recurring reassessment protocol documented (PR #1178).

PM competitive-intelligence sweep (PR #1159)

• Weekly cron job maintaining a living comparison doc against competitor tooling, feeding a decide-round pipeline for roadmap input.

Fixed

[LIVE issue] jobs --all crash on naive/aware datetime comparison (gh#1184, PR #1187)

• _parse_iso8601() in synlynk/gh_verify.py now normalizes a trailing Z and coerces naive timestamps to UTC-aware before comparison, instead of crashing with TypeError: can't compare offset-naive and offset-aware datetimes whenever a GitHub-sourced timestamp reached gh_write_verified(). _apply_gh_write_verification() in synlynk/jobs.py normalizes since through the same parser before use.

[LIVE-6, gh#1140] branch-protection sync re-enabling enforce_admins, closing #1185 (PR #1186)

• cmd_policy_sync_branch_protection() no longer hardcodes enforce_admins=True; a prior sync had silently re-locked the repo's own admin-merge bypass.

[LIVE issue] _migrate_db() backup storm on every connection (gh#1087, PR #1189)

• _migrate_db() now returns immediately once PRAGMA user_version is current, instead of running the harness-rename migration and full schema executescript unconditionally on every connection. Root-caused as the likely source of intermittent database is locked failures seen during full-suite test runs (e.g. test_cmd_agent_add_onboards_agent).

Process notes

• 8 stale [APPROVAL] GitHub issues closed (gh#1142-#1149): artifacts of the [0.17.0] Task 5 live dogfood verification's temporary task_dispatch_demo policy rule, which was fully reverted before merge and never landed on main. These tickets could never resolve through the normal auto-resume flow; closed as not planned with provenance comments during this release's backlog sweep.
• Version-drift note: the VERSION file had drifted to 0.16.0 despite v0.17.0 already being tagged and released — see #1188 for root cause and proposed durable fix (dispatch-time drift warning, defensive schema-version gate). This release's version bump corrects the immediate drift; #1188 remains open for the systemic fix.

Release pitch: an approved [APPROVAL] ticket now actually unblocks the story it was raised for — the last gap between v0.16.0's authority layer and a tpm sweep loop that runs unattended for real, closed and live-verified against this repo's own GitHub tracker.

Added

Ticket-driven approval auto-resume (design/plan 2026-08-24, PRs #1137-#1139, #1141)

• Closes the known gap flagged at the end of [0.16.0]: resolving an [APPROVAL] ticket now actually unblocks the parked story on the next synlynk tpm sweep pass, instead of the story re-parking forever.
• approval_tickets table (PR #1137) plus _find_ticket() / _insert_ticket() / _mark_ticket_consumed() helpers in synlynk/db.py (PR #1138) give run_sweep_pass() (PR #1139) three-way state awareness per story/action: no ticket yet → file one; open ticket → keep parking; resolved ticket → consume it and let dispatch proceed.
• synlynk/events.py's _scan_approval_tickets() (PR #1141) now writes approval_tickets.status='resolved' at the same point it emits approval_resolved, so the resolution is durable state the next sweep pass can actually query — not just an event log entry nothing consumed.
• Live dogfood verification (Task 5, Claude-direct per plan, 2026-08-24): ran the full ticket lifecycle against this repo's real GitHub issue tracker using a temporary, fully-reverted task_dispatch_demo policy rule (reverted before merge; never landed on main). Demo story story-becf09a5: sweep 1 parked it and filed ticket id 8 → issue #1149; sweep 2 confirmed no duplicate ticket/issue; gh issue comment 1149 --body "approve" + scan_local_events() produced approval_resolved event id 371 referencing issue #1149; sweep 3 dispatched instead of re-parking (job job-e8277299, exit 0) and marked the ticket consumed (consumed_at set). Every claim was verified via direct DB query / gh issue list / synlynk events tail, not sweep's own printed summary.
• Process note: Tasks 1-4's implementer stage was dispatched to Codex per the project's PM/review-only split as usual. Task 4 hit a session-level blocker — the Claude Code auto-mode classifier repeatedly denied synlynk dispatch calls even with valid role-scoped GitHub App credentials — so Task 4 was implemented directly by Claude as a documented, user-approved workaround. Filed as LIVE-6, #1140 (Sev2) since it degrades the autonomy-design goal; root cause not yet investigated.

Known gaps (carried forward)

• LIVE-6, #1140 — Claude Code auto-mode classifier blocks synlynk dispatch calls even with valid role-scoped GitHub App credentials, forcing a manual-implementation fallback. Root cause not yet investigated.

Release pitch: the authority layer v0.15.0 built now actually gates something unattended — synlynk tpm sweep walks ready stories through dispatch end-to-end, pauses on a policy-flagged action with a GitHub approval ticket instead of blocking the whole batch, and a live dogfood run proved both the happy path and the pause+ticket path work — surfacing two real gaps in the process, filed rather than papered over.

Added

GOVERNS awaiting_approval event (Task 10, PR #1125)

• New GOVERNS event type extending the job_terminal/review_submitted event-contract pattern (PR #922): emit_awaiting_approval(story_id, action, reason) in synlynk/events.py, recording which policy.json approval_required_for rule matched.

Approval-gate ticket flow (Task 11, PR #1126)

• synlynk/approval_gate.py — raise_approval_ticket() files a [APPROVAL] <action> — <story_id> GitHub issue with story context, the matched policy rule, and instructions to reply approve or act directly on GitHub.
• synlynk/events.py's _scan_approval_tickets() polls open [APPROVAL] issues and emits approval_resolved for any that are closed or have an approve-prefixed comment, wired as the last step of scan_local_events().

synlynk tpm sweep (Task 12, PR #1127)

• One pass over readiness='ready' stories: dispatch → verify → PR → review → merge per story, gating every step on check_authority(). A requires_approval result parks that story (raises a ticket, emits awaiting_approval) without blocking the rest of the batch. Per-pass summary surfaced via synlynk status.

Live dogfood verification (Task 13, Claude-direct per plan)

• Ran synlynk tpm sweep unattended against this repo's real backlog. To avoid dispatching all 8 pre-existing ready stories for real, the 8 were temporarily parked (synlynk story draft) and restored afterward; only two purpose-built demo stories were swept.
• Pass 1 (no approval rule active) proved the normal path: story-028d26d9 dispatched, ran to completion, PR opened.
• Pass 2 (a temporary, documented, fully-reverted test-only policy.json rule — task_dispatch: has no default rule that can trip requires_approval, since _matches_approval_rule() explicitly skips security_sensitive_paths: for dispatch actions) proved the pause path: story-7aa0aaec parked, a real [APPROVAL] issue was filed and assigned, approve was commented, and _scan_approval_tickets() correctly emitted approval_resolved (event id 272) — independently confirmed via synlynk events tail --type approval_resolved and gh issue view --json state,comments.
• Every claim was cross-checked directly (synlynk jobs --all, direct DB queries, gh issue list --search, gh api .../branches/main/protection) rather than trusted from the sweep's own printed summary, per the plan's explicit instruction.

Fixed

Release pitch: synlynk's own repo gets a real authority layer — a two-tier policy.json (workspace defaults + per-repo overrides) that turns previously-hardcoded prose tables (who can merge, who can cut a release, who can edit the roadmap, which harness handles which task type) into data, gated by a fail-closed check_authority() resolver, with branch protection now live-verified on main.

Added

Workspace Policy Layer (design 2026-08-23, plan docs/superpowers/plans/2026-08-23-workspace-policy-and-autonomous-loop.md, PR #1122)

• synlynk/policy.py — two-tier policy schema: workspace defaults (~/.synlynk/workspaces/<name>/policy.json, falling back to DEFAULT_WORKSPACE_POLICY when absent) merged with a repo's sparse .synlynk/policy.json overrides, whole-object-replace-per-top-level-key (not a deep merge).
• check_authority(action, role, repo_path) → AuthorityResult(allowed, requires_approval, reason), covering roadmap_edit, goal_create, merge, release_cut, and task_dispatch:<type> actions, plus an approval_required_for rule matcher (named releases, roadmap-authority changes, security-sensitive paths, irreversible merges).
• Wired fail-closed into four call sites: dispatch_agent()'s task-allocation resolution, cmd_release, cmd_roadmap_add, cmd_goal_create — each raises RuntimeError on allowed=False rather than proceeding.
• synlynk policy check-merge, synlynk policy sync-branch-protection, synlynk policy show — new CLI commands; sync-branch-protection calls GitHub's branch protection API idempotently, deriving required status checks from .github/workflows/.
• This repo's own .synlynk/policy.json migrates the existing CLAUDE.md prose tables (Capability-Based Task Allocation, PR Review Discipline, Named Release authority) into data — CLAUDE.md now points to synlynk policy show as the source of truth instead of hand-maintained tables.
• Full check_authority() unit coverage: allow/deny/requires_approval across both tiers, override-merge rule, missing-repo-override inheritance, unknown task_type denial (tests/test_policy.py, 11 tests).
• Live-verified: branch protection synced and independently confirmed via gh api repos/nikhilsoman/synlynk/branches/main/protection — required_status_checks = ["test (3.8)", "test (3.10)", "test (3.12)", "qa-gate"], required_reviews = 1, enforce_admins = true.

Fixed

Release pitch: the execution floor gets a truth guarantee — every GitHub-write dispatch now has its claimed outcome independently verified against live GitHub state instead of trusted at face value — and workspace agents get a real identity: a storage-backed charter, a synlynk agent init/list/show/edit/disable onboarding surface, and dispatch integration that resolves role and harness from that identity automatically.

Added

GOVERNS Job-Truth / GH-Write Consolidation (#701, PR #978) — closes #331, #579, #935

• synlynk/gh_verify.py gh_write_verified() — an independent delivery-of-effect check that queries live GitHub state via the orchestrator's own gh identity (not the sandboxed job's), replacing "the job said it succeeded" with "GitHub confirms the write landed."
• Wired into dispatch.py's _check_job_stall (extends timeout on an unverified write, kills the job on a confirmed failure) and jobs.py's _reconcile_daemon_jobs (new succeeded_gh_write_failed terminal status distinct from a clean success).
• gh_write_verified surfaced as a column in synlynk jobs output.
• Regression guard (tests/test_gh_write_guard.py) asserting every terminal-status-deciding code path for a --requires-gh-write job consults the check.
• synlynk doctor TC-7 preflight verifies Agy's local gh allow-rules before routing gh-write tasks to it, instead of failing at dispatch runtime.
• Codex PR-review tasks now route through the gh CLI directly instead of the previously-unreliable MCP add_review_to_pr/add_comment_to_issue tools.

Workspace-Scoped Agent Artifact Storage (design 2026-08-14/15, gh#936, PR #988)

• Mints a real workspace_id (uuid4, persisted once in .synlynk/config.json) keying a new workspace-level agent artifact store.
• agent_id registry (register_agent/resolve_agent_id) mirroring the existing member_id/member_aliases pattern — loud failure on an unregistered alias, rejects duplicate agent_id/alias.
• Canonical charter.md + provenance-chained charter.revisions.jsonl storage (read_charter/propose_charter_revision) with stale-parent-revision conflict detection, extended to memory/ and statements-of-record/ entries.
• regenerate_agent_projection() writes a generated, gitignored .synlynk/agents/<agent_id>.yaml projection (agent_id/role/overrides only, never charter content) via a stdlib-only flat YAML emitter.

Agent-Roles-Charters Phase 1 — CLI Onboarding + Dispatch Integration (design 2026-08-16, PR #1003)

• synlynk agent init/list/show/edit/disable — the CLI onboarding surface for workspace agents (org-chart roles: dev/qa/pm/architect/tpm/designer/marketing/synlynk-bot), built on the storage layer above.
• dispatch_agent() gains agent_id support: validates the agent is registered/enabled, resolves its role, auto-selects a harness by capability fit when none is forced, and threads the resolved role into GitHub-identity/token resolution (taking precedence over story_id-derived role when both are present).
• synlynk dispatch --as-agent <id_or_alias> — makes the harness positional argument optional when --as-agent triggers auto-selection.

Agent → Harness CLI Rename (PR #993)

• Renames synlynk agent add/configure/run/list to synlynk harness add/configure/run/list, resolving the naming collision between execution-backend harnesses and the workspace/role-identity agents introduced above. No deprecation shim — pre-1.0 breaking change, decided via a 4/4 synlynk decide --panel vote (project-docs/decisions/2026-08-16-synlynk-s-cli-has-a-naming-collision-syn.md).
• Frees the agent CLI verb for the onboarding surface above. dispatch <agent>, open <agent>, probe --agent, quota --agent are untouched — those use "agent" in unrelated senses.

TPM/Session MVP (plan 2026-08-13, PRs #934, #944, #950, #954, #959)

• sessions table + synlynk/session.py active-session marker file helpers.
• devlog_entries gains session_id/goal_id columns; cmd_devlog_append() auto-inherits the active session when not passed explicitly.
• session_id threaded through dispatch_agent() → daemon_jobs → cost_entries (with inheritance from job to cost row), so every dispatch and its cost are attributable to the session that launched it.
• synlynk dispatch --session <id> override flag.
• synlynk session status surfaces a NUDGE line when daemon_jobs has rows with no session_id — the first concrete TPM-facing signal for unattributed work.

Fixed

Housekeeping

• Worktree/job accumulation (#559) audited and closed without new code: synlynk worktree audit/worktree clean (shipped pre-0.13.1 in PR #676) already covers the core ask; synlynk status's existing staleness hint covers the proactive-warning ask. Re-verified against this repo's own worktree state during the audit.

Release pitch: synlynk gets safer to operate on — init/migrate/upgrade can now roll back on failure, project docs are DB-canonical instead of hand-parsed markdown, the GOVERNS event bus gains job-terminal and review-submitted events plus a synlynk events tail command, and a new doctor check catches invalid GitHub tokens before a dispatch wastes a turn discovering them.

Added

GOVERNS Event-Contract Extension (design 2026-08-12, plan 2026-08-12, #922)

• job_terminal event — emitted synchronously from _reconcile_daemon_jobs() for every daemon job reaching a terminal state, payload {job_id, status, cost_recorded, dispatch_context}.
• review_submitted event — emitted from scan_local_events() for each GitHub PR review not already represented, payload {pr_number, reviewer_login, reviewer_role, verdict}, with reviewer_role derived from bot-login patterns.
• synlynk events tail [--type TYPE] [--limit N] — read-only CLI command listing recent events newest-first directly from the events table.

Init/Migrate/Upgrade Rollback Mechanism (design 2026-07-22, plan 2026-07-22)

• rollback_checkpoint (Leg 1) wraps init() and cmd_migrate() in a git-checkpoint + untracked-state backup, auto-restoring on any mid-operation failure.
• rollback_checkpoint_upgrade (Leg 2) wraps _run_upgrade() in a global install snapshot (pipx reinstall-by-tag / script bin+lib backup), auto-restoring on upgrade failure.
• synlynk rollback [--last|<op-id>|--clear] — manual rollback CLI, restoring or discarding the most recent (or a specific) checkpoint manifest.
• --dry-run on synlynk init and synlynk upgrade — preview what would be written/changed without touching disk or making network/subprocess calls.
• Failure-injection live selftest coverage for both rollback legs, plus dedicated rollback --last/--clear scenario tests.

State Engine PR1 — DB-canonical roadmap/memory/costs (design 2026-07-20, plan 2026-07-25)

• roadmap.md, memory.md, and costs.md are now write-through generated from state.db (roadmap_arcs/roadmap_phases, memory_entries, cost_entries), with rotation/archive and a warn-and-continue mutation guard for hand-edits.
• check_budgets() reads cost_entries directly instead of regex-parsing costs.md.
• synlynk migrate run on this repo itself — project-docs/ relocated under .synlynk/, .synlynk_migrated sentinel committed.

synlynk doctor TC-6 — GitHub CLI auth check (#928, closes #577)

• New check across all 4 dispatch harnesses (claude, codex, agy, grok) inspects gh auth status output for known invalid-token marker strings even when the command exits 0 — the documented false-green failure mode where a dispatch sandbox has a broken GitHub token but gh doesn't report a nonzero exit.

Fixed

• Bumped linkify-it to 5.0.2 in website/package-lock.json, resolving a high-severity quadratic-complexity DoS (CVE-2026-59887, GHSA-v245-v573-v5vm) in its mailto: schema validator. Dev-only, transitive via markdown-it; fixes GitHub Dependabot alert #6.
• synlynk jobs now resolves the repo's real default base branch before gh pr create, avoiding hardcoded --base main failures on repos whose default branch is master or another tracked branch.
• synlynk dispatch agy now warns when no write/run permissions are granted, so headless dispatches do not fail silently when approval-gated tool calls are auto-denied.
• Bumped brace-expansion to 1.1.16 in website/package-lock.json, resolving a high-severity exponential-time DoS (CVE-2026-13149, GHSA-3jxr-9vmj-r5cp) in expansion of consecutive non-expanding {} groups. Dev-only, transitive via minimatch; fixes GitHub Dependabot alert #7.

Docs

• docs/rca/2026-08-13-dispatched-pr-review-cancellation-714.md (#929, closes #714) — RCA concluding Grok's cancelled stopReason on dispatched PR reviews is harness-side, not a synlynk stall/timeout bug; no code change warranted.

Release pitch: synlynk learns to explain itself — every command now has a discoverable taxonomy entry with a maturity-tiered reveal, a live selftest exercises all 59 commands end-to-end, cost accounting gets payment-model awareness and a task-boundary fence around actual spend, and dispatch routing gets capability-aware enough to stop sending GitHub-write work to agents that structurally can't do it.

Added

Command Taxonomy, Maturity-Tiered Reveal, and Trigger Registry (design #303, PRs #304/#305/#309/#310/#311/#312/#316/#319/#320/#321)

• COMMAND_TAXONOMY becomes the single source of truth for all 59 commands — cli.py's build_parser() extracted standalone (#304), taxonomy command surface restored and hardened (#305), default fenced_commands allowlist (#309).
• Command reference docs now generate directly from COMMAND_TAXONOMY (#316) instead of hand-maintained markdown, closing a recurring drift source.
• FTUE wizard and the synlynk launch picker are now driven by the same taxonomy (#319), so first-run onboarding and the reference docs can never disagree about what a command does or which tier it belongs to.
• Tier-scoped trigger phrases wired into synlynk:start/synlynk:end session fencing (#320).
• Pre-commit hook installed on synlynk init to gate instructions drift between the taxonomy and generated CLAUDE.md/GEMINI.md/AGENTS.md content (#321).

Task-Boundary Cost Fence (story-615bc8f4, PRs #313/#314/#315/#317)

• synlynk exec's actual-cost print now routes through a dedicated cost fence at the task boundary (#313) rather than being computed ad hoc per call site, closing a class of under/over-reporting bugs where a task's real spend diverged from what costs.md recorded.
• Shipped and marked complete in the roadmap (#314); PM session cost for the execution itself logged per the Cost Capture Protocol (#315, #317).

Live Command Selftest (PR #328, follow-ups #335/#337)

• synlynk selftest — a taxonomy-driven smoke test that exercises all 59 commands, catching command-surface regressions the unit suite doesn't (drift between COMMAND_TAXONOMY and actual CLI behavior, broken flag wiring, silent crashes on real invocation).
• Blog post documenting the design and implementation (#335).
• Follow-up fix: live paid selftest scenarios now rebind DB_PATH to a scratch workspace instead of touching the real project DB (#337, scenario N6).

Capability Sweep + Industry Taxonomy (PR #367)

• synlynk capability sweep — a taxonomy-driven calibration sweep scoring agent capability against NAICS/APQC/SFIA-coded skill axes, seeded from synlynk/capability_baseline.json and reinforced organically as real PRs land, with a configurable $10 cost guardrail (capability_sweep.cost_cap_usd) and independent cross-agent verification scoring.
• Legacy free-text discipline / org_domain / industry values are crosswalked to NAICS/APQC/SFIA codes on migration, tagging unmatched values legacy_unmapped rather than dropping them.

Payment-Model-Aware Cost/Value Accounting — PMA-1 through PMA-6 (PR #374)

• Cost and value accounting now distinguishes payment model (subscription-seat vs. metered/API) so costs.md and budget reporting reflect what was actually spent under each agent's real billing arrangement, instead of a single blended token-rate assumption.
• Manual cost entries gained payment-column population (#402); historical entries backfilled with api_equivalent_usd for cross-model comparison (#388).
• Roadmap and devlog synced for both Capability Sweep (#367) and PMA (#374) landing together (#375).

Story-ID Auto-Provisioning for Dispatch (PR #407)

• dispatch_agent() now auto-provisions a story_id when a dispatched task has none, closing a gap where ad hoc dispatches (not tied to an existing story) fell outside cost/capability tracking.

can_gh_write Capability Routing (issues #423/#426, PRs #427/#432/#438)

• AGENT_CAPABILITY_BASELINES gained a can_gh_write field so dispatch routing can structurally avoid sending GitHub-write work (gh pr review/merge) to agents that can't complete it headless (Agy, Codex, local) — previously enforced only by SOP convention (#427, #432 codified the convention first; #438 made it structural).
• New --requires-gh-write dispatch flag and enforcement logic in dispatch_agent().

Fixed

• synlynk watch crash on CYCLES.index("work") (issue #421, fixed by #301, released here): the v0.12.0 tag shipped cmd_watch() still looking up a "work" cycle name that had already been renamed out of hud.py's CYCLES list under the GOVERNS seven-stage vocabulary rollout, raising ValueError: 'work' is not in list on every invocation. The fix (CYCLES.index("execute")) merged to main via #301 two days after the v0.12.0 tag, but was never shipped in a release until now.
• synlynk viz --serve exits immediately, nothing binds the port (issue #421, PR #440, merged as #421): _start_server() spawned the HTTP server on a daemon=True thread and returned immediately with no blocking call, so the process exited (killing the daemon thread with it) right after printing "Serving at...". Not a sandbox/forking artifact — reproduced identically in a real terminal. Fix adds _serve_until_stopped(), which blocks the main thread until KeyboardInterrupt and then cleanly shuts the server down.
• synlynk migrate false-positive MigrationImportError on idempotent re-runs (#276, #278): natural-key collisions on re-import no longer trip the loud-fail check.
• Dispatch auto-PR branch detection re-derives the worktree's actual current branch instead of trusting the pre-recorded name (#280, #283).
• synlynk probe clears HARNESS_VERSION_DRIFT for the specific agent just re-probed (#281, #284).
• synlynk agent add <name> retrofits onboarding for a newly available CLI agent already on $PATH (#277, #285), plus lazy daily housekeeping on the first synlynk exec of a new calendar day.
• Token-outlier cost entries now flagged safely instead of silently corrupting averages (#295).
• Stale Cost Visibility / Repo Hygiene SOP text corrected (#290, #296).
• Per-provider model rates with freshness checks across costs, doctor, and sentinel (#289, #297).
• Probe version-token parsing fixed (#294); model version now resolved from agent config files (#287, #292).
• agent_quotas now populated from telemetry, plus a new synlynk quota CLI (#291, #293).
• Job summary overwrites guarded against clobbering (#387).
• Dispatch worktrees branch from a fresh origin/main tip instead of a potentially stale local ref (#398, #395).
• Headless permission denials correctly classified, avoiding false positives from echoed source text (#399, #404).
• Agy permission dispatch enabled (#417).
• GitHub issue #379 follow-up: .g file handling fix (#384).
• __init__.py modularisation epic marked shipped, closing stale #380 (#401).

Design specs: docs/superpowers/specs/2026-07-21-command-taxonomy-maturity-reveal-design.md, capability sweep and PMA specs referenced in PRs #367/#374. Roadmap rows synced for Task-Boundary Cost Fence, Command Taxonomy, and Live Command Selftest (#416). State Engine tiered design (single-user/team/enterprise) drafted for a future release (#412) — not shipped in this version.

Release pitch: the operational backbone gets provably reliable and provably accounted for — dispatched jobs finish their own git steps, a 5th zero-cost local agent joins the fleet, story routing gets real capability+quota+cost scoring with a fleet batch scheduler, and every dollar synlynk reports is now either structurally sourced or visibly flagged as an estimate.

Added

Measurement Ledger Hardening — Phase 1 + Phase 2 + display layer (epic #210, PRs #236/#241/#242/#244/#245/#246/#252/#256/#257/#264/#266/#267)

Phase 1 — provenance-tagged cost tracking (PR #236):

• cost_entries gained explicit provenance columns: cost_source TEXT NOT NULL (actual | estimated_token_rate | estimated_tshirt | estimated_manual | legacy_unknown, no default — every INSERT must pass it explicitly) and estimate_basis TEXT. Migration rebuilds the table and backfills historical rows as legacy_unknown.
• _insert_cost_row() (synlynk/db.py) is now the sole sanctioned writer to cost_entries, replacing four independently-drifting direct-SQL write sites in dispatch.py, jobs.py (×2), and support_engineer.py. Upserts by job_id when present. Enforced by a call-site audit test that fails the suite if any other file writes to cost_entries directly.
• extract_tokens() now tags a .basis (regex_pair | total_split | none) distinguishing a real per-field token extraction from an 80/20 heuristic guess.
• .synlynk/model_rates.json (scaffolded by synlynk init) is now the source of truth for per-model rates and billing_mode, replacing a hardcoded table; falls back to hardcoded rates on missing/invalid file.
• New 3-tier t-shirt-size token fallback (_estimate_tshirt_tokens()) for surfaces with no real token count: story's estimated_tokens column → historical average from cost_entries (same discipline+phase, ≥3 samples) → fixed conservative default.
• synlynk cost log — manually log a cost row for native/unwrapped PM or brainstorming sessions with no CLI token data, tagged estimated_manual.
• Cost coverage closed across every surface identified in the design spec's audit: dispatch_agent()'s exec wrapper (no longer gated on in_tokens > 0), jobs.py's reconcile and daemon-reconcile paths, cmd_launch(), and support_engineer.py's investigation runs. synlynk release, synlynk probe, and synlynk doctor audited and confirmed correctly out of ledger scope.
• check_budgets() gained a dedicated sub-line surfacing failed-job placeholder estimates separately from the headline spend total. costs.md and budget parsers now tolerate [est] /[legacy] /~ prefixes.
• New "Cost Capture Protocol" section in CLAUDE.md.
• [failed job] marker fix: dispatch.py's zero-token-failure cost label now prepends (not appends) the marker so it survives update_costs()'s 20-character command truncation, restoring check_budgets()'s failed-job sub-line to live code.

Phase 2 — structured-output token adapters, one per dispatch CLI (PRs #244, #252, #256, #257): replaces the 80/20 heuristic split with a real per-field structured-JSON extraction path for each vendor CLI — Codex, Claude, Agy (Gemini), and Grok all shipped, closing epic #210's adapter scope.

Display layer (PRs #264, #266): Vizor's Effort & Cost tab now visually flags estimated-vs-measured cost rows; synlynk status gained a RATES line (and JSON rates_updated_at key) showing when the model rate table was last updated, warning ⚠ never updated when no rate file exists.

Design spec: docs/superpowers/specs/2026-07-13-measurement-ledger-hardening-design.md. Roadmap arc + epic #210 marked shipped (PR #267). Deferred follow-ups filed as issues, out of scope for this release: #260 (Savings Ledger), #261 (dispatch-path unification), #262 (surface consolidation), #263 (stage constants staleness).

Local Agent — 5th dispatch agent, zero-cost on-device inference (PRs #200/#204/#205/#207/#208/#209)

• local joins claude/codex/agy/grok as a dispatchable agent, running as an aider CLI subprocess against an on-device oMLX OpenAI-compatible endpoint — zero per-token cost.
• Capability envelope seeding + concurrency guard so local starts with a conservative starter whitelist that self-widens with verified results.
• Real-hardware opt-in pytest tier (tests/test_local_agent_hardware.py) exercises actual Aider+oMLX end-to-end, correctly skipped when no local hardware is running.
• Capability-matrix taxonomy worked example + blog post documenting the integration.

Capability Matrix Hardening — 3-stage routing engine + fleet batch scheduler (epic #137, PRs #139/#140/#141/#147/#148/#150/#151/#152/#154/#156)

• _best_agent_for_story() now scores candidates across three real stages: weighted capability score (VERIFIER tier, dead-signal handling, pr_review_cycles/verified_by_ci signals), a hard quota-headroom gate (agent_quotas table across 5h/hourly/daily/weekly/monthly windows, degraded-mode fallback when quota signal is missing), and a cost tie-break (cheaper model wins when top scores are within 0.15).
• New synlynk/scheduler.py: stories.priority/readiness columns, synlynk story ready/draft gate, fleet-level in-batch headroom accounting (story N in a batch sees story 1..N-1's projected spend), retry/reassignment capped at 2 attempts, synlynk schedule [--execute] [--max-stories N] CLI.
• GOVERNS seven-stage vocabulary rollout replaces the old CYCLES/CYCLE_COLOURS naming across the capability taxonomy and HUD.
• Capability tag enum enforcement + taxonomy reference doc; cycle_capability row dedup migration fix.
• Deferred v2 (reset-timing-aware bin-packing, persistent quota-blocking history, GOVERNS-aware readiness gate) tracked as a goal, gated on 30 days of v1 production data (deadline 2026-08-10) rather than scoped into stories now.

Job Lifecycle Ground-Truth Verification (#126, #127, #128, #129, PRs #130/#131/#132/#133/#135)

• dispatch_agent() creates a dedicated git worktree per dispatched job (worktrees/<job_id>, branch dispatch/<agent>/<job_id>) instead of sharing the invoking shell's cwd — concurrent dispatches no longer collide.
• _reconcile_jobs() cross-checks git state when a job's exit sentinel is missing, instead of treating an ambiguous exit as automatic failure; new "failed_unverified" status flags "inspect before discarding."
• files_touched is real (via git diff --name-only <merge-base> HEAD + git status --short --porcelain), no longer hardcoded to [].
• cmd_migrate() prints the resolved DB_PATH and fails loud with MigrationImportError on a 0-row import from a non-empty source, instead of a silent green banner.

Vizor

• Architect Map v2 (PR #167): replaces the static tube-map SVG with a live force-directed graph of workspace repos and typed cross-repo edges, a side drawer (path/stack/GitHub/dispatch/Gantt-jump/active-dream-count), and an IDE-style file-tree sub-view.
• Business Goals Panel (PR #153): surfaces goals/stories rollups in the HUD.
• __init__.py re-modularized a second pass — 11 focused modules extracted (synlynk/db.py, jobs.py, dispatch.py, context.py, sentinel.py, scheduler.py, etc.), no more single-file monolith (PR #180).

Fixed

Dispatch git-finalization reliability chain (#182/#184/#185/#189/#190/#191/#196/#198, PRs #186/#187/#192/#193/#194/#195/#199/#201)

• Dispatched agents (Codex/Agy) frequently completed real, tested work but didn't reliably finish their own git steps (commit/push/PR). synlynk now performs git finalization itself once, gated on a job's running→terminal transition (idempotent by construction) — stages everything except a hard-exclusion list, commits, pushes, opens a PR via gh pr create if none exists.
• Borrowed-worktree completions attributed via origin/<branch> state instead of being misread as zero-work.
• HARNESS_INTERNAL_TIMEOUT jobs now auto-retry (cap 2) instead of landing as a dead failure.
• A job that raced its own disk writes and landed failed with 0 touched is re-inspected once and reclassified failed_unverified rather than staying permanently stale.
• Cost accounting no longer bypasses the per-model rate table in 3 places (including a hardcoded gemini-2.5-pro $0 bug); local gets an explicit $0.0 override regardless of model version.
• Capability router now filters on canonical discipline, not the legacy engg_domain column.
• Daemon queue launch unified through dispatch_agent() so worktree/preflight/permission-flags/concurrency-guard logic isn't duplicated across two divergent paths.
• Harness no longer misreports completed jobs as FAILED with fabricated token counts.

Misc dispatch/CI hardening (PRs #163/#164/#165/#171/#173/#238/#240)

• Codex sandbox gets --add-dir <git-common-dir> so it can write git refs inside a worktree.
• dispatch --help's agent list now derives from AGENT_CAPABILITY_BASELINES instead of a stale hardcoded list.
• Stall-killer generalized to detect harness-internal timeouts and checks remote branch activity before hard-failing a silent job.
• 3 baseline CI flakes isolated from runner environment state; Python 3.8 compat fix for a tuple[str, str] annotation.
• dispatch --context-mode full now warns when used on a task that's already self-contained.

Release pitch: synlynk v0.11.0 is the Agent Ecosystem Operational Layer — every dispatch now carries permissions and recovery paths, your terminal shows a live fleet of agents in real time, and the full workflow discipline is baked into every agent directive file at init.

Added

Agent Autonomy Bridge (BS-12, PR #119)

• synlynk dispatch --grant <perm> --revoke <perm> — per-task permission overrides; role defaults in .synlynk/config.json map 12 roles (pm, review, implement, test, css, infra, etc.) to capability tiers. Resolved set translates to --allowedTools (Claude), --ask-for-approval (Codex), or a ## Permissions context header (Agy).
• synlynk configure agent <name> [--flag k=v] [--env K=V] [--network-dep host:port] — write per-project harness overrides to .agents/<agent>.json; dispatch_agent() merges at call time: baseline → per-project overrides → per-task grant/revoke.
• synlynk jobs --stalled — list jobs with HANDOFF_PENDING sentinel (set when a job accumulates STALL_NO_OUTPUT, FLATLINE, or QUOTA_EXHAUSTED). Shows job ID, agent, failure sentinel, elapsed time, and recommended next agent.
• synlynk jobs handoff <job_id> [--to <agent>] — transfer a stalled job to a new agent; appends ## Handoff Note to the job context file, increments handoff_count, updates previous_agents (JSON array), launches new dispatch with full context, clears HANDOFF_PENDING.
• synlynk doctor TC-5 — scans each directive file for all 6 required SOP section headers; warns (non-blocking) if any are absent. Interactive fix wizard runs after each TC failure with structured fix paths (TC-1–5) and an "I'm stuck" escape that assembles failure context and dispatches Claude for conversational diagnosis.
• synlynk sync --repair-sops — re-injects missing SOP sections into directive files without touching existing harness fence content. Idempotent.
• 6 SOP blocks written into CLAUDE.md, GEMINI.md, AGENTS.md, and GROK.md at synlynk init and synlynk sync time: PR Review Discipline · Brainstorm-First Policy · Design → Plan → Build Sequence · Capability-Based Task Allocation · Cost Visibility · Repo Hygiene.
• daemon_jobs schema additions: handoff_count INTEGER DEFAULT 0, previous_agents TEXT (JSON array). Migration applied automatically on first access.

Live Job Observatory (BS-13, PR #117)

• synlynk watch --live — fullscreen live job board: all running/recent jobs with agent, status, elapsed time, cost, and output tail; auto-refreshes every 3s; Ctrl-C to exit.
• Vizor Observatory tab — fifth tab in synlynk viz browser dashboard: real-time job fleet table (JS polling), per-agent status badges, cost rollup, job output drawer.

Vizor Efficiency Enrichment (BS-22, PRs #113, #118)

• R/W/T budget bars — per-agent card shows Read, Write, Test utilisation as percentage of TIER1_CAPACITY.
• Cycle × Agent capability matrix — 6 × 4 table (dream/plan/work/ship/maintain/engage × Claude/Agy/Codex/Grok) with full/partial/none badges (cap-full, cap-partial, cap-none CSS classes).
• Per-agent radar hexagon SVGs — 80×80px SVG radar on each agent card; 6-axis polygon filled at 30% opacity with agent theme colour; axis score maps full→1.0, partial→0.5, none→0.0.

Ecosystem Status + Capacity (BS-16, PR #110)

• synlynk status — terminal platform health: harness compliance table, agent availability, budget pulse (R/W/T capacity bars per agent), 6-cycle capability matrix.
• synlynk status --json — machine-readable ecosystem snapshot consumed by Vizor as its live data contract.
• Three dispatch modes: eco (respects R/W/T budget gates), daily-grind (default), perf (no budget gates).
• Three new _preflight_dispatch() gates: CAPACITY_EXCEEDED_INPUT, CAPACITY_EXCEEDED_OUTPUT, TOOL_PRESSURE.
• New state.db tables: harness_status, cycle_capability; probe command extended to seed Tier 1 capacity baselines.
• synlynk/status.py new module; HarnessSnapshot dataclass in hud.py.

Modularisation (chore, PRs #103–#109)

• Extracted synlynk/__init__.py (11,268L) into five focused modules: synlynk/probe.py, synlynk/sentinel.py, synlynk/upgrade.py, synlynk/dispatch.py, synlynk/_constants.py. __init__.py reduced to ~1,500L of orchestration and CLI surface.

Fixed

TC-2 dispatch fix arc (PRs #114–#116)

• Fixed false-positive TC-2 failures caused by Agy dispatch_flags baseline including --non-interactive (valid for Agy but flagged as invalid by harness validator). Corrected per-agent flag baseline maps.
• Fixed _run_tc2 seeding invalid flags into the passed list on first scan, blocking all subsequent Agy dispatches.
• synlynk logs now shows exit summary + TC-2 preflight gate result per dispatch.

BS-12 review fixes

• --repair-sops now merges missing SOP blocks into existing harness fence body instead of replacing the entire fence.
• TC-5 result wired into all_passed in cmd_doctor; doctor now exits non-zero when SOPs are missing.
• Handoff note included in handoff_task sent to new agent (was reading context before append).
• TC-5 fix menu scoped to agents with missing sections only (was firing for all agents in loop).
• --flag KEY (boolean flag without =) in configure agent now uses partition instead of crashing with ValueError.

BS-22 review fixes

• Removed is_placeholder short-circuit in SVG circles matrix that contradicted the new text capability matrix.
• CSS class cap-{support} now normalised to lowercase; prevents unstyled cells from mixed-case DB values.
• Removed unreachable dead-code fallback block in get_capability_level().

Changed