The Trilogy Times

Reworks the Linear queue so the agent works the ticket and updates Linear itself. No GitHub Issue in between.

## What was wrong

The first version mirrored each ticket as a GitHub Issue and left the intake path to pick it up from an @heimdall mention. That was wrong three ways:

- Linear is the system of record. A shadow Issue means two places to look and two to update, while the ticket that actually counts goes stale in Today.

- It was a relay, and a relay substitutes for capability. Four mechanical hops existed because the agent wasn't simply handed the job — the same weakness this project exists to remove, moved from the prompt into the plumbing.

- The relay never fired. Nothing posted the mention. Seven tickets were claimed and parked rather than worked; I'd asserted the handoff instead of testing it, and every dry run stopped one step short of the gap.

## What replaces it

linear becomes a third source for the existing intake job:

| mode | sources from |

|---|---|

| triage | dispatcher blob |

| issue | issue thread |

| linear | the ticket |

All three then run the same diagnose → fix → PR. Reusing the path by changing its *source* is the reuse; materialising a fake artifact to re-trigger it was not.

The context matches issue-intake byte for byte — same payload.issue_title / issue_body / issue_comments, same pipeline_id extraction rules — so the prompt and every downstream stage are untouched. If the shape had to differ, the reuse would be a fiction.

## The state move is the claim

The queue query filters on workflow state, so a ticket only stops being eligible once it has moved to For Review. That's why the update step warns loudly when the move fails while the PR link and comment merely warn: a ticket left in the queue state with a PR against it gets re-picked next sweep.

The step is continue-on-error because the PR is the real deliverable and is already open — a Linear hiccup mustn't turn a successful fix into a red run. But the writes are ordered so the PR link, the durable record a human needs, lands before the state move that can fail.

## Deleted

167 lines: the standalone linear job, plus issue_body, issue_title, find_existing_issue, the title-as-idempotency-key and its prefix-collision guard. All of it existed only to support an artifact that shouldn't have been created — including two bugs found in that scaffolding during review of #54.

## Credential boundary

The key is held only by ctxprep, which reads the ticket and runs no agent. Ticket text is untrusted input; the credential must not be anywhere the agent's process can reach.

## Caller

[AI-Builder-Team/Surtr#1622](https://github.com/AI-Builder-Team/Surtr/pull/1622) — merge this first, it removes the job and declares the new input.

822 tests, ruff and actionlint clean.

## Business Value

Makes Linear actually the system of record for agent work, which is what the team's own working rules require: state current, PR linked, Done on merge. It also removes an entire class of failure — the previous design had four places to break between "ticket picked" and "work started", and broke at one of them silently.

## Manual Effort Estimate

~4 hours, including the cleanup of nine shadow Issues and nine parked tickets the old design produced. *(Proposed by Claude — Keval to confirm.)*

Closes AI-617.

## Why this one matters more than it looks

--allow-critical cannot survive the only workflow anyone would use it in: fix the finding, push, summon a re-review.

The concurrency group is shared across event types with cancel-in-progress on pull_request, so the push cancels the summon that follows it seconds later. The flag lived only in the comment body, so it died with the cancelled run. The surviving push run withheld auto-approve, and nothing in the logs said the flag had been dropped — it read as a considered refusal. Observed four times on #49.

Every heimdall change is a workflow change, so the sensitive-path hold fires on all of them and the documented way to lift it silently failed. That is worse than having no escape hatch. It is why the last two merges today needed --admin.

## The change

A trusted human's --allow-critical now also lands a label on the PR, and every later run reads it.

- Read is free and early. Labels are already in this job's env for both event types, so the check works before the App token exists — which matters, because the gate runs long before it.

- Write is late and best-effort. It needs the token, and the grant already applies to the run that created it, so a failure to persist costs the next run's inheritance rather than this run's review. A red run here would be the worse outcome.

- Visible and revocable, which a flag buried in one comment never was. Removing the label withdraws the grant.

## What is deliberately unchanged

Only a trusted human can create the grant. Heimdall is a trusted summoner for ordinary reviews, and a bot still must never lift the critical-path hold.

Scope is per-PR, and every other guard — bot author, failing CI, truncated diff, coverage ledger — still runs on every push. A later commit to a granted PR is fully reviewed; only the path hold is lifted.

Unreadable labels mean no grant. This lifts a safety hold, so absence and unreadability both have to resolve to "no".

## Tests

11 cases, executing the gate's own label-detection python rather than a copy of it, including malformed and wrong-shaped label payloads. Verified non-vacuous: narrowing the read to PR_LABELS only — the naive version — fails the comment-event case.

## Business Value

Unblocks the factory's own PRs without an admin override. Today the only way to land a mercy-approved workflow change is to bypass branch protection, which means the guardrail is either in the way or being stepped over — neither is a working state. This makes the documented escape hatch actually work, so sensitive-path PRs can be granted deliberately, visibly, and revocably by a human instead of merged around.

## Manual Effort Estimate

~3 hours — the grant plumbing, the read-before-token ordering, and tests that exercise the real gate. *(Proposed by Claude — Keval to confirm.)*

966 tests green.

## Summary

This PR is the standalone [AERIE-1957 — Simplify Search Site Documents tool from card to inline trace](https://linear.app/builder-team/issue/AERIE-1957/simplify-search-site-documents-tool-from-card-to-inline-trace) slice; there is no separate parent or child Linear issue for this ticket.

It replaces the oversized Search Site Documents Rhodes card with a compact, accessible inline trace. The trace shows the canonical site name, keeps match evidence collapsed until requested, and preserves source links and safe loading/error behavior.

This phase is tracked by [AERIE-1957 — Simplify Search Site Documents tool from card to inline trace](https://linear.app/builder-team/issue/AERIE-1957/simplify-search-site-documents-tool-from-card-to-inline-trace).

Production effect: cleanup or removal — the card shell is removed from this live tool rendering, while the underlying search behavior and evidence remain intact.

### Before / after

Before — oversized Search Site Documents card

<img width="698" height="291" alt="before-search-site-documents-card" src="https://github.com/user-attachments/assets/6d8a6c90-b4ce-4ec7-a5cb-edc5cae83f56" />

After — compact inline trace with collapsed evidence that can be expanded on click

<img width="733" height="696" alt="image" src="https://github.com/user-attachments/assets/277be309-7d1d-42ac-9a09-c9b718d11f7a" />

## Why

The previous card consumed disproportionate transcript space and made a simple read-only search look like a large dashboard surface. The new trace keeps the action and result count scannable while making document-level evidence available on demand. Resolving the canonical site name at the authorized search boundary also prevents the UI from presenting opaque site IDs as user-facing names.

## Business Value

- Makes search activity readable at a glance with the actual site name.

- Reduces transcript noise while retaining all match details and source links.

- Provides keyboard- and screen-reader-accessible evidence disclosure.

- Preserves safe source URL handling, redacted errors, and narrow-layout wrapping.

## How does it work

1. The authorized Convex search resolver obtains the canonical site name and returns it as an optional public-safe field through the site-document-search contract and Rhodes MCP path.

2. ToolCall routes searchSiteDocuments to RhodesSearchTrace, which renders the compact search action with the smaller magnifying-glass marker.

3. Positive results render Found 1 match or Found N matches as a collapsed accessible accordion; activation reveals all matching documents with titles, page numbers, and protocol-filtered Open source links.

4. Loading, empty, error, redaction, and wrapping behavior remain explicit; accordion state is reset when a reused tool-call row receives a new tool-call ID.

5. Other Rhodes tool renderers, migrations, upstream writebacks, and deployment surfaces remain deliberately unchanged.

## Scope

### Included in this phase

- Replace the Search Site Documents card shell with the compact inline trace.

- Include canonical authorized site names in search results.

- Add collapsed, accessible match evidence disclosure and per-match source links.

- Preserve loading, empty, error, safe-link, redaction, wrapping, and tool-row reuse behavior.

- Exact final diff paths:

chat/components/__tests__/tool-call.test.tsx
chat/components/rhodes-cards/rhodes-read-card.tsx
chat/components/tool-call.tsx
chat/convex/documentKnowledge/search.test.ts
chat/convex/documentKnowledge/search.ts
chat/rhodes-worker/mcp-server/tools/documents.test.ts
packages/contracts/src/site-document-search.test.ts
packages/contracts/src/site-document-search.ts

## Test plan

### Automated validation

- Tool-call and Rhodes trace tests — 103 passed (timeout 60s pnpm --dir chat exec vitest run components/__tests__/tool-call.test.tsx components/rhodes-cards/__tests__/rhodes-read-card.test.tsx)

- Convex document-search tests — 16 passed (timeout 60s pnpm --dir chat exec vitest run convex/documentKnowledge/search.test.ts)

- Site-document-search contract tests — 3 passed (timeout 60s pnpm --dir packages/contracts exec vitest run src/site-document-search.test.ts)

- Rhodes MCP document-tool tests — 6 passed (timeout 60s pnpm --dir chat/rhodes-worker exec tsx --test mcp-server/tools/documents.test.ts)

- Biome on all 8 changed files — passed (timeout 60s pnpm --dir chat exec biome check components/rhodes-cards/rhodes-read-card.tsx components/tool-call.tsx components/__tests__/tool-call.test.tsx convex/documentKnowledge/search.ts convex/documentKnowledge/search.test.ts rhodes-worker/mcp-server/tools/documents.test.ts ../packages/contracts/src/site-document-search.ts ../packages/contracts/src/site-document-search.test.ts)

- git diff --check — passed

- Exact-head diff scope — only the 8 paths listed above

## Summary

jotform-survey-sync has failed on nearly every hourly run for the last ~30 hours (CloudWatch Errors metric shows only 1 success out of ~30 invocations), with HTTP 429: {"message":"API-Limit exceeded"} on the very first API call (get_forms).

That message is Jotform's account-wide daily quota being exhausted, not a transient per-minute throttle. A single hourly run already iterates every form (~400+) doing 1-2 API calls each, which is enough to burn through the whole day's allotment by itself. Every following hourly run for the rest of the day then fails instantly, until the quota resets at midnight EST — at which point exactly one run succeeds and the cycle repeats. The existing 5x exponential-backoff retry logic can't help here (and just burns ~2 minutes of Lambda time per failing hour), since it's built for transient throttling, not an exhausted daily cap.

## Why it's needed

Survey data (jotform_forms, jotform_questions, jotform_submissions, jotform_answers) hasn't been refreshing since this started, and the pipeline's own alerting has been firing continuously.

## Changes

- sync.py: incremental per-form refresh. jotform_forms is still fully replaced every run (cheap — one API call for all forms). jotform_questions/jotform_submissions/jotform_answers are only re-fetched for forms with activity (updated_at or last_submission) in the last 48h (needs_refresh); forms with no recent activity keep their existing Redshift rows untouched. Forms with unparseable/missing timestamps fail open (always refreshed).

- redshift_client.py: new replace_forms/delete_by_form_ids methods — delete + reinsert only the refreshed forms' rows instead of truncating the whole table every run.

- jotform_client.py: detect Jotform's specific "API-Limit exceeded" message on a 429 and raise immediately (new JotformQuotaExceededError, a JotformClientError subclass) instead of retrying with backoff. Generic 429s (real transient rate-limiting) still retry as before.

- handler.py: fix logging.basicConfig(...) being a silent no-op in the Lambda Python runtime — the root logger already has a handler attached before user code runs, so basicConfig() without force=True never took effect. This is why past incident logs had zero per-run form/question/submission counts to debug from (only WARNING/ERROR reached CloudWatch).

- pipeline.json: schedule cron(26 * * * ? *) (hourly) → cron(26 0/6 * * ? *) (every 6 hours), for extra headroom on top of the incremental savings.

## Breaking changes

None. Redshift table schemas are unchanged; existing consumers of staging_education_jotform.* see the same shape of data, just refreshed incrementally instead of via full truncate-and-reload every hour.

## Test plan

- [x] 32 new/updated unit tests: incremental selection (needs_refresh), scoped delete+insert (replace_forms/delete_by_form_ids, including batching and quote-escaping), and the quota fail-fast path (JotformQuotaExceededError vs. generic 429 retry).

- [x] Full suite passes locally: pytest tests/ → 45 passed.

- [x] ruff format/ruff check clean (pinned 0.15.22, matches CI).

- [ ] Confirm the next scheduled run after merge succeeds and CloudWatch logs now show logger.info output (forms refreshed vs. skipped counts).

- [ ] Watch the daily-failure alert clear over the following 24h.

Caller half of [AI-Builder-Team/mercy#57](https://github.com/AI-Builder-Team/mercy/pull/57), which reworks the Linear queue so the agent works the ticket and updates Linear itself — no GitHub Issue in between.

⚠️ MERGE ORDER: mercy#57 first. It removes the standalone linear job and declares the new input.

## The one new input

linear_review_state: For Review

This is the claim. The queue query filters on workflow state, so a ticket only stops being eligible once it has moved there. Today → For Review → Done matches how this board actually works — there's no "In Progress" state on the Surtr team.

## Why the rework

The old design mirrored each ticket as a GitHub Issue and relied on a mention to re-enter the intake path. Linear is the system of record, so that gave two places to update while the real ticket went stale — and the mention was never posted, so seven tickets ended up claimed and parked rather than worked.

## State of play

HEIMDALL_LINEAR_ENABLED is currently false. I turned it off after un-claiming those tickets caused the still-live old bridge to re-create two shadow Issues on the next sweeps. It goes back to true once both PRs are merged.

All nine shadow Issues are closed and all nine ticket attachments removed, so the queue is clean.

## Business Value

Makes Linear actually the system of record for agent work — state current, PR linked, Done on merge — which is what the team's working rules require and what the productivity audit measures. It also removes four places the old path could break between "ticket picked" and "work started"; it broke at one of them silently.

## Manual Effort Estimate

~30 minutes for the caller. *(Proposed by Claude — Keval to confirm.)*

Requested by Keval, 2026-09-01.

## Before

Every PR opened with:

> Automated fix for renewals-v3 — fix_class code_fix, scope tier auto.

That tells a human nothing they can act on, and leads with vocabulary that only means something inside this harness.

## After

Renewal totals double-counted mid-quarter seats. Sums by contract now.
> Ready for review. Nothing ran the change, so it is unproven. A person still merges.
## For The Agent
_Everything below is detail for review. The summary above is the change._
Presented as ready — verification none, scope tier draft, fix_class code_fix, …
### What's broken
### What this PR changes
### Verification
<details>Run metadata</details>

The agent writes human_summary — one or two plain sentences, what changes and why it matters, written for someone scanning a PR list who has not read the ticket. Both diagnosis prompts say explicitly what to leave out (fix_class, tiers, paths, run IDs), because the field otherwise fills with the same jargon the old line had.

Optional in the schema, so older runs and any agent that skips it still validate — the fallback is the fix title, never the metadata line.

## The draft/ready note is plain too

*"Its own tests fail"* and *"nothing ran the change, so it is unproven"* are different facts a reader needs to act on. Scope tiers are not. The gate mechanics moved under For The Agent, where a reviewing agent can still see exactly why the PR presented as it did.

## Two builders, not one

The shell fallback that runs when the renderer dies still had the old metadata-first line. Rare is not unread — and it was the one place the old format survived. The test caught it.

## The tests render the body

They execute the renderer and assert on its output. The first version asserted on string literals inside out.append(...), which checks where a sentence happens to be assigned rather than what the reader sees — and it passed while the fallback was still wrong.

## Business Value

The PR body is the factory's main interface with people. Leading with internal vocabulary meant every PR needed decoding before a reviewer could tell whether it mattered, which is a tax on the one activity — human review — that the whole design depends on. This makes the first line the answer and everything else available underneath.

## Manual Effort Estimate

~2 hours — the schema field, both prompts, both builders, and tests that render rather than grep. *(Proposed by Claude — Keval to confirm.)*

1044 tests green.

## Summary

- Revert PR #1147 for rework

- Remove the Ops-Skills import, device distribution, installer, named telemetry, sandbox scaffolding, and feature-specific native operation introduced by that PR

- Preserve passive best-effort Skill telemetry, lifecycle edit locking with autosave-safe Publish and Archive transitions, and authorization-safe governance enrichment

## Why

PR #1147 is being reverted so its scope and implementation can be revisited separately. This returns main to the prior Skills product surface while retaining independent lifecycle, strict-type, authorization, and deterministic test fixes identified during review.

## Business Value

Keeps the current release focused and provides a clean baseline for reworking the feature without making observability a dependency of Skill activation or exposing governance metadata before Sindri authorizes the requested Skill.

## Test plan

- [x] Full workspace lint and typecheck

- [x] Architecture boundaries, Convex paths/read bounds, and test architecture

- [x] Skill lifecycle and governance browser tests: 4 passed

- [x] Sindri Skill lifecycle and authorization tests: 8 passed

- [x] Native Skill telemetry/gateway tests: 6 passed

- [x] Monitoring cron coverage tests: 2 passed

- [x] git diff --check

- [x] Hosted CI

- [x] Mercy review completed; its telemetry durability finding is intentionally not adopted because activation observability is best-effort and must remain passive

## Summary

- Provision the server-owned Global Documents Drive root through the Rhodes production deployment path

- Stabilize the Forge governance test by awaiting the projected-base reload

## Why

The production Rhodes Worker requires a managed Drive root to authorize Global Documents, but CD did not validate or inject that binding. An asynchronous governance assertion could also race the component follow-up load and fail nondeterministically.

## Business Value

Global Documents deploy with an explicit, fail-closed Drive boundary, while hosted validation no longer produces a timing-only release failure.

## Test plan

- [x] 237 Rhodes Worker tests passing

- [x] 20 deployment and dev-variable tests passing

- [x] 4 Forge governance browser tests passing

- [x] Chat and Rhodes Worker typechecks passing

- [x] Test-architecture and focused Biome checks passing

## Summary

- Reuse credential-free HTTPS validation for document projections

- Fall back to an encoded canonical Drive URL or omit unsafe Global search matches

## Why

Global document search trusted the stored Drive URL while the document API already validated URLs at projection time. Although supported Global registration writes canonical URLs, projections should remain safe if stored data is malformed or manually changed.

## Business Value

Global document search cannot return non-HTTPS or credential-bearing source links to API and MCP consumers.

## Test plan

- [x] 8 focused document URL tests

- [x] 33 public API v2 Documents tests

- [x] Chat typecheck

- [x] Test architecture and Biome checks

## Summary

- Add the dormant, pure TypeScript telemetry contracts and adapters for AERIE-1848 Slice 3.

- Preserve current-main's existing native Skill telemetry behavior and persisted row shapes.

- Keep this slice telemetry-only: no new producer traffic, database writer, endpoint, UI, schema, or generated artifact.

## Current-main adaptation

This PR is authored from current main after #1169. It does not restore the removed #1147 device, distribution, named/admin, outbox, or other governed foundations.

The additions are limited to pure helpers over the three existing legacy telemetry tables:

- skillTelemetryReceipts

- skillInvocationDedupe

- skillTelemetryRollups

Semantic identity continues to produce the legacy-compatible semanticKeyHash. A separate deterministic receipt fingerprint is non-persisted and is never substituted for semantic identity. Strict normalizers validate opaque IDs, hashes, dates, retention expiry, counters, and legacy row shapes; pure rollup helpers maintain the bounded two-week window without scanning history or inventing identity.

Device/session/install/distribution identity, named/admin/daily persistence, trusted-runtime cutover, producers, endpoints, UI, and other traffic/persistence work remain deferred to their sequenced slices.

## Scope

Exactly seven new files under chat/convex/skillTelemetry/:

- adapters.ts

- contracts.test.ts

- fixtures.ts

- privacy.ts

- requestFingerprint.ts

- rollup.ts

- semantic.ts

No legacy model, schema, calendar, native producer/caller, root schema, generated file, package metadata, endpoint, or UI path is changed.

## Validation

- Focused native and contract suites: 25/25 tests passed

- pnpm --dir chat typecheck

- Biome on changed paths

- pnpm lint:convex-paths

- pnpm lint:read-bounds

- pnpm lint:test-architecture

- pnpm lint:boundaries

- git diff --check

- Independent read-only QC passed exact range 1895a7102f64c584c81b9ebcee8029005219cfda..dc303314887d0ef26a69a307650b11d1bf020170

Fixes AERIE-1848

The dashboard has no record of any Linear queue work, and this is why.

## The bug

HEIMDALL_MODES listed triage, issue, revise. The enum is closed, and the ingest route returns 400 on a parse failure — so every linear run has been rejected outright since the queue was enabled.

release and steward are added for the same reason: they exist as modes today, and if either starts reporting it should land rather than 400.

## Still closed on purpose

A typo or an in-progress placeholder should fail at ingest rather than quietly distort the dashboard. So the fix enumerates the real modes rather than opening the enum.

## Prerequisite

The heimdall dashboard rework needs to show where work came from — Linear, a pipeline failure, or a human ask — and mode is that signal. It can't group by a value the store never accepted.

## Verified

Reverting the enum fails the linear case; 64 tests across the heimdall and telemetry suites pass with it.

## Business Value

Every ticket the factory has worked from Linear is missing from the dashboard, so the one view meant to show what the factory does has been blind to its newest source. It also means any cost or outcome figure read off that page today understates the real total.

## Manual Effort Estimate

~30 minutes — the enum, plus a test that ties it to the modes the workflow can route. *(Proposed by Claude — Keval to confirm.)*