instar 1.2.21 → 1.2.22

package/README.md

@@ -101,10 +101,11 @@ An agent that forgets what you discussed yesterday, doesn't recognize someone it
 | Feature | Description | Docs |
 |---------|-------------|------|
 | **Job Scheduler** | Cron-based tasks with priority levels, model tiering, and quota awareness | [→](https://instar.sh/features/scheduler/) |
-| **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session | [→](https://instar.sh/features/telegram/) |
-| **WhatsApp** | Full messaging via local Baileys library. No cloud dependency | [→](https://instar.sh/features/whatsapp/) |
+| **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session. Default GFM-to-HTML markdown formatter (v1.1.0+) | [→](https://instar.sh/features/telegram/) |
+| **WhatsApp** | Full messaging via local Baileys library or WhatsApp Business API webhook. No cloud dependency in Baileys mode | [→](https://instar.sh/features/whatsapp/) |
 | **iMessage** | Native macOS messaging via Messages.app database polling + `imsg` CLI. [Setup guide](#imessage-setup-macos) | |
-| **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages | [→](https://instar.sh/features/lifeline/) |
+| **Slack** | Two-way messaging via Slack adapter. Channel and DM routing, eight HTTP routes, dedicated CLI | [→](https://instar.sh/features/slack/) |
+| **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages, version-skew handling (v1.1.3+) | [→](https://instar.sh/features/lifeline/) |
 | **Conversational Memory** | Per-topic SQLite with FTS5, rolling summaries, context re-injection | [→](https://instar.sh/features/memory/) |
 | **Evolution System** | Proposals, learnings, gap tracking, commitment follow-through | [→](https://instar.sh/features/evolution/) |
 | **Relationships** | Cross-platform identity resolution, significance scoring, context injection | [→](https://instar.sh/features/relationships/) |
@@ -113,19 +114,21 @@ An agent that forgets what you discussed yesterday, doesn't recognize someone it
 | **Intent Alignment** | Decision journaling, drift detection, organizational constraints | [→](https://instar.sh/features/intent/) |
 | **Multi-Machine** | Ed25519/X25519 crypto identity, encrypted sync, automatic failover | [→](https://instar.sh/features/multi-machine/) |
 | **Serendipity Protocol** | Sub-agents capture out-of-scope discoveries without breaking focus. HMAC-signed, secret-scanned | [→](https://instar.sh/features/serendipity/) |
-| **Threadline Protocol** | Agent-to-agent conversations with canonical identity, three-layer trust model, authorization policy, Ed25519 invitations, Sybil protection, MoltBridge network discovery, rich agent profiles (auto-compiled from agent data with human review gate), discovery waterfall, message security, tamper-proof audit logging, framework-agnostic interop, and persistent listener daemon (always-on relay connection, pipe-mode sessions, sub-30s cross-machine failover). 2,324 tests across 104 test files | [→](https://instar.sh/features/threadline/) |
+| **Threadline Protocol** | Agent-to-agent conversations with canonical identity, three-layer trust model, authorization policy, Ed25519 invitations, Sybil protection, MoltBridge network discovery, rich agent profiles (auto-compiled from agent data with human review gate), discovery waterfall, message security, tamper-proof audit logging, framework-agnostic interop, persistent listener daemon (always-on relay connection, pipe-mode sessions, sub-30s cross-machine failover), eleven MCP tools (seven core + four registry-conditional). 80 modules, roughly 3,800 test cases across 74 dedicated test files plus 125 cross-cutting | [→](https://instar.sh/features/threadline/) |
 | **Self-Healing** | LLM-powered stall detection, session recovery, promise tracking | [→](https://instar.sh/features/self-healing/) |
 | **AutoUpdater** | Built-in update engine. Checks npm, auto-applies, self-restarts | [→](https://instar.sh/features/autoupdater/) |
 | **Build Pipeline** | `/build` skill with worktree isolation, 6-phase pipeline, quality gates, stop-hook enforcement | |
-| **Behavioral Hooks** | 9 automatic hooks: command guards, safety gates, identity grounding, topic context | [→](https://instar.sh/reference/hooks/) |
+| **Behavioral Hooks** | Eleven hook scripts plus nine observability event hooks: command guards, safety gates, identity grounding, topic context, channel context for iMessage and Slack, free-text guard, skill-usage telemetry, build stop-hook | [→](https://instar.sh/reference/hooks/) |
 | **Initiative Tracker** | Persisted multi-phase long-running work tracker. Phases, blockers, links, digest alerts. HTTP API at `/initiatives/*` | |
-| **Default Jobs** | Health checks, reflection, evolution, relationship maintenance | [→](https://instar.sh/reference/default-jobs/) |
+| **Observability** | Token burn detection, quota tracking with tiered backpressure, telemetry collection, homeostasis monitoring, session activity tracking, credential management | [→](https://instar.sh/features/observability/) |
+| **Cross-framework portability** | First-class Codex CLI support via `instar setup --framework codex-cli`. Codex-only init produces zero `.claude/` files. Framework-aware telegram-reply path. FrameworkSessionStore (per-runtime transcripts). FrameworkParitySentinel | [→](https://instar.sh/features/portability/) |
+| **Default Jobs** | Fourteen built-in jobs covering health, reflection, evolution, relationship maintenance, identity review, and five `overseer-*` jobs across development, learning, infrastructure, maintenance, and guardian responsibilities | [→](https://instar.sh/reference/default-jobs/) |
 
 > **Reference:** [CLI Commands](https://instar.sh/reference/cli/) · [API Endpoints](https://instar.sh/reference/api/) · [Configuration](https://instar.sh/reference/configuration/) · [File Structure](https://instar.sh/reference/file-structure/)
 
 ## Agent Skills
 
-Instar ships 12 skills that follow the [Agent Skills open standard](https://agentskills.io) -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.
+Instar ships fourteen skills total — twelve user-facing, plus two internal skills (`instar-dev` and `spec-converge`) used only by the agent that develops instar itself. The standard is the [Agent Skills open standard](https://agentskills.io) -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.
 
 **Standalone skills** work with zero dependencies. Copy a SKILL.md into your project and go:
 

package/package.json

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

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T03:55:48.253Z",
-  "instarVersion": "1.2.21",
+  "generatedAt": "2026-05-22T04:08:18.326Z",
+  "instarVersion": "1.2.22",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/src/scaffold/templates/jobs/instar/docs-coverage-audit.md

@@ -0,0 +1,36 @@
+---
+name: Docs Coverage Audit
+description: Weekly walk of the instar source tree against the docs surface. Surfaces newly-undocumented capabilities so docs don't drift between releases. Off by default — only useful on machines that have the instar source repo locally (instar developers, contributors). Operators who want it can flip enabled to true in `.instar/jobs/instar/docs-coverage-audit.md`.
+schedule: "0 10 * * 1"
+priority: medium
+expectedDurationMinutes: 5
+model: haiku
+enabled: false
+tags:
+  - cat:learning
+  - audit
+  - instar-dev-only
+toolAllowlist: "*"
+unrestrictedTools: true
+---
+Run a weekly documentation coverage audit on the instar codebase. This job exists because docs drift between releases — features ship without doc updates, and the gap accumulates silently until someone notices. This audit catches the drift early.
+
+The job:
+
+1. Locate the instar source repo on this machine. Try in order: the workspace dir from .instar/config.json under workspace.repoPath; ~/Documents/Projects/instar/; ~/.instar/agents/<self>/.worktrees/ (any subdirectory); or whatever path the operator has configured. If you cannot find the instar repo on this machine, send a short Telegram message saying so and exit — there's no audit to run.
+
+2. Run the coverage script from inside that repo: `node scripts/docs-coverage.mjs --json > /tmp/docs-coverage-this-week.json`. The script enumerates every shipped capability (routes, commands, jobs, hooks, skills, top-level classes per subsystem) and cross-references against site docs + README. It writes both a JSON inventory and a markdown report to .instar/docs-coverage.json and .instar/docs-coverage.md.
+
+3. Compare the new report to last week's. The previous week's report lives at .instar/state/docs-coverage-last-week.json if it exists. Use plain JSON diff logic — what's the delta in undocumented count per category? What capabilities are newly undocumented (existed before but lost their doc mention, or are brand-new in src/ without any doc)? What capabilities became newly documented (good news worth surfacing)?
+
+4. If the delta is interesting (any category gained ≥3 undocumented items OR any single category dropped below its CI floor OR the overall coverage dropped by ≥2 percentage points), send a Telegram message that's a quick, conversational heads-up. Lead with the headline: "Docs coverage dipped in [category]" or "Five new endpoints landed without doc mentions" or similar. Then list the specific items in plain language with their file paths. End with a one-line suggestion of where to add the missing doc (which file in site/src/content/docs/ is the natural home).
+
+5. If the delta is uninteresting (small fluctuations, churn that nets to zero, all categories still above floor), stay silent. Most weeks should be silent — that means the docs are keeping up.
+
+6. After surfacing (or not), save the current report as next week's baseline: copy /tmp/docs-coverage-this-week.json to .instar/state/docs-coverage-last-week.json.
+
+7. Optionally, if the script's --check mode would fail (any category below its CI floor), file a higher-priority signal via the degradation reporter — this is the case where the next PR will hit a CI failure unless someone fixes coverage first.
+
+IMPORTANT: This is a guardian job, not a doer. Surface the drift and where to fix it, don't fix it yourself. The fix work belongs in a deliberate doc-update PR with proper review, not in an autonomous job run. If the drift is large, suggest the operator open a topic to scope the doc update — don't try to enumerate the full backlog in one Telegram message.
+
+Plain English. No raw JSON in the message. No structured field names. The user reads these on their phone. Write like you're texting a teammate about a code-review observation.

package/upgrades/1.2.22.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**feat(docs-coverage-weekly): weekly audit job + GitHub Actions cron that surface accumulated docs drift.**
+
+Companion to the per-PR docs coverage gate that shipped in v1.2.21. The per-PR gate catches regression, but coverage can stagnate at the floor indefinitely if every PR just barely scrapes by. This release adds the trend-surface piece: a weekly check that catches accumulated drift even when the per-PR gate is satisfied.
+
+Two delivery surfaces, both light and both off the critical path:
+
+1. **Job template** — `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` ships as an agentmd job, `enabled: false` by default. Instar-developing agents (the ones with the instar source repo on their machine) can flip it to `true` in their local `.instar/jobs/instar/docs-coverage-audit.md`. Once enabled, the job runs every Monday at 10:00 local time, locates the instar source repo, executes the coverage script, compares to the prior week's baseline, and sends a Telegram heads-up if anything drifted in an interesting way. Most weeks stay silent — that means docs are keeping up.
+
+2. **CI workflow** — `.github/workflows/docs-coverage-weekly.yml` runs every Monday at 10:00 UTC against the main branch. Posts the weekly report as a comment on a standing tracking issue tagged `docs-coverage`. Creates the issue on first run; appends weekly thereafter. Provides a durable, GitHub-native ledger of how coverage moves over time.
+
+Both surfaces are signals, not authorities. Neither fixes docs autonomously. The per-PR gate from v1.2.21 remains the authoritative regression check; these surface the trend.
+
+Spec: `docs/specs/docs-coverage-weekly.md`. ELI16: `docs/specs/docs-coverage-weekly.eli16.md`. Side-effects review: `upgrades/side-effects/docs-coverage-weekly.md`.
+
+## What to Tell Your User
+
+Nothing user-visible. The job is off by default and would only apply to agents that develop instar itself. The workflow runs in instar's own GitHub Actions, not the user's.
+
+## Summary of New Capabilities
+
+This release adds a single new job template (off by default) and a single new CI workflow. Both target the instar-developer use case rather than the end-user agent. No new agent runtime behavior.
+
+## Evidence
+
+The coverage script that both surfaces invoke was shipped and tested in v1.2.21. The job template was verified to parse with valid frontmatter. The workflow YAML validates against GitHub Actions schema. Both files were verified to install via existing pipelines: `installBuiltinJobs()` walks the templates directory on every install and update, and the workflow runs from `.github/workflows/` like every other workflow in the repo.

package/upgrades/side-effects/docs-coverage-weekly.md

@@ -0,0 +1,74 @@
+# Side-effects review — docs-coverage-weekly
+
+Spec: `docs/specs/docs-coverage-weekly.md`
+ELI16: `docs/specs/docs-coverage-weekly.eli16.md`
+Companion to: `docs/specs/docs-coverage.md` (the underlying script + per-PR CI gate)
+
+## Surface map
+
+| Change | File | Type |
+|---|---|---|
+| New job template | `src/scaffold/templates/jobs/instar/docs-coverage-audit.md` | `agentmd` job, `enabled: false` by default. Distributed via `installBuiltinJobs()` on `instar init` and on every update via `PostUpdateMigrator` |
+| New CI workflow | `.github/workflows/docs-coverage-weekly.yml` | GitHub Actions cron workflow, Mondays at 10:00 UTC |
+
+No production code touched. No agent behavior changes at runtime unless an operator explicitly enables the job.
+
+## Over-block analysis
+
+**Could the job spam an operator?**
+
+The job ships `enabled: false`. Operators with the instar source repo on their machine can flip it to `true` in `.instar/jobs/instar/docs-coverage-audit.md`. The job's first action is to locate the instar source repo; if it can't find one, it sends a short message and exits — and the operator can disable the job again. So the worst case is one Telegram message before the operator turns it back off.
+
+When enabled and working correctly, the job stays silent most weeks. The delta thresholds (≥3 newly-undocumented items in a category, any category below CI floor, ≥2-point overall drop) ensure that only meaningful drift surfaces a message.
+
+**Could the CI workflow spam an issue tracker?**
+
+The workflow opens or updates one standing issue tagged `docs-coverage` and appends weekly reports as comments. If the issue is closed by a maintainer (signaling "stop tracking this"), the workflow creates a new one on the next run. This is the desired behavior — closing the issue is the soft way to say "I'm aware, I'll re-engage later." Comments accumulate on a single issue rather than creating a new issue per run.
+
+**Could the CI workflow fail and block other CI?**
+
+No. The workflow is its own job in its own file with no dependencies on other workflows. A failure is visible in the Actions UI but doesn't gate any other PR or push.
+
+## Under-block analysis
+
+**What does the weekly audit NOT catch?**
+
+- Same content-quality limitations as the per-PR coverage check — a documented capability with completely wrong content still counts as documented. The audit catches enumeration drift, not comprehension drift.
+- Doesn't catch capabilities that exist outside the enumerated locations (e.g. an exported class moved to a directory the script doesn't walk). This is a deliberate scope choice; the alternative is walking everything and producing noise.
+- Doesn't catch deleted docs that should still exist (the script measures coverage of what's in code; if code AND docs both lose a capability, neither shows up as drift).
+
+## Level-of-abstraction fit
+
+The job lives in `src/scaffold/templates/jobs/instar/` alongside the other default jobs. The CI workflow lives in `.github/workflows/` alongside other workflows. Both are at the right level: the job is at the agent-behavior layer (something the agent does), and the workflow is at the project-infrastructure layer (something the project does to itself).
+
+The script they both invoke (`scripts/docs-coverage.mjs`) was deliberately built first as a separate concern. This change layers two delivery mechanisms on top of it without modifying the script. If the cadence needs to change (daily, monthly), the script doesn't care.
+
+## Signal-vs-authority compliance
+
+Both surfaces are **signals**. Neither has authority to fail a build or block work. The per-PR coverage check from the docs-coverage spec is the authoritative gate. The weekly job and the weekly workflow are loud heads-ups, but they can't refuse to ship anything. The separation matches how other signal/authority pairs work in instar.
+
+## Interactions with existing systems
+
+- **`installBuiltinJobs()`** — picks up the new `docs-coverage-audit.md` template on every install/update. Existing agents get the template (off by default) on their next update via `PostUpdateMigrator`. No separate migration code needed because `installBuiltinJobs` already overwrites built-in templates idempotently.
+- **Scheduler** — sees the new job. With `enabled: false`, the scheduler reads it on startup but doesn't schedule it for execution. No CPU cost.
+- **GitHub Actions cron** — runs in the same project as other workflows but in its own job and on its own schedule. Doesn't share state with any per-PR workflow.
+- **Telegram adapter** — the job uses the same `telegram-reply.sh` path every other job uses for outbound messages. No new adapter integration.
+- **Docs-coverage script** — invoked via `node scripts/docs-coverage.mjs`. The script is deterministic and idempotent, safe to run repeatedly.
+
+## Rollback cost
+
+Trivially reversible. Remove the two added files. Existing agents lose the template on their next update; the workflow stops running on the next merge.
+
+## Risk summary
+
+- **Low risk of regression.** Pure additions. Job is off by default; workflow runs independently of any other workflow.
+- **Low risk of friction.** Job stays silent most weeks. Workflow posts to one standing issue rather than spraying alerts.
+- **No risk of data loss.** Both surfaces are read-only against the codebase.
+
+## Verification done before commit
+
+- Job template parses correctly (verified via reading frontmatter in test fashion).
+- CI workflow YAML validates against GitHub Actions schema (manual review).
+- The underlying script (shipped in the docs-coverage spec) is already tested and verified — no changes needed.
+- `enabled: false` confirmed in the template so this lands silently for existing agents.
+- Distribution path verified: `installBuiltinJobs()` walks `templates/jobs/instar/` and installs all `.md` files regardless of `enabled` flag, so the file reaches every agent on update; the `enabled: false` controls whether the scheduler runs it.