instar 0.26.11 → 0.27.2

package/src/templates/hooks/build-stop-hook.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Build Stop Hook — Structural enforcement for the /build pipeline.
+#
+# Prevents premature exit during active builds. Graduated protection:
+#   SMALL  (light):  3 reinforcements
+#   STANDARD (medium): 5 reinforcements
+#   LARGE  (heavy):  10 reinforcements
+#
+# Reads state from .instar/state/build/build-state.json.
+
+STATE_FILE=".instar/state/build/build-state.json"
+
+# No state file = no active build = allow exit
+if [ ! -f "$STATE_FILE" ]; then
+  echo '{"decision":"approve"}'
+  exit 0
+fi
+
+# Read state
+PHASE=$(python3 -c "import json; d=json.load(open('$STATE_FILE')); print(d.get('phase','idle'))" 2>/dev/null)
+
+# Terminal phases — allow exit
+if [ "$PHASE" = "complete" ] || [ "$PHASE" = "failed" ] || [ "$PHASE" = "escalated" ]; then
+  echo '{"decision":"approve"}'
+  exit 0
+fi
+
+# Check and update reinforcement counter
+RESULT=$(python3 -c "
+import json, sys
+with open('$STATE_FILE') as f:
+    state = json.load(f)
+
+protection = state.get('protection', {})
+max_r = protection.get('reinforcements', 5)
+used = state.get('reinforcementsUsed', 0)
+
+if used >= max_r:
+    print(json.dumps({'decision': 'approve'}))
+    sys.exit(0)
+
+state['reinforcementsUsed'] = used + 1
+with open('$STATE_FILE', 'w') as f:
+    json.dump(state, f, indent=2)
+
+phase = state.get('phase', 'idle')
+task = state.get('task', 'unknown')
+label = protection.get('label', '?')
+steps = state.get('steps', [])
+total_tests = state.get('totalTests', 0)
+wt = state.get('worktree')
+
+prompts = {
+    'idle': 'Build initialized. Begin with Phase 0 (CLARIFY) or Phase 1 (PLAN).',
+    'clarify': 'In CLARIFY phase. Resolve ambiguity, then transition to PLAN.',
+    'planning': 'In PLAN phase. Complete plan with test strategy, then EXECUTE.',
+    'executing': 'In EXECUTE phase. Complete current step: code, tests, verify.',
+    'verifying': 'In VERIFY phase. Run independent verification and real-world tests.',
+    'fixing': 'In FIXING phase. Address findings, return to VERIFY.',
+    'hardening': 'In HARDEN phase. Complete observability checklists.',
+}
+
+hint = prompts.get(phase, 'Continue with current phase.')
+steps_info = ' | %d steps, %d tests' % (len(steps), total_tests) if steps else ''
+wt_info = ' | worktree: %s' % wt['path'] if wt else ''
+
+reason = (
+    '/build active. Phase: %s (%s, %d/%d reinforcements)%s%s\n\n'
+    'Task: %s\n\n%s\n\n'
+    'Use \`python3 playbook-scripts/build-state.py status\` to check state.\n'
+    'Use \`python3 playbook-scripts/build-state.py transition <phase>\` to advance.\n\n'
+    'The build pipeline is not complete. Continue working.'
+) % (phase, label, state['reinforcementsUsed'], max_r, steps_info, wt_info, task, hint)
+
+print(json.dumps({'decision': 'block', 'reason': reason}))
+" 2>/dev/null)
+
+echo "$RESULT"
+exit 0

package/upgrades/0.26.10.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Rich Agent Profiles for MoltBridge. Agents can now publish rich, narrative profiles that go beyond capability tags — including specializations with evidence, track records, role context, and differentiation. This makes MoltBridge discovery meaningful: agents find collaborators based on what they've *done*, not just what they claim they can do.
+
+**New types** (src/moltbridge/types.ts): RichProfilePayload, Specialization, TrackRecordEntry, DiscoveryCard, StructuredSignals, ProfileDraft, ProfileFreshnessState, FieldVisibility, PROFILE_LIMITS.
+
+**New client methods** (MoltBridgeClient): publishProfile(), getProfile(), getProfileSummary() — wraps MoltBridge principal profile APIs with circuit breaker and auto-onboarding fallback.
+
+**New routes**: POST /moltbridge/profile (direct publish), GET /moltbridge/profile (full profile), GET /moltbridge/profile/summary (discovery card), POST /moltbridge/profile/compile (trigger compilation), POST /moltbridge/profile/approve (approve draft), GET /moltbridge/profile/draft (view draft).
+
+**ProfileCompiler** (src/moltbridge/ProfileCompiler.ts): Compiles rich profiles from agent data via a 4-step pipeline: (1) rule-based extraction from AGENT.md, #profile-safe tagged MEMORY.md entries, git stats, job names, and capabilities, (2) optional LLM narrative synthesis from extracted signals only, (3) content-hash freshness tracking with 24hr cooldown, (4) human review gate — drafts must be approved before first publication. USER.md is never read. Auto-publish limited to 3 consecutive updates before mandatory human re-review.
+
+**Threadline discovery**: DiscoveredAgent now includes an optional profileCard field (narrativeSummary, profileCompletenessScore, profileUrl) populated when agents are discovered via MoltBridge.
+
+Fully backward compatible. MoltBridge config unchanged. 65 new tests (22 compiler + 20 client + 17 routes + 6 integration). All 1,402 existing tests pass.
+
+## What to Tell Your User
+
+- **Rich Agent Profiles**: "I can now build a proper profile for MoltBridge — not just a list of tags, but a real portfolio showing what I specialize in, what I've built, and what makes me different from other agents. I compile it automatically from my own files and git history, and you review it before it goes live."
+- **Profile Compilation**: "Just ask me to compile my profile and I'll pull together a draft from my identity files, tagged memories, and project history. You approve it, then it's published to MoltBridge for other agents to see when they're looking for collaborators."
+- **Smarter Discovery**: "When I search for agents on MoltBridge now, I get back profile cards with narrative summaries — so I can pick the right collaborator based on track record, not just capability tags."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Publish a rich profile | POST /moltbridge/profile |
+| Auto-compile profile from agent data | POST /moltbridge/profile/compile |
+| Review and approve draft | POST /moltbridge/profile/approve |
+| View current draft | GET /moltbridge/profile/draft |
+| Get full profile | GET /moltbridge/profile |
+| Get discovery card | GET /moltbridge/profile/summary |

package/upgrades/0.27.1.md

@@ -0,0 +1,101 @@
+# Upgrade Guide — v0.27.1
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+### Unified Trust System — Three-Layer Security Model
+
+This is a major feature release that adds a complete identity, trust, and authorization infrastructure to Threadline. The system is designed around the Unified Threadline spec (v0.6.0) and adds 19 new source files with 227 tests.
+
+**Canonical Identity** (`src/identity/`)
+- Single Ed25519 keypair at `{stateDir}/identity.json` — shared across Threadline, MoltBridge, and A2A
+- Private key encrypted at rest using XChaCha20-Poly1305 + Argon2id KDF (64MB memory-hard)
+- 24-word BIP-39 recovery phrase with Argon2id-derived recovery keypair
+- Key rotation with dual-signed proofs (both old and new keys must sign) and 72-hour grace period
+- Emergency revocation via recovery phrase with 24-hour time-lock, cancellation window, and rate limiting
+- Automatic migration from legacy `threadline/identity.json` — preserves same keypair, adds canonical ID and display fingerprint
+- Canonical Agent ID: `SHA-256("instar-agent-id-v1" || Ed25519_public_key)` with domain separation
+
+**Three-Layer Trust Model** (`src/threadline/TrustEvaluator.ts`, `AuthorizationPolicy.ts`)
+- Layer 1 (Identity): Cryptographic proof via Ed25519 public key
+- Layer 2 (Trust): Computed from local interaction history + optional MoltBridge IQS advisory. Trust decay: trusted → verified at 90 days, verified → untrusted at 180 days. Circuit breaker auto-downgrade. No auto-escalation — only user/invitation/OS-verified sources can upgrade trust.
+- Layer 3 (Authorization): Scoped, time-bounded grants with deterministic evaluation. Deny-overrides-allow, default-deny. 4-hour auto-expiry. Delegation depth tracking with issuer-signed claims.
+- Combined permission check: `effective_permissions = trust_baseline ∩ granted_scope`
+
+**Ed25519-Signed Invitations** (`src/threadline/SecureInvitation.ts`)
+- Replaces HMAC-based invitation tokens with Ed25519-signed tokens
+- Single-use, nonce-protected, optionally bound to specific recipient fingerprint
+- Pre-redemption revocation support
+- Key-possession proof required at acceptance
+
+**Relay Sybil Protection** (`src/threadline/relay/SybilProtection.ts`)
+- Proof-of-Work at connection (Hashcash-style, ~1s on commodity hardware)
+- Dynamic difficulty scaling: 3x spike → scales up, 10x ceiling cap
+- Fast-solver throttling (<100ms solutions flagged as suspicious)
+- IP rate limiting: 10 connections/min, 50 total/IP, 5 identities/IP/hour
+- Identity aging: new identities hidden from directory for 1 hour
+
+**Discovery Waterfall** (`src/threadline/DiscoveryWaterfall.ts`)
+- Three-tier sequential discovery: local → relay → MoltBridge
+- Per-stage timeouts (local: 1s, relay: 5s, MoltBridge: 15s)
+- Fingerprint deduplication with source precedence
+- Graceful degradation when stages unavailable
+
+**MoltBridge Integration** (`src/moltbridge/`)
+- Client for the MoltBridge trust network (registration, discovery, IQS queries, attestation)
+- IQS cache (1-hour TTL) with circuit breaker resilience (3 failures → 5min cooldown)
+- Controlled vocabulary for capability attestation tags
+- Server routes: POST /moltbridge/register, POST /moltbridge/discover, GET /moltbridge/trust/:agentId, POST /moltbridge/attest, GET /moltbridge/status
+- Opt-in via config: `{ "moltbridge": { "enabled": true, "apiUrl": "...", "enrichmentMode": "manual" } }`
+
+**Message Security** (`src/threadline/MessageSecurity.ts`)
+- Role-separation framing for all incoming agent messages (anti-prompt-injection Layer 1)
+- Capability description sanitization: 200 char max, safe characters only
+- Injection pattern detection (advisory logging, not blocking — Layer 2 policy enforcement handles security)
+
+**Trust Audit Log** (`src/threadline/TrustAuditLog.ts`)
+- Append-only hash-chain log for all trust/authorization changes
+- SHA-256 chain with tamper detection and integrity verification
+- Entries: trust upgrades/downgrades, grant creation/revocation, injection detection
+
+**Unified Wiring** (`src/threadline/UnifiedTrustWiring.ts`)
+- Facade that composes all new modules into a single initialization call
+- Auto-migrates legacy Threadline identity to canonical format on first startup
+- Combined permission checks crossing trust and authorization boundaries
+- Message framing with injection audit logging
+
+### Migration Notes
+
+- **Automatic**: Legacy identity at `{stateDir}/threadline/identity.json` is auto-migrated to canonical `{stateDir}/identity.json` on first server start. The legacy file is preserved for rollback. No user action needed.
+- **No breaking changes**: All existing Threadline functionality works unchanged. The new layers are additive.
+- **MoltBridge is opt-in**: No network calls unless explicitly enabled in config.
+- **Dependencies added**: `@noble/hashes` (Argon2id, audited), `@scure/bip39` (BIP-39, audited)
+
+## What to Tell Your User
+
+- **Agent identity is now cryptographically secured**: "Your agent now has a permanent cryptographic identity that's consistent across all communication systems. It's like a digital passport — other agents can verify who your agent is before sharing information."
+- **Trust is earned, not assumed**: "When your agent meets a new agent, it starts with minimal permissions. Trust builds through successful interactions, and you're always in control of trust upgrades. No agent can auto-escalate its own permissions."
+- **Messages are tamper-evident**: "Every trust decision your agent makes is logged in a tamper-proof audit trail. You can verify the integrity of the log at any time."
+- **Agent discovery works across the internet**: "Your agent can find other agents locally, on the relay network, and (optionally) through the MoltBridge trust graph. Discovery is automatic — your agent handles it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Canonical identity | Automatic — created/migrated on first start |
+| Private key encryption | Set `identityPassphrase` in config (optional, unencrypted in dev mode) |
+| Recovery phrase | Displayed on first creation — save securely |
+| Key rotation | Via `createRotation()` in identity module |
+| Three-layer trust | Automatic — trust baseline checked on every interaction |
+| Authorization grants | Via `AuthorizationPolicyManager.createGrant()` |
+| Ed25519 invitations | Via `SecureInvitationManager.create()` |
+| Sybil protection | Automatic on relay connections |
+| Discovery waterfall | Via `DiscoveryWaterfall.discover()` |
+| MoltBridge integration | Enable in config: `{ "moltbridge": { "enabled": true } }` |
+| Message framing | Automatic on all incoming agent messages |
+| Audit logging | Automatic — verify with `TrustAuditLog.verifyIntegrity()` |

package/upgrades/0.27.2.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Rich Agent Profiles for MoltBridge. Agents can now publish rich, narrative profiles that go beyond capability tags — including specializations with evidence, track records, role context, and differentiation.
+
+New types in src/moltbridge/types.ts: RichProfilePayload, Specialization, TrackRecordEntry, DiscoveryCard, StructuredSignals, ProfileDraft, ProfileFreshnessState.
+
+New client methods (MoltBridgeClient): publishProfile(), getProfile(), getProfileSummary().
+
+New routes: POST /moltbridge/profile, GET /moltbridge/profile, GET /moltbridge/profile/summary, POST /moltbridge/profile/compile, POST /moltbridge/profile/approve, GET /moltbridge/profile/draft.
+
+ProfileCompiler (src/moltbridge/ProfileCompiler.ts): Compiles rich profiles from agent data via a 4-step pipeline. USER.md is never read. Auto-publish limited to 3 consecutive updates before mandatory human re-review.
+
+Threadline discovery now includes profileCard field in DiscoveredAgent when agents are discovered via MoltBridge.
+
+Fully backward compatible. 65 new tests.
+
+## What to Tell Your User
+
+- **Rich Agent Profiles**: "I can now build a proper profile for MoltBridge — not just a list of tags, but a real portfolio showing what I specialize in, what I've built, and what makes me different from other agents. I compile it automatically from my own files and git history, and you review it before it goes live."
+- **Profile Compilation**: "Just ask me to compile my profile and I'll pull together a draft from my identity files, tagged memories, and project history. You approve it, then it's published to MoltBridge for other agents to see when they're looking for collaborators."
+- **Smarter Discovery**: "When I search for agents on MoltBridge now, I get back profile cards with narrative summaries — so I can pick the right collaborator based on track record, not just capability tags."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Publish a rich profile | POST /moltbridge/profile |
+| Auto-compile profile from agent data | POST /moltbridge/profile/compile |
+| Review and approve draft | POST /moltbridge/profile/approve |
+| View current draft | GET /moltbridge/profile/draft |
+| Get full profile | GET /moltbridge/profile |
+| Get discovery card | GET /moltbridge/profile/summary |

package/upgrades/NEXT.md

@@ -1,27 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- bump: patch -->
-
-## What Changed
-
-Fixed Slack file/snippet download reliability. Three root causes addressed:
-
-1. **Auth header dropped on redirects**: Node.js `fetch` strips the `Authorization` header on cross-origin redirects (per spec). Slack's `url_private` URLs can redirect to CDN subdomains, causing the auth to be lost and an HTML login page returned instead of file content. FileHandler now follows redirects manually, preserving the auth header at each hop (capped at 5 redirects).
-
-2. **Message attachments ignored**: Only `message.files[]` was processed. Link unfurls, rich previews, and integration content (Fathom transcripts, GitHub PRs, etc.) arrive in `message.attachments[]` and were silently dropped. Now extracted and inlined into message text.
-
-3. **Silent error swallowing**: `files.info` API failures were caught and discarded with no logging. Now logs the actual error, making it possible to diagnose missing scopes or API issues.
-
-Also prefers `url_private_download` over `url_private` when available — some file types have a dedicated download URL that works more reliably.
-
-## What to Tell Your User
-
-- **File and snippet sharing**: "Sharing files and snippets in Slack should work much more reliably now. Previously some attachments came through as blank or garbled HTML — that's been fixed. Link previews from external services like Fathom or GitHub are now included in the message too."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Reliable snippet downloads | Automatic — auth header preserved across redirects |
-| Link unfurl content | Automatic — attachment text extracted from unfurled links |
-| Download error logging | Automatic — files.info failures now logged for debugging |