Skip to content
GRPNR.

Atlas User Stories

Companion to 01-initial-recommendation.md (pre-research position) and the R1-R8 evidence files in evidence/. This document does not re-argue build-vs-buy; it takes the loop-not-a-layer frame as the thing under test and asks, story by story, whether each piece of the concept has a real user, a real trigger, and a real failure mode. Where the substrate cannot yet support a claimed behavior, that is called out as a blocking dependency, not smoothed over.

No em-dashes. Numbers carry a passport: MEASURED (real fleet data - none exists yet for this product), MODELED (estimated from an analog or a formula), DARK (genuinely unknown, flagged as such), DESIGN (a target the team is choosing, not a measurement).

0. How to read this

  • Format for significant stories: Job / Preconditions / Trigger / Main flow / Alternative flows / Edge cases / Failure states / Acceptance criteria / Dependencies / Permissions / Data / Security / Instrumentation / Priority / Metric / Classification.
  • Lightweight stories are one line: persona, story, classification, priority.
  • Classification: MVP (build now), POST-MVP (real, deferred), EXPERIMENTAL (worth a spike, not a commitment), REJECTED (must not be built in v1, with a reason).
  • Priority: P0 (nothing works without it) through P3 (backlog).
  • IDs: CP (critical path), ACT (activation), RET (retention/trust-over-time), ADM (administrative), TS (trust-and-safety, full detail per the brief), SEC (security reviewer), FUT (future team reader), REJ (must-not-build).

1. Personas

Persona Who Job to be done
Asker agent Any fleet agent (Claude Code, 64-concurrent ceiling) mid-task Get unblocked without derailing into guesswork
Reader agent Any fleet agent, at the start of any task touching unfamiliar ground Find the answer before spending a human’s attention
Write-back agent A cheap agent invoked after an answer lands Turn one answer into a permanent, findable artifact
Robert Operator/router, only human admin Keep the queue sane, keep Tomas’s interrupt budget spent well
Tomas Architect, the scarce answerer (“more agents won’t help me”) Answer each real question exactly once, in a tool he already uses
Future team reader Does not exist yet (program context: no third stakeholder today) Passive consumer of decisions/progress once a team exists
Security reviewer Whoever audits the internal/core plane boundary before go-live Confirm the loop cannot leak, forge, or corrupt across the boundary

2. The loop, end to end

flowchart TD
    A[Agent hits ambiguity] --> B{Search corpus first - CP1}
    B -- hit, self-serves --> Z[No interrupt. Product worked invisibly.]
    B -- miss --> C[File structured question - CP2]
    C --> D{Dedup against open queue - CP3}
    D -- duplicate --> E[Attach to existing open question]
    D -- novel --> F[New task in agent-questions queue]
    E --> G[Tomas answers once, existing tasks UI - CP4]
    F --> G
    G --> H[Fan-out completes every attached task - CP5]
    H --> I[Every attached agent resumes]
    G --> J[Write-back agent drafts artifact - CP6]
    J --> K[Human-gated review of the diff]
    K --> L[Doc / GLOSSARY.md / decision-log entry lands]
    L --> B
    L --> M[Generated digest line to GChat]

Everything left of L is the system. Everything right of L (docs, glossary, digest) is a rendering of it, per the initial recommendation’s core claim. This document tests that claim story by story rather than asserting it.

3. Foundational open dependency (blocks CP-2, read this before the critical path)

FACT (R1): the only task-creation endpoint that exists is POST /tasks/internal/create, expose: false, auth: false - reachable only by other backend services in-cluster (e.g. a Temporal workflow activity), not by an external caller such as an MCP client.

FACT (R3, arXiv/GitHub-sourced): Claude Code subagents cannot call AskUserQuestion at all (“unavailable to subagents”), and a background subagent auto-denies any tool call that would otherwise prompt for permission. Even the top-level session’s AskUserQuestion has no firing hook as of the open, unresolved GitHub issue #59908 (opened 2026-05-17). There is no out-of-the-box path from “a Claude Code agent has a question” to “a human sees it.”

Consequence (INTERPRETATION): for an asker agent to reach the tasks service at all, one of two things must be true, and R1 did not examine workflow-management’s own exposed API surface closely enough to say which:

  • (A) every fleet agent run is itself modeled as (or drives) a Temporal workflow execution inside workflow-management, and “asking a question” is an activity inside that workflow calling createFromWorkflow in-cluster, exactly the way APPROVAL/SIGNATURE tasks already work today. Zero-PR holds.
  • (B) a new exposed, authenticated task-creation endpoint has to be added to the core-plane tasks service for out-of-workflow callers. This is a PR to Tomas’s code and directly contradicts the decided zero-PR v1 constraint (R2a-1).

This is the single highest-priority technical question for the synthesis to resolve, ahead of the single ask already sent under plan 001. Every downstream story in this document (CP-2 onward) assumes (A) and flags it ASSUMPTION, unverified.

4. Critical-path stories

CP-1: Reader agent self-serves before asking

  • Job: find out whether this question is already answered, so the loop never has to run at all.
  • Preconditions: the write-back artifact from a prior answer (doc section, GLOSSARY.md entry, or decision-log row) already exists and is reachable from git or the docs-search MCP tool.
  • Trigger: agent hits ambiguity about a term, a legacy system’s status, a naming convention, or a prior decision.
  • Main flow: agent calls the existing docs.search MCP tool (or greps the bundled _documentation) -> gets a hit with provenance (which question, who answered, when, scope, expiry) -> proceeds without interrupting anyone.
  • Alternative flows: partial match (term exists, answer doesn’t cover this scope) -> falls through to CP-2 with the partial match cited as “already searched, found X, not sufficient because Y” (this is the initial recommendation’s mandatory question-form field, and it doubles as a documentation-gap signal, the closest local analog to kapa.ai’s coverage analytics, R6).
  • Edge cases: corpus search returns a stale or expired answer (see TS-2); search returns a confident-looking but wrong match because dedup logic and doc search share no code path yet (v1 gap, note under Dependencies).
  • Failure states: search tool itself is down (docs service outage) -> agent should fail toward asking, not toward silent guessing; this must be an explicit fallback, not an accident.
  • Acceptance criteria:
    • every written-back artifact is reachable by the same search path an agent already uses (no second index to remember).
    • every hit surfaces provenance and expiry, not just text.
    • a partial-match miss still requires the “what I already found” field before a question can be filed.
  • Dependencies: CP-6 (write-back) must have already run at least once for this to have anything to find; existing docsContentService.search() (R1 section 5) is the only reusable search primitive today, in-memory substring scan over 23 bundled files, no code index, no embeddings.
  • Permissions: read-only, no new ACL needed.
  • Data: the written artifact plus its provenance fields.
  • Security: none beyond “don’t index anything from reasons-and-decisions/ into the searchable corpus” (see TS-3/SEC-3).
  • Instrumentation: log(query, hit/miss/partial, artifact id if hit) to compute self-serve rate, the number that falsifies the whole expansion if it never rises.
  • Priority: P0.
  • Metric: self-serve hit rate over time; plan 001’s explicit failure signal is “questions/unit flat after 4 weeks” (MODELED target, no MEASURED baseline exists).
  • Classification: MVP.

CP-2: Asker agent files a structured question

  • Job: get unblocked with the smallest possible ask, in a form that a dedup engine and a write-back agent can both use later.
  • Preconditions: CP-1 came back miss or insufficient-partial-match. The Section 3 dependency is resolved in favor of (A).
  • Trigger: agent (or its wrapping workflow) decides it cannot proceed without a human decision.
  • Main flow: agent’s workflow activity calls createFromWorkflow with type: INFORMATION_REQUEST, assigneeGroupSlug: "agent-questions", a title, a description forced through four fields (what I’m blocked on, what I already searched/found, the smallest answer that unblocks me, blast radius), and the workflow stamp for later signal-resume.
  • Alternative flows: agent’s own workflow was itself spawned from a parent question already open (a sub-question) -> question should carry a parent reference so dedup/write-back can see the thread, not just a flat list (no such field exists in Task today, R1; treat as a v2 ask if it turns out to matter, not a v1 blocker).
  • Edge cases: two independent agents ask the identical question in the same second, both before either has been through dedup (race, see CP-3 edge cases); an agent asks a question whose “blast radius” field is empty or vague because nothing forces the format (formSchema/AJV payload validation is explicitly not built yet, R1) - v1 has no platform-level guarantee the four fields are actually filled, only convention.
  • Failure states: createFromWorkflow call fails (network, service down) -> agent must have a defined fallback (retry with backoff, then degrade to “flag and continue with a documented assumption” rather than hang forever; this fallback is itself a product decision this document surfaces but does not resolve).
  • Acceptance criteria:
    • every question created has non-empty title, description, and the four forced fields, or is visibly flagged as malformed for triage.
    • every question carries its originating workflow stamp so CP-5 can resume it later.
    • filing a question never silently blocks the agent forever; a timeout or fallback path is defined.
  • Dependencies: Section 3 open dependency (unresolved); TaskWorkflowStamp existing infrastructure (R1); the agent-questions group must already exist with Tomas (and/or Robert) as members (ADM-1, currently ASSUMED absent).
  • Permissions: the calling identity is whatever service identity workflow-management uses today for other TaskType creations; no new grant if (A) holds, a new grant if (B) is the actual mechanism.
  • Data: question text, forced fields, workflow stamp, entity links (entityType/entityId) if the ambiguity is about a specific legacy unit.
  • Security: question text can contain pasted code, config, or legacy snippets; see TS-3 before this ships.
  • Instrumentation: log question id, agent id, workflow id, timestamp, and text length only (not full text) to a metrics store; full text stays inside the ACL’d task record, not an open dashboard.
  • Priority: P0.
  • Metric: questions filed per day/unit (MODELED baseline: “hundreds/day vs ~101 contributors,” dossier estimate, no MEASURED data exists).
  • Classification: MVP, blocked on Section 3.

CP-3: Dedup engine attaches a duplicate to an open question

  • Job: stop N agents from creating N tasks for one ambiguity, so Tomas’s queue reflects distinct decisions, not raw interrupt volume.
  • Preconditions: at least one agent-questions task is already PENDING.
  • Trigger: CP-2 fires a new question.
  • Main flow: Atlas’s own service polls GET /tasks?assigneeGroupSlug=agent-questions&status=pending (the exact query the tasks service’s own doc comment demonstrates as “a review queue,” R1) - the only mechanism available, since no task-events fan-out topic exists yet (R1: “add when a consumer exists” - Atlas is that consumer and it is absent) - normalizes and exact/keyword-matches the new question against that open set, per plan 001’s pre-mortem-tested ordering: naive exact-match first, embeddings only if measured miss-rate demands it, never the reverse. On a match, attach the new question’s stamp to the canonical task’s merge record (a new record Atlas owns, not a Task schema change) rather than creating a second task.
  • Alternative flows: near-duplicate, not exact (paraphrase) -> v1 does NOT auto-merge on similarity alone; it surfaces the candidate match to the human answering the canonical task as “N possibly-related open questions,” and the human confirms or rejects the merge. This is a deliberate divergence from the initial recommendation’s “auto-resolve on high-confidence match” tier, argued in TS-1 below.
  • Edge cases: two questions filed within the same poll interval both look novel and both create tasks, then turn out to be duplicates of each other (race condition inherent to polling instead of event-driven dedup, itself a consequence of the missing fan-out topic); a question that is a duplicate of a CLOSED (already-answered) task rather than an open one - this should attempt an answer-reuse path (closer to CP-1’s job) before creating any new task at all.
  • Failure states: poll job itself stalls or crashes -> queue silently stops deduping and every question becomes its own task, degrading gracefully to “no dedup” (safe) rather than “wrong dedup” (unsafe); must be monitored (ADM-6).
  • Acceptance criteria:
    • v1 dedup is exact/keyword match only; no embedding model ships in v1.
    • no merge happens without a human confirming it, ever, in v1 (see TS-1).
    • every questions considered, every match score, and every decision (attach/new/reject) is logged with enough detail to audit later.
    • a stalled dedup job fails toward “too many tasks,” never toward “wrongly merged tasks.”
  • Dependencies: Atlas needs its own lightweight index of open questions; nothing existing provides this (docsContentService.search() covers only the 23 bundled docs, not live tasks, R1 section 5).
  • Permissions: read access to the agent-questions queue (VIEWER role or equivalent, R1); write access only to Atlas’s own merge-record store, not to Task rows directly.
  • Data: normalized question text, candidate set, match scores, merge decisions, all attributable to a specific human confirmation once merges require one.
  • Security: a bad merge is a trust failure, not a data leak; see TS-1.
  • Instrumentation: dedup precision (of confirmed merges, how many were right) and recall (of true duplicates, how many were caught) - both currently DARK, no fleet-scale data exists anywhere in the evidence base (R2b, checked twice, same conclusion).
  • Priority: P0.
  • Metric: duplicate rate (questions filed vs distinct decisions needed).
  • Classification: MVP, with auto-resolve explicitly descoped to EXPERIMENTAL (see TS-1).

CP-4: Tomas answers once, in the tool he already uses

  • Job: make one decision, in a familiar UI, and have it count for every attached agent.
  • Preconditions: CP-3 has routed the (possibly merged) question into a single canonical PENDING task assigned to agent-questions.
  • Trigger: Tomas opens his existing tasks inbox (assigneeGroupSlug=agent-questions&status=pending).
  • Main flow: Tomas reads the question plus any attached duplicate count, fills the answer form (decision, rationale, scope, expiry/confidence - the initial recommendation’s mandated fields), and calls POST /tasks/:id/complete.
  • Alternative flows: Tomas delegates to Robert for anything that is process/routing rather than architecture (Robert is ADMIN-scoped and can complete any task per the existing ACL, R1); Tomas rejects the question as out of scope or as a duplicate of a CLOSED task Atlas missed, feeding a correction back into CP-3’s index.
  • Edge cases: Tomas fills only the decision, leaves scope/expiry blank - since AJV payload validation is not built (R1), nothing stops this; the write-back agent (CP-6) must handle missing fields by defaulting to the most conservative reading (narrow scope, short expiry) and flagging the gap, never by guessing broad/permanent.
  • Failure states: the _workflowSignalSend call inside completion fails (workflow already gone, run expired) - by design this fails the whole completion call (R1: “a completed task whose workflow never learns of it is the worst state”) - Tomas’s UI must surface this clearly rather than showing a silent success.
  • Acceptance criteria:
    • Tomas never sees a new UI; this is the existing tasks-complete screen.
    • the answer form’s four fields are present as a template even without platform-level enforcement.
    • a failed signal-send on completion is visible to Tomas, not silent.
  • Dependencies: none beyond what is already built; this is the one story in the whole document that needs zero new backend work if CP-2/CP-3 land.
  • Permissions: existing ACL (assignee, group member, or ADMIN, R1).
  • Data: decision, rationale, scope, expiry/confidence, timestamp, answerer.
  • Security: none beyond standard task ACL; no new surface introduced.
  • Instrumentation: time-to-answer, fields-filled-vs-blank ratio.
  • Priority: P0.
  • Metric: human interrupts per day, before/after (MODELED baseline only).
  • Classification: MVP.

CP-5: Answer fans out and resumes every attached agent

  • Job: deliver “one answer unblocks every agent who asked” as an actual mechanism, not a slogan.
  • Preconditions: CP-3 attached one or more duplicate questions to the canonical task via Atlas’s own merge record (not a Task schema field - TaskWorkflowStamp is a single stamp per task, R1, so the fan-out cannot be “one task, many stamps” without a PR).
  • Trigger: CP-4’s completion of the canonical task.
  • Main flow: Atlas’s own service, using a service identity that is a member of agent-questions (ADM-2), calls POST /tasks/:id/complete for the canonical task AND, separately, for every duplicate task attached to it, each time reusing Tomas’s answer as the formPayload and stamping it with a provenance note (“answered as a duplicate of task X”). Each call independently triggers its own _workflowSignalSend to that task’s own stamped workflow. This uses only the existing exposed, authenticated completion endpoint - zero PR, at the cost of N sequential API calls instead of one fan-out primitive.
  • Alternative flows: none; this is the only mechanism available under the zero-PR constraint (ASSUMPTION, not verified against a live implementation).
  • Edge cases: a duplicate’s workflow has already terminated or timed out by the time its completion call runs (the asker agent gave up or errored out independently) -> that one completion call throws by design (R1) -> must be caught and logged per-task, not allowed to block completion of the other N-1 duplicates.
  • Failure states: partial fan-out failure (5 of 6 duplicates resumed, 1 failed) -> must be visible and retryable, not silently dropped; a duplicate that never resumes is functionally the same as never having deduped it, which defeats the entire point of CP-3.
  • Acceptance criteria:
    • every attached duplicate gets its own completion call with the canonical answer and a provenance stamp.
    • a single failed fan-out call never blocks the others.
    • fan-out completeness (N attached, N resumed) is logged and monitorable.
  • Dependencies: ADM-2 (Atlas needs an authenticated identity with agent-questions group membership to call complete on tasks it did not originate); no cross-plane signal bridge exists (R2a-3), so this fan-out logic must run wherever it can call the core-plane exposed API directly, which constrains where Atlas’s dedup/fan-out service can live.
  • Permissions: group-member-equivalent write access to complete tasks it is not the original assignee-of-record for; this is a real new grant, not a no-op, and should be named explicitly to Tomas rather than assumed.
  • Data: canonical answer, list of attached duplicate task ids, per-task fan-out result.
  • Security: a service identity that can complete arbitrary tasks in this queue is a real privilege; scope it to agent-questions only, never ADMIN.
  • Instrumentation: fan-out count, success count, failure count and reasons.
  • Priority: P0.
  • Metric: resumed-vs-attached ratio; this is the number that proves or disproves the concept’s headline claim.
  • Classification: MVP, with the mechanism itself flagged ASSUMPTION until verified against a real implementation spike.

CP-6: Write-back agent converts the answer into a durable artifact

  • Job: make sure an ANSWERED question is not “closed,” only “done,” once its answer exists as a diff someone (or some agent) can find later.
  • Preconditions: CP-4/CP-5 completed; the answer has a decision, scope, and (ideally) expiry.
  • Trigger: canonical task completion event (observed by polling, per the same missing-event-topic constraint as CP-3).
  • Main flow: a cheap agent classifies the answer’s target (doc section, GLOSSARY.md entry, or the factory-lane decision log under docs/atlas/decisions/ (12-prd N10; reasons-and-decisions/ is confidential and never a write target), whichever already fits, per R1’s real, working precedent - never a second, competing knowledge system, per R2d’s flagged overlap risk with the MADR-style ADR mechanism proposed in research/12 §4, not yet implemented - the running precedent is Tomas’s flat, append-only decision log per root CLAUDE.md), drafts the diff with a provenance footer (question id, answerer, date, scope, expiry), and opens it for human-gated review rather than auto-committing.
  • Alternative flows: the answer doesn’t cleanly map to any existing doc section (novel topic) -> agent proposes a new section rather than forcing a bad fit; the answer scope is “Orders only,” narrower than the doc it would otherwise land in -> the diff must carry that scope, not silently generalize it.
  • Edge cases: the answer’s scope/expiry fields were left blank (CP-4 edge case) -> write-back defaults to the most conservative artifact (scoped narrowly, short review-again date) and flags the gap in the diff itself rather than guessing; the same decision is written back twice because two independent completions raced (CP-5’s per-task fan-out could, in a bug, double-fire) -> write-back must be idempotent per question id.
  • Failure states: the drafting agent hallucinates a plausible-sounding but wrong summary of the actual decision -> this is exactly the failure mode human-gated review exists to catch; if review is skipped “to save time,” the corpus poisons itself at machine speed, the initial recommendation’s own named biggest usability risk. See TS-4.
  • Acceptance criteria:
    • no diff merges without a human (or explicitly-scoped delegate) approving it; nothing auto-commits in v1.
    • every artifact carries question id, answerer, date, scope, expiry.
    • write-back targets an existing doc/glossary/decision-log location before proposing a new one.
    • write-back is idempotent per answered question.
  • Dependencies: CP-4’s answer quality (garbage in, garbage written back); the existing decision-log/ADR precedent (R1, R2d) as the target, not a new system; fewer than ~5 answers/week worth writing back collapses this story back to plan-001 triage per the initial recommendation’s own falsifiable test - this document does not resolve that number, it inherits it as the kill switch.
  • Permissions: the write-back agent needs write access to a docs/git branch or PR, gated by human review before merge - CODEOWNERS-partitioned, per the decided internal-plane lane (R2a-2).
  • Data: the answer plus its provenance fields; the target doc/glossary/ decision-log file.
  • Security: this is the highest-leverage single point of failure in the whole loop (a bad diff, once merged, is read as ground truth by every future agent) - see TS-4 in full.
  • Instrumentation: answers-worth-persisting per week (the initial recommendation’s own sizing metric for whether the expansion beyond triage is justified at all), diff review outcome (approved/rejected/edited), time from answer to merged diff.
  • Priority: P0.
  • Metric: answers-worth-persisting/week; below ~5/week (MODELED threshold, not measured) the expansion thesis fails by the initial recommendation’s own test.
  • Classification: MVP for the mechanism, human-gated; auto-merge without review is REJECTED (see REJ-2/TS-4).

CP-7: Next reader finds the artifact before asking (loop closure)

  • Job: confirm the loop actually closes, i.e. CP-6’s output is what CP-1 finds next time.
  • Preconditions: CP-6 has merged at least one diff.
  • Trigger: a future agent hits a related ambiguity.
  • Main flow: identical to CP-1, but now the corpus contains the new artifact; success is measured as a hit, not a re-ask.
  • Alternative flows / edge cases / failure states: shared with CP-1 and TS-2 (stale answer served as fresh); not repeated here.
  • Acceptance criteria: a new artifact becomes findable via the same search path within one docs-sync cycle (pnpm docs:sync, R1) of merging, not on a manual/occasional refresh.
  • Dependencies: CP-1, CP-6.
  • Permissions/Data/Security: as CP-1.
  • Instrumentation: re-ask rate for a topic that already has a written-back answer; a nonzero, non-decaying re-ask rate on the same topic is the clearest possible signal that write-back isn’t working.
  • Priority: P0.
  • Metric: the single number that validates or falsifies the entire expansion thesis: does self-serve rate rise and re-ask rate fall over the weeks after write-back starts, or does it stay MODELED-flat as plan 001’s failure signal predicts if the loop doesn’t actually close.
  • Classification: MVP (as a measurement, not as new code - CP-7 is CP-1 run again after CP-6 has had time to work).

5. Activation stories

ID Story Class Priority
ACT-1 As an asker agent, I want my very first question answered inside a bounded time (not open-ended silence), so that I trust the loop enough to use it again instead of guessing. MVP P1
ACT-2 As a new fleet agent, I want the corpus pointer already in CLAUDE.md/skills at spawn time, so that I search before I ask without being told to. MVP P1
ACT-3 As Robert, I want the first fleet-wide rollout throttled (a small cohort first), so that a naive-dedup v1 isn’t flooded by day-one volume before precision is known (DARK today, R2b). MVP P1

6. Retention stories (trust maintained over time)

ID Story Class Priority
RET-1 As a reader agent, I want every answer’s provenance and expiry visible at the point of use, so that I can judge freshness myself instead of trusting text alone. MVP P1
RET-2 As Tomas, I want expired answers to surface for a cheap re-check rather than silently keep being served, so that “the corpus is trustworthy” stays true past week one. Full failure mode detailed at TS-2. MVP P1
RET-3 As Robert, I want a weekly readout of the four core numbers (questions filed, duplicate rate, interrupts/day, answers-worth-persisting/week), so that the kill-switch test in the initial recommendation is actually checked, not assumed. MVP P1

7. Administrative stories

ADM-1: Robert provisions the agent-questions queue and its membership

  • Job: make the one queue this entire concept depends on actually exist.
  • Trigger: before CP-2 can file anything.
  • Main flow: Robert (or Tomas, core-plane DRI) creates the agent-questions entry in the user service’s user_groups table and adds Tomas (and Robert, for delegation) as members via the existing GET/POST /user/groups surface (R1). ASSUMED absent today; not independently verified.
  • Acceptance criteria: assigneeGroupSlug=agent-questions&status=pending returns real membership-gated results before any agent files a question.
  • Dependencies: none technical; this is a data/config action inside already-built services, not a PR - but it is still an ask that needs Tomas’s (or his delegate’s) action inside core plane, since user is core.
  • Permissions: whoever can write to user_groups today (likely ADMIN).
  • Classification: MVP, P0, blocking.

ADM-2: Robert provisions Atlas’s service identity for fan-out completion

  • Job: give the dedup/write-back service a real, scoped identity so CP-5 can call complete on tasks it did not originate.
  • Trigger: before CP-5 can run.
  • Main flow: a service account is created in core plane’s user/auth system, added to agent-questions only (never ADMIN), with credentials held by Atlas’s internal-plane service.
  • Edge cases: if this identity’s scope creeps to ADMIN “for convenience,” it becomes a standing privilege escalation risk across the whole tasks service, not just this queue - flag for SEC-1.
  • Acceptance criteria: the service identity can complete tasks in agent-questions and cannot complete, list, or touch anything outside it.
  • Dependencies: ADM-1; core-plane user/auth provisioning (needs a core-plane action, an additional ask beyond plan 001’s single sent baseline ask - name this explicitly to Tomas rather than assume it is free).
  • Permissions: scoped group-member equivalent, no broader.
  • Classification: MVP, P0, blocking, and itself a negotiated ask surfaced in the synthesis’s ask bundle (12-prd D5, corrected baseline).
ID Story Class Priority
ADM-3 As Robert, I want a hard cap on open agent-questions depth (rate-limit new tasks once the queue exceeds N pending), so that a bad naive-dedup week can’t flood Tomas past his stated capacity. MVP P1
ADM-4 As Robert, I want to manually re-route or split a mis-triaged question, so that a routing mistake doesn’t sit unresolved waiting for a human to notice on their own. MVP P2
ADM-5 As Robert or Tomas, I want to un-merge a bad dedup match after the fact and correct which agents get which answer, so that CP-3’s mistake (TS-1) is recoverable, not permanent. MVP P1
ADM-6 As Robert, I want dedup precision/recall tracked weekly and an explicit kill switch on any auto-resolve tier if it drifts, so that “auto-resolve” never runs unmonitored. MVP (monitoring) / auto-resolve itself EXPERIMENTAL P1

8. Trust-and-safety stories (full detail, as required)

TS-1: Dedup false positive silently serves the wrong answer to a different question

  • Job/failure being guarded against: two questions that look similar but are not identical get merged, and N agents working on the actually-different question are resumed with an answer that does not apply to them.
  • Evidence: industry guidance across Jira/Zendesk-adjacent merge tooling converges independently on “merges are effectively irreversible in most systems… a false-positive auto-merge can erase important context,” best practice is surface-for-human-confirmation even at similarity thresholds around 0.90, never blind auto-merge (R8 section 4, vendor-blog sourcing but convergent across independent vendors). Stack Overflow’s own aggressive human duplicate-closing culture is independently cited as a top reason experienced contributors left the platform (R8 section 4) - the failure mode generalizes even to human-judged merges, not just automated ones.
  • Direct tension with the initial recommendation: 01-initial-recommendation.md proposes an “auto-resolve ONLY on high-confidence duplicate match… always logged” tier. R8’s evidence base argues against ANY unconfirmed auto-merge, full stop, regardless of confidence. This document resolves the tension by descoping auto-resolve to EXPERIMENTAL (spike-only, not shipped) and making CP-3’s v1 behavior “always surface, never silently merge.”
  • Trigger: a paraphrased question with high keyword overlap but different actual scope (e.g. “is VIS frozen” vs “is the VIS payments submodule frozen”
    • legacy EOL code is a named, concrete generator of exactly this ambiguity, R2b).
  • Main flow (the guard, not the failure): CP-3 surfaces the candidate, Tomas or Robert confirms or rejects before any fan-out happens.
  • Failure state if unguarded: N agents proceed on a wrong premise silently; the failure is invisible until downstream work built on it breaks, at which point the cost is much higher than the interrupt the merge was meant to save.
  • Acceptance criteria:
    • no merge in v1 completes without an explicit human confirmation.
    • every rejected candidate match is logged (dedup recall data for later).
    • ADM-5 exists so a merge that slips through wrong is recoverable.
  • Dependencies: CP-3, ADM-5, ADM-6.
  • Permissions: merge confirmation requires the same ACL as task completion.
  • Data: match candidates, scores, human decision, timestamp.
  • Instrumentation: confirmed-merge accuracy over time (DARK today, no fleet-scale measurement exists, R2b).
  • Priority: P0 (as a guard against shipping auto-resolve).
  • Metric: false-merge rate, target zero tolerance in v1 by construction (no auto-merge exists to produce one).
  • Classification: the guard is MVP; unconfirmed auto-resolve is EXPERIMENTAL at best, arguably REJECTED given the weight of R8’s evidence against the initial recommendation’s own proposal.

TS-2: Stale answer served as fresh

  • Job/failure being guarded against: an answer that was true when given (e.g. “VIS is frozen, don’t touch it”) stops being true (VIS gets unfrozen, or the scope was narrower than later reused) and keeps getting served with full apparent confidence.
  • Evidence: Gartner Peer Insights reviews of Stack Overflow for Teams / Stack Internal name a recurring, named complaint directly on point: “some answers become outdated over time… there isn’t always a clear signal that a solution is no longer valid” (R6 section 1, 2025-2026 reviews). Guru’s entire differentiated feature is a scheduled re-verification precisely because timer-based decay-checking is the best broadly-proven mitigation found (R6 section 3); Slite’s contradiction-triggered write-back is a newer, architecturally closer-to-automatic approach but is five weeks old at research time with no independent track record (R6 section 7) - not a foundation to depend on yet, a pattern to imitate cautiously.
  • Trigger: the underlying fact changes after the answer was written back, or the answer’s expiry field was never set (CP-4 edge case, no platform enforcement of the answer form, R1).
  • Main flow (the guard): every written-back artifact carries an expiry or a review-by date (CP-6 acceptance criterion); RET-2 surfaces expired answers for cheap re-confirmation rather than silent continued use.
  • Alternative flows: answer never had an expiry set (blank field) -> defaults to a short, conservative review-by date, not “forever.”
  • Edge cases: an answer is technically still true but its scope was narrower than how a later reader applies it (the initial recommendation’s own named risk - “one wrong dedup match silently feeds N agents a wrong answer” applies here too, at the read side rather than the merge side).
  • Failure states: no automatic contradiction detection exists in v1 (that is Slite’s differentiator, unproven, R6); relying on it would be building on a five-week-old product’s claim - v1 must rely on scheduled expiry only.
  • Acceptance criteria:
    • every artifact has an expiry/review-by date, defaulted conservatively if the answerer left it blank.
    • an expired artifact is flagged in search results, not silently served as current.
    • a expired-but-unreviewed artifact has an owner (the original answerer, by default) who is prompted, not left to notice on their own.
  • Dependencies: CP-6, RET-2.
  • Permissions: re-confirming an artifact uses the same ACL as answering.
  • Instrumentation: count of expired-and-unreviewed artifacts over time.
  • Priority: P1.
  • Metric: percentage of served answers past their review-by date (target near zero; DESIGN target, not yet measured).
  • Classification: MVP (scheduled expiry); automatic contradiction/drift detection is EXPERIMENTAL, explicitly not v1 (the underlying pattern is five weeks old in the one product that ships it, R6).

TS-3: Confidential or sensitive data pasted into question text leaks beyond intended readers

  • Job/failure being guarded against: an agent, in the course of asking a question, pastes a code snippet, config value, or legacy-system detail that should not be broadly readable, and it ends up visible to more people than intended, or gets written back into a doc that is more widely read than the original task.
  • Two concrete leak vectors identified, not hypothetical:
    1. Task-list visibility scope is unverified. R1 documents that GET /tasks requires a VIEWER role and can filter by assigneeGroupSlug, but does not establish whether the endpoint scopes visibility by the caller’s own group membership or whether any VIEWER-role employee can list (and read the full question text of) any group’s queue by simply passing that queue’s slug as a filter. If the latter, every agent-questions question, including pasted code and legacy detail, is readable by every VIEWER-role employee, not just Tomas/Robert. ASSUMPTION, needs verification before go-live (SEC-1).
    2. reasons-and-decisions/ is explicitly confidential (unannounced org plans) per program context. An agent that reads or is influenced by that directory (it must never read or cite it) and pastes related content into a question description, or a write-back agent that summarizes an answer referencing it, would leak confidential content into a queue or a written-back doc with much broader reach than the original folder’s access control (SEC-3).
  • Trigger: any question whose “blast radius” or context field includes a code paste, a config value, a customer-data sample from legacy Ruby/Java code, or content derived from the confidential decisions folder.
  • Main flow (the guard): the question form’s structure (what I’m blocked on, what I searched, smallest answer, blast radius) should push toward describing the problem, not pasting raw sensitive material; this is a process control, not a technical one, and is insufficient alone.
  • Edge cases: an EOL legacy file (VIS ~2013, orders ~2017 frozen) may contain hardcoded secrets or real customer-shaped sample data from its era; an agent citing “here’s the exact line I’m confused by” could paste exactly that.
  • Failure states: confidential content lands in a written-back doc, which by design (CP-6/CP-1) is MORE widely read than the original task ever was - write-back is a leak amplifier, not just a leak vector, if this isn’t guarded.
  • Acceptance criteria:
    • task-list visibility scoping is verified (not assumed) before any real question is filed (SEC-1).
    • a written rule (skill or CLAUDE.md instruction) tells every agent never to read or cite reasons-and-decisions/ in a question or an answer, mirroring the constraint this very project operates under.
    • write-back review (CP-6, human-gated) explicitly checks for pasted secrets/PII before merging, not just factual correctness.
  • Dependencies: SEC-1, SEC-3.
  • Permissions: as tightly scoped as the underlying user service’s ACL model allows; this story does not introduce new permissions, it audits existing ones.
  • Instrumentation: none proposed beyond the review gate itself; a detection tool for secrets-in-text (existing off-the-shelf secret scanners, not a new build) could run over question text and diffs before either ships, per the ladder (“already-installed dependency solves it” if one exists in the CI pipeline already).
  • Priority: P0 (must be resolved before go-live, not after).
  • Metric: zero confirmed leaks; this is a binary go/no-go gate, not a trend line.
  • Classification: the verification itself is MVP-blocking; do not file a real question in production until SEC-1 and SEC-3 are answered.

TS-4: Write-back poisoning - a wrong or malicious answer becomes a permanent, trusted artifact

  • Job/failure being guarded against: CP-6 writes something false, outdated, or actively malicious into the corpus, and because write-back is the mechanism that makes future agents trust the corpus over asking again, the error compounds instead of being caught.
  • Evidence:
    • MINJA (Memory INJection Attack), NeurIPS 2025 poster, Dong et al. (https://arxiv.org/html/2503.03704v4, 2025): query-only interaction can inject malicious records into an agent’s memory bank with 95%+ injection success and 76.8% downstream attack success across tested agents (R8 section 3). This is peer-reviewed, the strongest single source in this bucket, and directly on point: Atlas’s write-back is, structurally, a shared memory bank fed by many agents’ query interactions.
    • “Agent READMEs” empirical study, arXiv 2511.12884 (2025-11-18), mined 2,303 real AGENTS.md/CLAUDE.md files: functional content (build commands, architecture) is well-maintained, but security guidance appears in only 14.5% of files and performance guidance in only 14.5% - i.e. even actively-maintained agent-memory files systematically under-cover the categories of content most likely to prevent costly mistakes (R8 section 3). Directly suggests write-back agents will default toward documenting the convenient and skipping the safety-relevant.
    • MindStudio anecdote (undated blog, lower confidence): a memory file written on day 1 persists unless someone manually deletes it, and corrections made verbally vanish at session end while the (possibly wrong) written memory persists (R8 section 3) - the asymmetry this story exists to prevent: a written artifact should be easier to correct than to create, not the reverse.
    • Legal/reputational precedent that “the bot said it, not a human” is not a valid defense: Moffatt v. Air Canada, 2024 BCCRT 149 (adjudicated, 2024-02), tribunal rejected the argument that a chatbot is a “separate legal entity” and held the company to a standard of reasonable care regardless of who/what made the representation (R8 section 4). The Cursor support-bot incident (April 2025, AI Incident Database #1039) shows the failure mode is not loud: a wrong answer that is believed causes real action (customers canceled subscriptions) before anyone corrects it (R8 section 4).
  • Trigger: any CP-6 draft, whether from a genuinely wrong human answer, a hallucinated summary of a correct answer, or (adversarial case) a compromised or careless agent deliberately or accidentally injecting a false “fact” that looks like a legitimate answer.
  • Main flow (the guard): human-gated review before merge (CP-6 acceptance criteria), provenance footer on every artifact so a bad entry is attributable and revertible, and git as the storage medium specifically because it is append-only-with-history rather than a mutable memory blob (durability argument already in the initial recommendation, reinforced here: git history is the difference between Atlas and the vulnerable “memory bank” MINJA targets).
  • Edge cases: review fatigue - if answers-worth-persisting/week is high enough that review becomes routine rubber-stamping, the guard degrades to the same failure mode as no guard at all; this is the initial recommendation’s own named question (“who reviews machine-written doc diffs at fleet scale, and does that review itself become the new bottleneck”) and this document does not resolve it, it inherits it as an open risk.
  • Failure states: a bad artifact merges, gets found and trusted by CP-1/ CP-7, and propagates its error into the next agent’s actual code changes before anyone notices - the cost compounds silently exactly the way the peer-reviewed memory-poisoning research describes.
  • Acceptance criteria:
    • no artifact merges without human review (CP-6, restated here as a trust-and-safety gate, not just a workflow step).
    • every artifact is revertible via normal git history, with the provenance footer making “who wrote this and from what answer” always answerable.
    • review load is monitored (ADM-6-adjacent); if answers/week grows past what a human can meaningfully review (not just click through), that is itself a signal to slow down write-back, not speed up auto-merge.
  • Dependencies: CP-6, ADM-6.
  • Permissions: write-back agent has PR-open rights only, never merge rights, in any configuration.
  • Instrumentation: review outcome distribution (approved as-is / edited / rejected) - a near-100% as-is approval rate over time is itself a warning sign of rubber-stamping, not a success metric.
  • Priority: P0.
  • Metric: reverted-artifact rate (how often a merged write-back later needed correction) - target near zero, currently unmeasurable (no artifacts exist yet).
  • Classification: the human-gate is MVP and non-negotiable; any variant that removes the human gate (auto-merge on confidence, “self-healing docs” a la Slite’s five-week-old pattern) is REJECTED for v1 (see REJ-2).

9. Security-reviewer stories

  • SEC-1 (blocks TS-3): audit whether GET /tasks?assigneeGroupSlug= scopes results to the caller’s own group membership or exposes any VIEWER-role employee to any group’s full queue; resolve before any real question is filed. MVP, P0.
  • SEC-2: confirm the internal plane genuinely cannot call _workflowSignalSend or any other core-plane expose:false endpoint directly (R2a-3’s “no cross-plane signal bridge yet” should mean Atlas’s fan-out logic MUST run through the exposed, authenticated complete API, never a shortcut); a shortcut found here would be a boundary violation, not a convenience. MVP, P0.
  • SEC-3 (blocks TS-3): confirm no agent-facing skill, prompt, or write-back path can surface content from reasons-and-decisions/; add an explicit, tested negative case (an agent asked to explain something from that folder must decline or redirect, not summarize it into a question or an artifact). MVP, P0.
  • SEC-4 (restates TS-4 from the audit side): confirm write-back diffs are gated by human review in the actual CODEOWNERS configuration, not just in this document’s intent - a misconfigured auto-merge branch protection rule would silently defeat every acceptance criterion in TS-4. MVP, P0.

10. Future-team-reader stories (audience does not exist yet)

All of the following are legitimate future work and none are rejected outright (a team will eventually exist), but none are MVP, because program context confirms no third stakeholder exists today (R2a-6).

ID Story Class Priority
FUT-1 As a future team reader, I want to receive the generated GChat digest without asking to be added manually, so that onboarding to “what’s happening” doesn’t require Robert’s manual effort per person. POST-MVP P3
FUT-2 As a future team reader, I want to browse the glossary/decision log directly in git/markdown without touching the tasks UI (which is not their tool), so that reading requires no new account or training. POST-MVP P3
FUT-3 As a future team member, I want my own way to ask a question (not the agent-questions queue, which is fleet-scoped), so that human questions don’t crowd out agent dedup logic built for a different volume/shape. EXPERIMENTAL P3

11. Stories that must NOT be implemented initially

  • REJ-1: Portal/wiki UI for browsing Atlas content. Every sibling factory app (work-ledger, fleet monitor) already removed custom UI/kanban/control- room from its own concept as a standing anti-pattern (R2c); Backstage’s own adoption data is the sharpest cautionary evidence available: ~10% external adoption vs ~99% at Spotify itself, 6-12 months to a usable instance, 2-5 FTEs of ongoing cost, ~$150K TCO per 20 developers (Port.io newsletter, 2026-03-31, commercial-competitor source but independently corroborated by a second Medium piece, R8 section 2) - and TechDocs’ own underlying engine (MkDocs/Material) is heading into unmaintained territory on a named clock (per an open Backstage GitHub RFC, #33990, accessed 2026-07-18, R6 section 8). For a 2-human audience, this cost is indefensible. REJECTED.
  • REJ-2: LLM auto-answers without a human decision anywhere in the chain. Air Canada was held liable for its chatbot’s fabricated policy (Moffatt v. Air Canada, 2024 BCCRT 149) and Cursor’s support bot fabricated a policy that caused real subscription cancellations before correction (AI Incident Database #1039, April 2025) - both are on-point precedent that “the bot answered wrong” is not a neutral failure, it is an accountability problem for whoever owns Atlas. Combined with MINJA’s peer-reviewed 95%+ memory- injection success rate, any path that lets an answer reach an agent or a doc without a human decision is unacceptable in v1. REJECTED; the narrower “auto-resolve on high-confidence exact-duplicate, always logged” tier from the initial recommendation is downgraded to EXPERIMENTAL at most (see TS-1).
  • REJ-3: Org-wide/company-wide comms broadcast. Program context and all three sibling plans confirm no organization exists to broadcast to today (R2a-6); building distribution lists, subscription management, or a broadcast channel for an audience of zero is pure speculation. REJECTED for v1; revisit only when FUT-1 has a real audience.
  • REJ-4: Real-time status dashboard / control room. Both work-ledger and fleet monitor explicitly removed “kanban board,” “metric wall,” and “control room” framing from their own concepts (R2c/R2d); fleet monitor already owns the daily-digest-to-Tomas mechanism (R2d) - Atlas building a second status surface duplicates a sibling’s decided territory rather than filling a gap. REJECTED; if fleet monitor’s digest needs Atlas data, Atlas exposes data to it, it does not build its own screen.
  • REJ-5: Embedding/semantic (RAG) search replacing exact-match dedup in v1. Plan 001’s pre-mortem is explicit and falsifiable: naive exact-match dedup ships first, embeddings only if measured miss-rate demands it, never the reverse (R2b) - and no existing search primitive in the codebase supports it today anyway (only an in-memory substring scan over 23 files, R1 section 5). REJECTED for v1; candidate for POST-MVP once CP-1/CP-3’s naive version has measured data showing it’s insufficient.
  • REJ-6: Atlas as a second, competing ADR/knowledge system. A MADR-style decision-log mechanism is proposed (research/12 §4) but not yet implemented; the running precedent today is Tomas’s flat, append-only decision log (root CLAUDE.md) (R2d). Atlas’s glossary/decision ambition must render through whichever of these is authoritative (per CP-6’s main flow), not stand up a parallel one. Building a second system here is the single most concrete way this expansion could waste effort duplicating already-claimed territory. REJECTED as a standalone system; folded into CP-6 as a rendering, not a rebuild.

12. Traceability table

ID Persona Stage Class Priority Metric
CP-1 Reader agent Search MVP P0 Self-serve hit rate
CP-2 Asker agent Ask MVP (blocked, Sec.3) P0 Questions filed/day
CP-3 (system) Dedup/route MVP P0 Duplicate rate
CP-4 Tomas Answer MVP P0 Interrupts/day before-after
CP-5 (system) Resume MVP (assumption flagged) P0 Resumed/attached ratio
CP-6 Write-back agent Persist MVP, human-gated P0 Answers-worth-persisting/week
CP-7 Reader agent Loop closure MVP (measurement) P0 Self-serve rate trend
ACT-1..3 Asker/new agent/Robert Onboarding MVP P1 Time-to-first-unblock
RET-1..3 Reader/Tomas/Robert Ongoing trust MVP P1 Provenance completeness, expiry compliance
ADM-1 Robert Provisioning MVP P0 blocking Queue exists and is member-gated
ADM-2 Robert Provisioning MVP P0 blocking Scoped identity exists
ADM-3..6 Robert/Tomas Ongoing admin MVP P1-P2 Queue depth, precision/recall
TS-1 (system) Dedup safety MVP guard / EXPERIMENTAL auto-resolve P0 False-merge rate
TS-2 Reader/Tomas Staleness MVP scheduled / EXPERIMENTAL drift-detect P1 % served past review-by
TS-3 Security Confidentiality MVP-blocking verification P0 Zero confirmed leaks
TS-4 (system) Write-back safety MVP human-gate P0 Reverted-artifact rate
SEC-1..4 Security reviewer Audit MVP P0 Pass/fail per audit
FUT-1..3 Future team reader (dormant) POST-MVP/EXPERIMENTAL P3 N/A, no audience yet
REJ-1..6 n/a n/a REJECTED n/a n/a

13. Open questions carried to synthesis

  1. Section 3’s foundational dependency (how does an out-of-workflow agent ever reach createFromWorkflow) is unresolved and blocks CP-2. This is more load-bearing than plan 001’s final single sent ask (the three-ask draft was reduced by the architect addendum) and should be verified against workflow-management’s actual API before anything else in this document is built.
  2. CP-5’s fan-out-via-N-completion-calls mechanism is an ASSUMPTION about how to honor “one answer, every agent resumes” without a schema PR; it needs a real implementation spike, not just this document’s reasoning, before it’s trusted.
  3. ADM-2’s service identity is a real, scoped new ask to core plane (user/auth provisioning) beyond plan 001’s single sent baseline ask; this should be surfaced explicitly rather than assumed free.
  4. SEC-1 (task-list visibility scoping) is a go/no-go gate for filing any real question, not a nice-to-have; do not let CP-2 ship ahead of it.
  5. TS-1 directly contradicts the initial recommendation’s “auto-resolve on high-confidence match” proposal using the same evidence base this project commissioned; the synthesis should either accept this document’s descope to EXPERIMENTAL or explicitly argue against the R8 evidence, not split the difference silently.
  6. CP-6/TS-4’s review-fatigue risk (“does review itself become the new bottleneck”) is inherited, not resolved, from the initial recommendation’s own open question 6. No evidence source in R1-R8 answers it either.