@adrata/adrata-mcp 1.0.2 → 1.0.6

package/skills/qa-the-card/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: qa-the-card
+description: Deeply verify a Starfield card in Staging QA1 or Staging QA2, fix defects and rerun evidence until clean, then leave an auditable AI-to-human handoff without claiming deployment. Use when asked to QA, review, verify, sign off, or clear cards from a QA column.
+---
+
+# QA the card
+
+QA is an engineering pass, not a documentation pass. Reproduce every acceptance
+claim, attack the implementation beyond the happy path, fix defects in scope,
+and repeat until the card is genuinely ready for the next accountable reviewer.
+
+The workflow semantics are fixed by
+`company/decisions/2026-08-29-two-gate-ai-qa-human-production.md`; the required
+evidence loop is fixed by
+`company/decisions/2026-08-29-recorded-staging-qa-standard.md`. This skill is
+their operating procedure.
+
+## Establish the real queue
+
+1. Read every active board or the all-boards roll-up before announcing a count.
+   A card's `product` may differ from the board holding it, so inspect both the
+   Adrata board and Adrata-labelled cards on another board. Re-read the queue
+   during a long session and at every deployment checkpoint because new cards
+   can arrive while QA is running. Report the delta, not only the new total.
+2. Limit mutations to the QA scope the user named. Read each card, its full
+   stage history, comments, acceptance criteria, flag, linked pull request, and
+   exact-SHA delivery evidence before testing it.
+3. Do not infer missing history from a sparse screen. Confirm the transition
+   rows through the governed API. A card created directly in an old QA column
+   may honestly have only one transition.
+4. Audit the criteria themselves. Each must describe an observable outcome and
+   be executable at the current gate. Add or correct missing coverage before
+   calling the card clean; never turn a vague criterion green by interpreting it
+   generously.
+
+## Preserve independent gates
+
+- QA1 and QA2 are separate passes over separate column-history dwells. A prior
+  checkbox or receipt is evidence to inspect, not a substitute for rerunning it.
+- An agent's QA2 credential must differ from the criterion author and the agent
+  credential whose clean receipt opened QA1. Never impersonate a human to bypass
+  this rule. A human may perform the final acceptance even when they own or
+  authored the card.
+- For non-trivial QA2 work, use at least one independent adversarial reviewer
+  when subagents are authorized and available. Parallelize separable surfaces
+  such as UI, backend/security, and migration/deployment behavior. Give each
+  reviewer a bounded target and avoid concurrent edits to the same files.
+- Multiple reviewers may find and challenge defects, but they do not assemble a
+  synthetic gate from partial identities. One eligible second-agent credential
+  must rerun or confirm every current criterion so the final QA2 receipt is
+  coherent and the badge can be derived honestly.
+- Stagger expensive Rust builds on the shared Mac. More concurrent compilers can
+  make verification slower and can exhaust disk; an independent final result
+  must use the reviewer's own target artifacts and show any new test by name.
+
+## Run the fix-and-retest loop
+
+For every criterion:
+
+1. Write down the observable, the environment, and the strongest practical way
+   to falsify it. Source inspection alone is not a pass.
+2. Reproduce the behavior before changing code when the deployed failure is
+   observable. Preserve the failing request, console output, screenshot, video,
+   trace, or exact database/API result.
+3. Exercise the happy path, boundary conditions, failure states, authorization
+   boundaries, retries/idempotency, and a realistic regression path. For a
+   migration, prove both representative old state and transactional rerun. For
+   a deployment, prove the exact deployed SHA and behavior during replacement,
+   not only the final steady state.
+4. If anything fails, fix it within the same card when passing the card's
+   existing acceptance outcome necessarily requires that fix. Add the narrowest
+   regression test that would have caught it, rerun the focused suite, then rerun
+   the broader affected contracts. Do not merely describe a defect and stop
+   while a safe in-scope fix remains.
+5. Repeat adversarial review after the fix. A first green rerun is evidence, not
+   automatic sign-off.
+
+Keep the card in its QA column throughout this loop unless the user or board
+policy explicitly asks for a bounce. Never hide an incomplete pass by moving it
+forward.
+
+## Visual QA requires visual evidence
+
+Use Playwright for every user-facing change. A DOM assertion or source review
+does not establish that the screen is visually correct.
+
+- Record a WebM video of the real interaction and take screenshots of the states
+  that decide the criterion. Enable action annotations or chapter markers when
+  they make the recording easier for the human reviewer to follow.
+- Measure duration, MIME type, size, and hash from the finalized media file
+  before upload. Never declare the interaction stopwatch as the video duration:
+  recorder startup/finalization can make those values differ. Reject the
+  receipt when a checkpoint falls outside the measured media duration or the
+  declared metadata does not match the finalized file.
+- In QA2, inspect the QA1 recording as prior evidence, then record a new QA2
+  replay. Keep both attached to their exact gate and column-history dwell. Never
+  reuse, replace, or relabel the QA1 media as QA2 evidence.
+- Give each concurrent QA agent an isolated synthetic account or an explicit
+  exclusive lease on the shared account. For stateful journeys, create and read
+  back a unique server resource (for example, a conversation id) and address it
+  directly; never rely on the newest active resource. An unexpected request,
+  turn, or mutation from outside the recorded browser makes the run ambiguous
+  and therefore a failure, not evidence.
+- Inspect the rendered screenshots yourself at the target viewport. Check
+  alignment, clipping, wrapping, whitespace, stacking, focus, disabled/loading
+  behavior, and whether badges and controls line up with neighboring content.
+- Capture the browser console, page errors, failed requests, and the relevant
+  network responses. Distinguish an expected simulated failure from an
+  unexpected product error.
+- Cover normal, empty, loading, error, and recovery states when they exist. Test
+  both hosted Starfield and the packaged desktop app when both ship the changed
+  renderer.
+- When governed QA evidence is available, attach the screenshot/video to the
+  card's exact open QA dwell with the environment and build SHA. Until that
+  surface is deployed, retain the files and record their paths or durable run
+  links without pretending they were attached.
+- Reopen both uploaded gate recordings before handoff. Prove each fresh
+  short-lived URL loads and that each video can play, seek, and enter
+  fullscreen; an upload response alone is not a media pass.
+
+## Manage cards as outcomes, not bug counters
+
+- A defect required to satisfy the current card stays on that card. Fix it and
+  retest there; do not create a new Up Next card merely because QA found it.
+- Create a separate card only for an independently releasable outcome outside
+  the current acceptance scope. Search the whole board first. If a likely
+  duplicate already exists, identify the pair and let a human collapse it; do
+  not delete or merge cards on your own judgement.
+- A new card needs a concrete title, reproduction/context, first-class
+  acceptance criteria, and no invented assignee. Move it through the ordinary
+  workflow instead of placing it directly in a protected QA or done column.
+- Keep findings, fixes, and evidence on the canonical card. Do not rewrite the
+  original body to make the request match what was discovered.
+
+## Promotion and the human handoff
+
+Local verification comes before CI. Keep incomplete pull requests draft, seek
+an independent code review for consequential fixes, make the PR ready only
+after local evidence is clean, and merge only after the applicable protected
+checks pass. Verify the cumulative staging deployment rather than treating a
+merge as deployment proof.
+
+When QA2 is clean:
+
+1. Tick only criteria actually executed in the current dwell, with concise
+   evidence naming commands or run links, exact counts, environment, build SHA,
+   and any material caveat.
+2. Add one concise final card comment summarizing the fixes and the last clean
+   rerun. Comments preserve the audit trail; they never replace the fix.
+3. Confirm the derived `Ready for review` badge appears and aligns correctly in
+   both the card and detail view. Never edit an emoji into the title; a derived
+   badge disappears correctly after a bounce.
+4. Leave the card in Staging QA2. An agent must not move it to Ready to Ship or
+   Production. Ready to Ship is the human's acceptance of both AI receipts.
+5. Treat Production as a separate claim: the approved release is live, its exact
+   delivery evidence is known, and release notes may now include it. A board
+   column alone is not exact-SHA proof.
+
+If the badge does not appear, identity is ambiguous, evidence belongs to an old
+dwell, a criterion is open, CI is incomplete, or the deployed behavior differs,
+the card is not ready. Fix the cause and rerun; never use an override to make the
+handoff look complete.
+
+## Report while working
+
+Keep the human informed with concrete state: current QA2 count, cards clean,
+cards in fix/retest, newly found defects, and deployment/desktop readiness. Do
+not announce that the app is ready to inspect until the required API migration,
+hosted build, packaged desktop version, relaunch, and final Playwright video pass
+are actually complete.
+
+At handoff report:
+
+- card and current column;
+- criteria executed and the final evidence;
+- defects found, fixes made, and independent review result;
+- exact staging/production/desktop build state;
+- whether the `Ready for review` badge is visible;
+- any genuinely separate follow-up card.

package/skills/ship-the-card/SKILL.md

@@ -9,6 +9,10 @@ This is the loop a coding agent actually runs: read a card, do the work, move
 the card. The part people get wrong is the last step — work that lands with the
 board untouched is work nobody can see.
 
+If the card is already in Staging QA1 or Staging QA2, use `qa-the-card` instead.
+QA is a fresh independent verification and fix-and-retest loop, not the ordinary
+implementation-and-submit path below.
+
 ## Pick up
 
 1. `list_my_work_items` — **start here.** It answers "what is mine", across every
@@ -110,6 +114,28 @@ Two things to carry back to the card:
   session), so the next person at aligning can ask you what you meant; what it
   must not arrive with is a list of outcomes nobody can check.
 
+## Tick what you ran
+
+Before you move the card on, tick the criteria you actually executed, with
+`satisfy_work_item_acceptance_criterion` and the evidence in `note` — a build
+number, a run link, the caveat that makes it honest. An untouched checkbox says
+nothing about whether the check passed; it says nobody has been near it, which
+is the same thing an abandoned card says.
+
+Ticking from a build column records `claimed`, not `verified`. At a QA gate, an
+authenticated human may verify even when they own the card or authored the
+criterion: the human is the accountable exception when one person operates the
+workspace. An agent verifies only when its credential differs from the
+criterion author, and QA2 requires a different agent credential from the one
+whose clean receipt opened QA1. One AI cannot certify both gates. Tick anyway
+when the result is `claimed` — it is a real state that says the work is believed
+done and tells QA what to rerun. Never tick a box you did not execute merely to
+improve the count.
+
+If a tick turns out to be wrong, `unsatisfy_work_item_acceptance_criterion`
+takes it off. It clears the note with it, so if the evidence is worth keeping,
+put it on the card with `comment_on_work_item` first.
+
 ## Submit it
 
 When the change is ready for review, `move_work_item` it onward — no `claim`
@@ -129,11 +155,11 @@ The tool refuses placeholder reasons — "moved", "update", "Moved to another
 column" — on purpose: a history full of those looks like an audit trail, so
 nobody goes looking for the real answer, which is worse than no history at all.
 
-**Do not move a card into the terminal column** — `Production` on a default
-board, or whatever the last column is called on this one. That is a human's call:
-the person who reported it, or the reviewer. An agent marking its own work
-complete is the one move on this board that nobody can trust. Stop at the review
-or QA column and say it is ready.
+**Do not move a card into `Ready to Ship` or `Production`.** Ready to Ship is the
+human's final acceptance of both AI QA receipts. Production is a separate,
+stronger claim that the release is actually live and eligible for release
+notes. In QA1, an independent agent may advance a clean card to QA2; in QA2,
+document the second pass and leave the `🏁 Ready for review` card for the human reviewer.
 
 ## Writes
 

package/tool-annotations.js

@@ -239,9 +239,22 @@ const IDEMPOTENT_WRITES = new Set([
   // Every Starfield board write is governed by a required idempotency key.
   // Retrying the same key replays; it never appends a second transition,
   // comment, criterion, or card.
-  'move_work_item', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
+  'move_work_item', 'transfer_work_item_between_boards', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
   'create_work_item', 'comment_on_work_item', 'flag_work_item',
   'add_work_item_acceptance_criterion',
+  // Ticking and un-ticking are both genuinely idempotent, and for different
+  // reasons worth keeping straight: a repeat tick is a no-op because the server
+  // only writes the ticker, column and note where they were empty, and a repeat
+  // un-tick clears columns that are already NULL. Neither can compound.
+  'satisfy_work_item_acceptance_criterion', 'record_work_item_criterion_engineering_proof',
+  'unsatisfy_work_item_acceptance_criterion',
+  'claim_work_item_qa_pass',
+  'claim_next_work_item_qa_pass',
+  'heartbeat_work_item_qa_pass',
+  'attach_work_item_qa_evidence',
+  'verify_work_item_qa_evidence_playback',
+  'record_work_item_qa_failure_and_release',
+  'requeue_work_item_qa_after_fix',
 ]);
 
 // Non-read tools that create new state / have side effects each call.
@@ -255,6 +268,7 @@ const NON_IDEMPOTENT_WRITES = new Set([
   'warmup_email', 'schedule_demo', 'schedule_meeting', 'connect_workspace',
   'enable_toolset', 'track_conversion', 'log_interaction', 'test_webhook',
   'replay_webhook_delivery', 'upgrade_account',
+  'release_work_item_qa_pass',
 ]);
 
 // Tools that reach beyond the workspace (external enrichment, web, providers).

package/tools/source-control/connection-tools.js

@@ -0,0 +1,31 @@
+/** Read-only, product-visible health for Starfield's source-control ingestion. */
+export function registerSourceControlTools(server, { z, api, ok }) {
+  server.tool(
+    'list_source_control_connections',
+    'List source-control connections with repository binding count, last durably acknowledged delivery, rejection state, actionable health, and the exact webhook events that are safe to enable.',
+    {},
+    async () => {
+      const response = await api('GET', '/api/v1/scm/connections');
+      return ok({ connections: response?.data ?? response ?? [] });
+    }
+  );
+
+  server.tool(
+    'get_source_control_connection_events',
+    'Read the recent persisted delivery and attention ledger for one source-control connection. This is the evidence for whether GitHub reached Starfield; service logs are not a substitute.',
+    {
+      connectionId: z.string().describe('Source-control connection id.'),
+      limit: z.number().int().min(1).max(200).optional().describe('Newest events to return; defaults to 50, maximum 200.'),
+    },
+    async ({ connectionId, limit }) => {
+      const suffix = limit === undefined ? '' : `?limit=${limit}`;
+      const response = await api('GET', `/api/v1/scm/connections/${encodeURIComponent(connectionId)}/events${suffix}`);
+      return ok({ events: response?.data ?? response ?? [] });
+    }
+  );
+}
+
+export const SOURCE_CONTROL_TOOL_NAMES = [
+  'list_source_control_connections',
+  'get_source_control_connection_events',
+];