instar 1.3.436 → 1.3.437

package/skills/spec-converge/scripts/write-convergence-tag.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * write-convergence-tag.mjs — stamp a spec's frontmatter with the convergence tag.
+ *
+ * Called by the /spec-converge skill at Phase 5 after a round produces zero
+ * material findings. Writes review-convergence, review-iterations, and
+ * review-report fields into the spec's YAML frontmatter (preserving any other
+ * frontmatter fields the spec author set).
+ *
+ * Usage:
+ *   node skills/spec-converge/scripts/write-convergence-tag.mjs \
+ *     --spec docs/specs/<slug>.md \
+ *     --iterations 3 \
+ *     --report docs/specs/reports/<slug>-convergence.md \
+ *     [--cross-model-review "<flag value>"] \
+ *     [--cross-model-reason "<reason>"]
+ *
+ * The optional --cross-model-review flag records the external (non-Claude)
+ * reviewer posture on the spec frontmatter (Step B of the tiered-dev process,
+ * docs/specs/codex-crossreview-stepB-spec.md §2/§4). This is the FINAL
+ * spec-level value the skill computes via aggregateRoundOutcomes() across all
+ * convergence rounds (a single round's status is per-round; the spec gets one).
+ * Valid values:
+ *   - codex-cli:<model>                       (a supported reviewer ran in >=1 round)
+ *   - codex-cli:<model> (degraded: <reason>)  (present but a given round's call failed)
+ *   - degraded-all-rounds                     (present every round, ZERO succeeded —
+ *                                              as loud as unavailable; spec converged
+ *                                              with no real external opinion)
+ *   - unavailable                             (no supported framework)
+ *   - skipped-abbreviated                     (author chose the fast path)
+ * This script does NOT enum-validate the value (it accepts any string and
+ * quotes it safely) — the canonical accepted set lives in crossModelReviewer.ts
+ * (CrossModelFlagStatus) and is documented here for the caller.
+ * It is DISCLOSURE, not a gate — it does not change /instar-dev's
+ * review-convergence + approved enforcement. Idempotent (re-run strips and
+ * rewrites the field, like the review-* fields).
+ *
+ * Does NOT write `approved: true` — that tag is the user's structural
+ * contribution. /spec-converge only ever writes the machine-verifiable
+ * review-convergence chain.
+ *
+ * Exit codes:
+ *   0 — tag written successfully
+ *   1 — usage error, spec not found, or frontmatter malformed
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkEli16Overview } from '../../../scripts/eli16-overview-check.mjs';
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const out = {
+    spec: null,
+    iterations: null,
+    report: null,
+    crossModelReview: null,
+    crossModelReason: null,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--spec') out.spec = args[++i];
+    else if (a === '--iterations') out.iterations = parseInt(args[++i], 10);
+    else if (a === '--report') out.report = args[++i];
+    else if (a === '--cross-model-review') out.crossModelReview = args[++i];
+    else if (a === '--cross-model-reason') out.crossModelReason = args[++i];
+    else {
+      console.error(`Unknown arg: ${a}`);
+      process.exit(1);
+    }
+  }
+  if (!out.spec || !out.report || !Number.isFinite(out.iterations)) {
+    console.error(
+      'Usage: write-convergence-tag.mjs --spec PATH --iterations N --report PATH ' +
+        '[--cross-model-review VALUE] [--cross-model-reason REASON]',
+    );
+    process.exit(1);
+  }
+  return out;
+}
+
+const {
+  spec: specArg,
+  iterations,
+  report: reportArg,
+  crossModelReview,
+  crossModelReason,
+} = parseArgs();
+
+const ROOT = path.resolve(new URL('../../..', import.meta.url).pathname);
+const specPath = path.resolve(ROOT, specArg);
+const reportPath = path.resolve(ROOT, reportArg);
+
+if (!fs.existsSync(specPath)) {
+  console.error(`Spec not found: ${specArg}`);
+  process.exit(1);
+}
+if (!fs.existsSync(reportPath)) {
+  console.error(`Report not found: ${reportArg}`);
+  process.exit(1);
+}
+
+const content = fs.readFileSync(specPath, 'utf-8');
+
+// ─── ELI16 overview check ────────────────────────────────────────────────
+// Convergence cannot be stamped onto a spec without a plain-English overview.
+const _fmHeadMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+const _eli16Result = checkEli16Overview(specPath, _fmHeadMatch ? _fmHeadMatch[1] : '');
+if (!_eli16Result.ok) {
+  if (_eli16Result.reason === 'missing') {
+    console.error(
+      `Spec ${specArg} has no ELI16 overview.\n` +
+      `Convergence cannot be stamped without a plain-English companion at:\n` +
+      `  • Sibling path: ${path.relative(ROOT, _eli16Result.siblingPath)}\n` +
+      `  • OR declared via spec frontmatter: eli16-overview: <relative-path>\n` +
+      `See skills/instar-dev/templates/eli16-overview.md for the expected shape.`,
+    );
+  } else if (_eli16Result.reason === 'declared-not-found') {
+    console.error(
+      `Spec ${specArg} declares an ELI16 overview at ${path.relative(ROOT, _eli16Result.declaredPath)},\n` +
+      `but that file does not exist.`,
+    );
+  } else if (_eli16Result.reason === 'too-short') {
+    console.error(
+      `Spec ${specArg}'s ELI16 overview at ${path.relative(ROOT, _eli16Result.declaredPath)} is too short ` +
+      `(${_eli16Result.charCount} chars, need ${_eli16Result.minChars}).\n` +
+      `A stub isn't an overview. See skills/instar-dev/templates/eli16-overview.md.`,
+    );
+  }
+  process.exit(1);
+}
+
+// Parse YAML frontmatter manually (no dependency).
+// Expect: /^---\n<body>\n---\n<rest>/
+const FM_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+const match = content.match(FM_RE);
+if (!match) {
+  console.error(
+    `Spec ${specArg} has no YAML frontmatter block at the top. ` +
+    'Add one before running /spec-converge.',
+  );
+  process.exit(1);
+}
+const [, fmBody, rest] = match;
+
+// Strip any existing managed lines (review-* chain + cross-model-review chain)
+// so re-runs are idempotent — the field is rewritten, never duplicated.
+const preservedLines = fmBody
+  .split('\n')
+  .filter(
+    (l) =>
+      !/^\s*review-convergence\s*:/.test(l) &&
+      !/^\s*review-iterations\s*:/.test(l) &&
+      !/^\s*review-completed-at\s*:/.test(l) &&
+      !/^\s*review-report\s*:/.test(l) &&
+      !/^\s*cross-model-review\s*:/.test(l) &&
+      !/^\s*cross-model-review-reason\s*:/.test(l),
+  )
+  .join('\n')
+  .trim();
+
+const ts = new Date().toISOString();
+const reportRel = path
+  .relative(ROOT, reportPath)
+  .replace(/\\/g, '/');
+
+// Double-quote a YAML scalar value, escaping embedded quotes/backslashes so a
+// flag like `codex-cli:gpt-5.5 (degraded: timeout)` (colon + parens) parses.
+function yamlQuote(v) {
+  return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+const newFmLines = [
+  preservedLines,
+  `review-convergence: "${ts}"`,
+  `review-iterations: ${iterations}`,
+  `review-completed-at: "${ts}"`,
+  `review-report: "${reportRel}"`,
+];
+
+// Cross-model review posture (Step B). Disclosure-only; additive.
+if (crossModelReview) {
+  newFmLines.push(`cross-model-review: ${yamlQuote(crossModelReview)}`);
+  if (crossModelReason) {
+    newFmLines.push(`cross-model-review-reason: ${yamlQuote(crossModelReason)}`);
+  }
+}
+
+const newFm = newFmLines.join('\n');
+
+const newContent = `---\n${newFm}\n---\n${rest}`;
+fs.writeFileSync(specPath, newContent, 'utf-8');
+
+console.log(
+  `Tagged ${specArg}:\n` +
+    `  review-convergence=${ts}\n` +
+    `  review-iterations=${iterations}\n` +
+    `  review-report=${reportRel}`,
+);

package/skills/spec-converge/templates/report.md

@@ -0,0 +1,76 @@
+# Convergence Report — {{SPEC_TITLE}}
+
+**Spec:** [{{SPEC_PATH}}]({{SPEC_PATH}})
+**Slug:** `{{SPEC_SLUG}}`
+**Converged at:** {{CONVERGED_AT}}
+**Iterations:** {{ITERATION_COUNT}}
+**Final-round material findings:** 0
+
+---
+
+## ELI10 Overview
+
+<!--
+Two or three paragraphs in plain English. No jargon. Tell the user:
+1. What this spec is (the problem it solves, the design it proposes)
+2. Why it matters — what changes for users if it ships
+3. The main tradeoffs — what this design does well and what it deliberately doesn't do
+
+Tone: "We're adding a way for different parts of the agent to know what each
+other is doing, because right now the user-facing session and the session
+handling agent-to-agent messages are blind to each other..."
+
+Assume the reader is smart but not a systems engineer. The user should be able
+to read this section alone and decide whether to approve.
+-->
+
+## Original vs Converged
+
+<!--
+A dedicated section describing what the review process changed, also in
+ELI10 terms. This is the most important section for the user to read.
+
+Structure as: "Originally the spec said X. After review, it now says Y,
+because [plain-English reason]."
+
+Cover the 3-6 most significant changes. Skip cosmetic/minor ones. If a
+major redesign happened, put that first.
+
+Example:
+  - Originally: any session could write anything to the ledger.
+    After review: writes are restricted to a curated set of server-side
+    sources. Why: untrusted writes made adversarial scenarios (session
+    writing false commitments, poisoning context) too hard to defend
+    against — the safer default is "read-only to sessions, writes only
+    from infrastructure the user controls."
+
+The user reads this section to understand what convergence changed.
+-->
+
+## Iteration Summary
+
+| Iteration | Reviewers who flagged material issues | Material findings | Spec sections changed |
+|-----------|---------------------------------------|-------------------|-----------------------|
+{{ITERATION_TABLE}}
+
+## Full Findings Catalog
+
+<!--
+Structured dump for detail-oriented readers. Organize by iteration,
+then by reviewer perspective. For each finding: severity, reviewer,
+original finding text, resolution taken.
+-->
+
+{{FINDINGS_CATALOG}}
+
+## Convergence Verdict
+
+{{CONVERGENCE_VERDICT}}
+
+<!--
+Plain statement: "Converged at iteration N. The final review round
+produced zero material findings. Spec is ready for user review and
+approval. To approve: edit the spec's frontmatter to set approved: true
+(or run `instar spec approve {{SPEC_SLUG}}`), then /instar-dev can
+proceed with implementation."
+-->

package/skills/spec-converge/templates/reviewer-adversarial.md

@@ -0,0 +1,37 @@
+# Reviewer Prompt — Adversarial Perspective
+
+You are the adversarial reviewer for an instar spec under convergence review.
+
+Read these in order:
+
+1. The spec file at {SPEC_PATH}
+2. Any architectural doc the spec references.
+
+Your ADVERSARIAL perspective: assume at least one session, subsystem, or input source is misbehaving — not malicious in the threat-actor sense, but wrong, hallucinating, confused, or buggy. What goes wrong when the system is used WRONG?
+
+Specifically check:
+
+1. **Bad-input poisoning** — can a confused session write false entries that other sessions treat as truth? What's the downstream effect?
+
+2. **Self-reinforcing loops** — can a session read its own bad output, act on it, and write a new confirmation that another session amplifies?
+
+3. **Stale state** — does the system distinguish between a fact that was true 3 weeks ago and one that's still true? If not, how does the reader know?
+
+4. **Authority ambiguity** — can a reader of this state mistakenly attribute another session's work to itself or to the wrong party? (The 2026-04-15 incident is the canonical example — user-facing session re-asserting a threadline-session's commitment to the human user.)
+
+5. **Rate-based attacks** — can a chatty or buggy session flood a storage/signal layer and crowd out important entries via rotation or eviction?
+
+6. **Kind/label gaming** — are enumerated types or tags trusted from their source without verification? Can a misclassifying writer corrupt downstream reasoning?
+
+7. **Provenance** — does the system bind provenance (session id, agent id, timestamp) from authoritative sources, or does it accept client-supplied strings that could be forged?
+
+8. **Graceful degradation** — does the design hold up when the hot path is broken? What does the reader see when the writer is wrong?
+
+9. **Anything else** about how the system fails when used wrong.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- Specific findings with spec-section references and concrete resolutions.
+
+Be rigorous. The system only works if graceful degradation is designed in.

package/skills/spec-converge/templates/reviewer-cross-model.md

@@ -0,0 +1,28 @@
+# Reviewer Prompt — Cross-Model External Perspective
+
+You are an EXTERNAL, non-Claude reviewer (a GPT-tier model) auditing an instar spec under convergence review.
+
+The spec under review — at the path `{SPEC_PATH}` — and all of its supporting context are **inlined below** in this prompt (you have no filesystem or repo access; do not try to open any file). The spec follows a `--- SPEC UNDER REVIEW: ... ---` marker; any architectural context the spec references follows under `--- CONTEXT: <path> ---` markers. Review only what is inlined here. If a `--- NOTE: referenced context was TRUNCATED ---` marker is present, your view of the supporting docs is partial — flag any finding that depends on context you could not see.
+
+Your perspective is deliberately OUTSIDE the Claude family. You may notice blind spots that Claude models share. Specifically look for:
+
+1. **Architectural clarity** — is the design easy to understand? Are there implicit assumptions the author is making that a reader from outside their context wouldn't share?
+
+2. **Alternative designs** — is the chosen design the obvious one, or are there significant alternatives the spec doesn't acknowledge? If so, why was this chosen over those?
+
+3. **Industry patterns** — does this design reinvent a solved problem? Could an existing library, protocol, or pattern (distributed logs, CRDTs, message queues, workflow engines) do this better?
+
+4. **Failure modes** — from an outside perspective, what's the most likely way this design fails that the author wouldn't have considered?
+
+5. **Language / clarity** — are there sections where the spec assumes too much reader knowledge? Where's the terminology locally-defined vs industry-standard?
+
+6. **Model-family blind spots** — Claude models tend to over-index on: safety fences, consent flows, structured JSON responses, LLM-as-authority patterns. Is the spec over-reliant on any of these where a simpler non-LLM approach would serve better?
+
+7. **Anything else** you'd flag as a non-Claude reviewer.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- Findings with spec-section references and concrete resolutions.
+
+Your independence is the value. Agree with other reviewers where it's warranted, but if you see something they missed because of shared priors, surface it.

package/skills/spec-converge/templates/reviewer-integration.md

@@ -0,0 +1,39 @@
+# Reviewer Prompt — Integration / Deployment Perspective
+
+You are the integration reviewer for an instar spec under convergence review.
+
+Read these in order:
+
+1. The spec file at {SPEC_PATH}
+2. Any architectural doc the spec references.
+3. `/Users/justin/Documents/Projects/instar/src/core/PostUpdateMigrator.ts` if the spec modifies anything that ships with instar (hooks, scaffold, templates).
+4. `/Users/justin/Documents/Projects/instar/src/core/BackupManager.ts` if the spec adds new persistent state.
+
+Your INTEGRATION perspective: what breaks in real-world deployment scenarios?
+
+Specifically check:
+
+1. **Migration for existing agents** — how does a running agent get this change when they update instar? Is there a post-update migrator hook that needs updating? Does the template file actually ship, or does an inline string literal in the migrator need patching too?
+
+2. **Backward compatibility** — do existing callers of any modified interfaces still work? Are optional parameters handled gracefully?
+
+3. **Auto-update path** — when a user pulls a new version of instar, what automatically propagates? What needs manual intervention?
+
+4. **Multi-machine** — if instar agents are paired across machines, does the new state stay coherent across both, or does each machine develop its own divergent view?
+
+5. **Backup/restore** — is new persistent state included in the backup manifest? If a user runs a snapshot/restore cycle, does the state survive?
+
+6. **Rollback** — if the feature is reverted, what happens to state files, config entries, and background jobs? Is cleanup provided?
+
+7. **Dashboard / observability** — is there a UI surface where users can see what's happening? A feature affecting every session should be visible somewhere.
+
+8. **Config knob** — is there a way to disable the feature if it turns out to be harmful? Default on or off?
+
+9. **Anything else** about deployment, operations, or integration that might surprise in production.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- Specific findings with file references and concrete resolutions.
+
+Be rigorous — things that work in dev often fail in deployment.

package/skills/spec-converge/templates/reviewer-lessons-aware.md

@@ -0,0 +1,101 @@
+# Reviewer Prompt — Lessons-Aware Perspective (8th reviewer)
+
+You are the lessons-aware reviewer for an Instar spec under convergence review.
+
+This is the structural defense against the failure mode documented at `feedback_spec_converge_pre_auth_circular`: when an author writes a spec AND runs its convergence AND self-verifies it, the self-verify step is circular — it confirms the spec agrees with the author's own framing, missing documented hard-earned lessons.
+
+Your job: load the canonical Instar lessons catalog, then check this spec against every entry. Find every contradiction, every backtrack, every unengaged-but-applicable lesson.
+
+## Sources to load (in order)
+
+1. **The spec under review** at `{SPEC_PATH}`.
+2. **The canonical principles + lessons index** at `docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md`. This is the authoritative catalog. Read it in full.
+3. **The author-agent's local feedback memory** at `.instar/memory/feedback_*.md` (relative to the running agent's project root, NOT the instar source). These are per-agent specific lessons that supplement the canonical catalog. If `.instar/memory/` doesn't exist (e.g. running in the instar source repo itself), skip this step.
+4. **The project's CLAUDE.md** (if reviewing an instar-source spec, this is `CLAUDE.md` at instar root; if reviewing a downstream consumer spec, it's the consumer's CLAUDE.md). For the "Standards" + "Anti-Patterns" + "Key Patterns from Dawn" sections.
+5. **Any specific lesson sources the spec already engages with** under `lessons-engaged:` in its frontmatter. Verify the engagement is real, not just citation.
+
+## Your perspective — three structural questions
+
+### Q1. Contradictions (CRITICAL severity)
+
+For each Part 1 principle (P1-P10) and Part 2 architectural lesson (L1-L17) in the index, ask:
+- Does the spec CONTRADICT this principle/lesson?
+- Specifically: does the spec propose something the lesson was written to prevent?
+
+A contradiction is the strongest finding. If found, it requires either spec revision or an explicit `principal-deferral-approval` in the spec frontmatter (per P10 Comprehensive-First Directive).
+
+**Backtrack-tells from the index** — flag these when you see them:
+- `applyXBlock(agentMd, ...)` or `appendCriticalAwareness(...)` → L1 (AGENT.md bloat)
+- "preserve context by exiting before [X]" without LLM gate → L2 (context-death)
+- `review-iterations: 1` with `review-deviation: "abbreviated convergence"` AND no lessons-aware pass → L4 (external review skipped)
+- Stamp/diff-protection on built-in hooks → P3 (Migration Parity §4, hook-event-reporter wedge)
+- "v0.2 deferred: migration backfill" → P3 + L3
+- "Tier 3 e2e queued as follow-up" without explicit pure-data justification → P4
+- "Pre-existing failure, leaving them" → P6 (Zero-Failure)
+- New sentinel/job/loop without `supervision` declaration → P7
+- New wizard with no error-recovery path → P8
+- New autonomy capability with no intent surface → P9
+- Multiple "v0.2 deferred" items without paired ETAs/owners → P10
+- New MCP integration bypassing `external-operation-gate.js` → L11
+- New `execFileSync('git', ['reset', ...])` or `fs.rmSync` not via SafeGitExecutor/SafeFsExecutor → L12
+- Session-spawn code that doesn't take an explicit cwd → L13
+- New external-PR pathway with simpler review than internal → L14
+- New trust-aware surface without `AuthorizationPolicy` evaluation → L15
+- New external service connector without `ExternalOperationGate` → L11
+- Side-effects review with fewer than 7 dimensions covered → L6
+
+### Q2. Unengaged-but-applicable (HIGH severity)
+
+For each principle/lesson, ask:
+- Does the spec touch a surface this lesson covers?
+- If so, does the spec engage with the lesson explicitly (citation + acknowledgment + how it respects the lesson)?
+
+If applicable but not engaged, that's a HIGH finding. The fix: spec must add a `lessons-engaged:` frontmatter entry citing the lesson and explaining how it's respected.
+
+This catches the conversational-action pattern: the spec wasn't *contradicting* the bloat lessons per se, it was *ignoring* them — never named ContextHierarchy, never named Playbook, never named Self-Knowledge Tree. The reviewer must flag missing engagement, not just active contradiction.
+
+### Q3. Behavioral lessons applicable to agent-facing surfaces (MEDIUM severity)
+
+For each Part 3 behavioral lesson (B1-B39), ask:
+- Does the spec propose agent-facing behavior (auto-responses, commitment patterns, messaging, file edits, lifecycle events)?
+- If so, does the behavior respect the documented conduct rule?
+
+Behavioral lessons are usually about HOW the agent acts; specs proposing new agent capabilities must respect them.
+
+## Output format
+
+Produce a structured finding list. For each finding:
+
+```
+### F<N>: <short title>
+
+- **Severity:** critical | high | medium | low
+- **Index reference:** P<N> / L<N> / B<N> (cite the index entry by its label)
+- **Source doc cited by the index:** <file path or memory entry name>
+- **Spec section that triggers the finding:** <quote the section title or paragraph from the spec>
+- **What contradicts/ignores the lesson:** <one-paragraph explanation>
+- **Required resolution:** <concrete edit the spec needs — be specific about file path, section, paragraph>
+- **If deferral acceptable, gate:** <P10 frontmatter requirement>
+```
+
+End with a one-line summary:
+
+```
+SUMMARY: <N> critical, <N> high, <N> medium, <N> low findings. Convergence-blocking: <Y/N>.
+```
+
+Convergence is blocked if any critical OR high findings are unresolved.
+
+## What this reviewer is NOT
+
+- Not the security/scalability/adversarial/integration reviewers — they cover their own perspectives. You're specifically focused on "what documented Instar lessons does this spec contradict or fail to engage with?"
+- Not a code reviewer — you don't read source files unless the spec references them.
+- Not an architectural reviewer — you're checking against historical lessons, not first-principles design.
+
+If the spec is structurally fine but doesn't engage with applicable lessons, your finding is "missing engagement" not "missing design rigor."
+
+## Confidence note
+
+If you're uncertain whether something is a real backtrack vs. a justified tradeoff, flag it as MEDIUM and let the author resolve in the spec. Do not pad findings — only flag what's substantive.
+
+If you find zero findings, your report says "Lessons-aware review: no contradictions or missing engagements found. Spec respects all applicable principles + lessons." (Don't pad with affirmations of every passed check.)

package/skills/spec-converge/templates/reviewer-scalability.md

@@ -0,0 +1,35 @@
+# Reviewer Prompt — Scalability / Performance Perspective
+
+You are the scalability reviewer for an instar spec under convergence review.
+
+Read these in order:
+
+1. The spec file at {SPEC_PATH}
+2. Any architectural doc the spec references.
+
+Your SCALABILITY perspective: what breaks under real load, over time, or at scale?
+
+Specifically check:
+
+1. **Hot paths** — what runs on every request, every turn, every session? What's the cost of those hot paths at typical and pathological input sizes?
+
+2. **Growth model** — what state does this add that accumulates over time? Is there a retention policy? A rotation mechanism? What happens at 1k entries, 10k entries, 100k entries?
+
+3. **Concurrent operations** — can two operations race? Is there locking where it's needed? Are acks, retries, or writes safe under concurrent access?
+
+4. **Memory** — what's the memory cost per operation? Is there ephemeral allocation that GC will pressure?
+
+5. **Event loop blocking** — is any sync I/O on the request path? Could slow disk cause cascading stalls?
+
+6. **Fail-open semantics** — when something fails, does it fail silently or surface a signal? Could an outage of this feature be invisible to operators?
+
+7. **Hook latency impact** — for changes that touch session-start hooks, what's the cumulative cost at max input size?
+
+8. **Anything else** about performance, scaling, or operational cost at scale.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- Specific findings with spec-section references and concrete resolutions.
+
+Be rigorous — things that work in dev often fail at scale.

package/skills/spec-converge/templates/reviewer-security.md

@@ -0,0 +1,36 @@
+# Reviewer Prompt — Security Perspective
+
+You are the security reviewer for an instar spec under convergence review.
+
+Read these in order:
+
+1. The spec file at {SPEC_PATH}
+2. `/Users/justin/Documents/Projects/instar/docs/signal-vs-authority.md` — the architectural principle every instar spec must comply with.
+3. Any architectural doc the spec references (typically under `docs/`).
+
+Your SECURITY perspective: what attack surfaces, leaks, or abuse paths could this design open?
+
+Specifically check:
+
+1. **File system exposure** — what permissions do new files get? Could other users on the machine read sensitive data? Are backups, git, or support bundles at risk of including sensitive derived content?
+
+2. **Prompt injection vectors** — is anything written by one session read into another session's prompt context? If so, what is the blast radius of an adversarial or compromised writer?
+
+3. **Auth on endpoints** — are all new HTTP endpoints bearer-token-gated? What happens if the token leaks via logs, screenshots, or a Cloudflare tunnel being enabled?
+
+4. **Trust boundaries** — does the design respect threadline's per-thread message sandboxing? Does it cross any other security boundary established in existing specs?
+
+5. **Race conditions** — are there places where concurrent operations could produce inconsistent or dangerous state?
+
+6. **Input sanitization** — does untrusted input get validated at the edge? Length caps, enum checks, type checks?
+
+7. **DoS surfaces** — are any read paths O(n) over growing state? Can an authenticated but malicious caller exhaust CPU/memory?
+
+8. **Anything else** that occurs to you.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- If issues: bullet them with specific spec-section references and recommended resolution for each.
+
+Be rigorous. Your job is to catch what the author missed. Assume the spec will ship — every issue you don't flag could become a real production incident.