12 - Product Requirements: Atlas (the answer loop)

Passport convention (binding, per root CLAUDE.md’s communication-standards summary; the underlying reasons-and-decisions/08-communication-standards.md is confidential and was not read directly): every number carries MEASURED (real fleet data), MODELED (estimated from an analog or formula), DARK (genuinely unmeasured), or DESIGN (a target the team is choosing). No em-dashes. Plain English, receipts not adjectives. Where two prior docs conflict, this PRD decides and names the conflict inline.

Scope note: the concept under test is “the intelligence and communication layer for large-scale legacy refactoring.” Every prior doc in this plan (02 research, 05 competitive, 09 north-star, 08 made-to-stick) reached the same verdict from a different premise: only the answer loop is a system; docs, glossary, and the digest are renderings of it; the comms/status platform serves an audience that does not exist. This PRD specifies the loop and its renderings, and it drops the “intelligence and communication layer” name for anything Tomas-facing. That is not a softening of the concept, it is what survived scrutiny.

1. Executive summary

A 64-agent fleet (MEASURED ceiling) rebuilding a 1.05M-LOC EOL legacy estate generates a stream of ambiguities it cannot resolve alone, and the program has exactly one authorized answerer, Tomas Zaruba, who is decision-bound by his own account (“vic agentu mi nepomuze”). The substrate already captures a question (INFORMATION_REQUEST tasks), routes it (group queues), and resumes a blocked agent (Temporal signal-resume). Two things are missing and only two: dedup on the way in (N agents hitting one ambiguity should cost the human once, not N times) and write-back on the way out (an answer should become a findable artifact so the next agent never re-asks). Atlas is those two pieces plus the fan-out that connects them, built thin on Tomas’s greenfield monorepo, zero PRs to his code in v1.

The product is a loop: search-first, file-structured, dedup, route one, answer once, fan out to all attached askers, write the answer back as a provenance-stamped diff, render a digest line. Documentation, GLOSSARY.md, and the digest are generated from the answer ledger, never hand-maintained, so they cannot rot on their own schedule.

The MVP does not miniaturize the vision. It tests the four assumptions that would kill the concept if false: that duplicates are frequent enough for dedup to matter (RA-1), that a machine-written corpus stays trustworthy enough that agents read it before asking (RA-2), that content dedup can hit a safe false-merge rate (RA-3), and that human-gated write-back review does not become the new bottleneck (RA-4). One real fleet wave, one week, four numbers, one kill test.

2. Problem statement and evidence

Problem. The human answer does not compound. It is neither de-duplicated on the way in nor persisted on the way out, so the program’s single scarcest resource, architect decision-hours, gets spent again and again on questions already answered.

Evidence (FACT unless labeled):

The fleet ceiling is 64 concurrent (MEASURED); two humans total; Tomas is the sole scarce answerer (program ground truth).
EOL/dead-owner legacy code is a named, high-volume question generator: VIS frozen ~2013, orders frozen ~2017 (MODELED volume), producing “is this alive / who owns this” at scale (analysis/legacy/SYNTHESIS.md, R2).
The substrate already does capture, route, and resume: INFORMATION_REQUEST task type, assigneeGroupSlug group queue, TaskWorkflowStamp + _workflowSignalSend (R1). What is not built: content dedup, write-back, and the fan-out from one answer to N attached askers (R1).
No product or OSS project surveyed closes the loop “N agents hit one ambiguity, merge to one question, one human answers, all resume, answer persists” (R3, R6, R7). The gap is real and empty.
INTERPRETATION: the binding constraint is answer-reuse, not answer-capture. Capture is a solved substrate feature; reuse (dedup in, persist out) is not.
The four sizing numbers are DARK: questions/day, duplicate rate, interrupts/day before/after, answers-worth-persisting/week. No fleet-scale data exists anywhere in public literature (R2, checked twice). Frequency is a validation target, not an input.

3. Goals

G1. Spend Tomas’s decision-hours once per distinct question, never twice. (North Star: interrupts per merged work unit, falling while output holds.)
G2. Make an answer findable by the next agent before it can ask again (write-back that actually closes the loop).
G3. Add zero PRs to Tomas’s core-plane code in v1; reuse the existing tasks, Temporal, git, and chat substrate.
G4. Keep the corpus trustworthy: provenance, scope, and expiry on every served fact; never serve a stale answer as fresh.
G5. Produce the four validation numbers on one real fleet wave, so the expansion is decided by measurement, not by the concept name.

Non-goal-shaped clarification: G1 succeeds by absence (fewer interrupts), not by usage volume. Rising question volume is not success.

4. Non-goals

N1. A portal, wiki, website, dashboard, or control room. No new human UI. (Rejected in 04 REJ-1, 09 non-goals, and both sibling plans.)
N2. An org-wide communication or status platform. No org exists to communicate with; every standalone status product surveyed is dead or absorbed (Atlassian Atlas retired 2025-05-21; Friday.app dead 2022; R5).
N3. A second daily message. Atlas contributes rows to the fleet-monitor digest (plan 004), it does not send its own channel (see FR and 07 point 2). Interim exception in FR-24.
N4. LLM auto-answers with no human decision anywhere in the chain (04 REJ-2; Air Canada / Cursor precedent, MINJA 95%+ injection, R8).
N5. Embedding / RAG / vector search in v1 (04 REJ-5; grep + Postgres exact/trigram only until a MEASURED miss-rate demands more).
N6. A standalone SaaS product. Not built for resale or for other teams.
N7. Legacy documentation authoring. The audit extractor (plan 001) owns legacy evidence; Atlas links, never duplicates or re-authors.
N8. A single source of truth for all program knowledge (09 risk #7). Atlas is the canonical ledger for questions it actually mediated, cross-linking to the existing decision log, work-ledger, and audit extractor, never superseding them.
N9. SLA tracking, escalation, reminders, multi-team routing trees, invented backpressure. Dedup is the only rate-limiting in v1.
N10. Writing to the confidential reasons-and-decisions/ directory, ever. Atlas decision records live in its own lane (see FR-19). This overrides the stray reference in 04 CP-6 and 08 that named reasons-and-decisions/07-decision-log.md as a write target.

5. Product principles

One answer, once. Every distinct question gets exactly one durable answer; every future asker finds it before asking again.
Renderings, not systems. Docs, glossary, and digest are generated views of the answer ledger. The moment one becomes hand-maintained it starts rotting on the same clock every wiki rots on.
No new human UI. Reuse the tasks completion surface, chat, and git.
Silence is success. A quiet week for Tomas is the win condition.
Provenance over confidence. Every served fact carries who decided it, when, its scope, and its expiry. Nothing is presented as fresher or more certain than it is.
Human-gated write, machine-gated read. Agents read the corpus freely; anything entering it as new truth passes a one-human-decides step (or an exact-duplicate auto-resolve that reuses a prior human decision, logged).
Corpus growth is a cost, not a KPI, until it is shown to prevent a repeat interrupt.
Bias to false-new over false-merge. A missed merge costs one extra routed question; a wrong merge silently feeds N agents a wrong answer.

6. Personas (including agent personas)

Persona	Human?	Job
Asker agent	No	Get unblocked with the smallest possible interruption to the one human who can answer.
Reader agent	No	Resolve the ambiguity from the corpus before ever filing a question, so the interrupt never happens. (Same running instance as asker; distinct behavior.)
Write-back agent	No	Turn one completed answer into a permanent, provenance-stamped, findable artifact. Untrusted until a human approves its diff.
Atlas service identity	No	The scoped machine actor that mints Core tasks, reconciles completed tasks, and fans out one answer to all attached askers. Member of `agent-questions` only, never ADMIN.
Tomas Zaruba (architect)	Yes	Answer each real question exactly once, in a tool he already uses; keep his core plane clean of factory process. The protected resource.
Robert (operator/router/admin/reviewer)	Yes	Keep the queue sane, provision the lane, judge near-duplicate merges in wave 1, review write-back diffs for fidelity, watch the four numbers, ship or kill.
Security reviewer	Yes	Confirm the loop cannot leak, forge, or corrupt across the internal/core plane boundary before go-live.
Future team reader	Yes	Deferred audience. Does not exist today (program ground truth). Not designed for in MVP.

7. Jobs to be done

Primary JTBD (Christensen framing, 02 §2.5): When my agent hits an ambiguity it cannot resolve from the repo, I want an authoritative decision that keeps the fleet moving, without spending my one architect on a question he or the corpus has already answered.

Functional: get a correct, authoritative decision for a blocked agent, once, and make it reusable so it is never bought again.
Emotional: the operator stops worrying that 64 agents are silently building on wrong guesses; the architect feels his scarce time is spent on genuinely new decisions.
Social: the architect does not want to be the visible blocker of a 64-agent fleet; the operator wants to show the program compounds knowledge rather than re-litigating it.

What is “hired” today and why it is fired: Robert relaying in GChat (fired: does not scale, is itself the bottleneck); raw INFORMATION_REQUEST tasks (fired: no dedup, no memory); conventions/skills/grep (fired: nothing writes new answers into them). Atlas must beat all three by doing the compounding third that none of them does.

8. Journeys

Full journey analysis is in 03-journey.md (19-stage adaptation, 8 variant journeys, sequence diagrams). Not duplicated here. The MVP-load-bearing paths:

Happy path (03 variant A): ambiguity, search corpus, miss, file structured question, dedup, route one, Tomas answers once, fan-out resumes all attached askers, write-back diff, digest line, next agent self-serves.
Cold-start (03 variant B): week 1 corpus is empty by construction, every question is a miss, interrupts look like a no-Atlas baseline until the corpus has depth. Judge at week 4, not week 1.
Failed write-back (03 variant E): answer resumes agents but the diff never lands; the loop silently degrades to plan-001 triage; “task completed” looks identical whether or not write-back succeeded. Must be instrumented as a distinct state.
Wrong dedup match (03 variant F): the highest-blast-radius silent failure; one false merge feeds N agents a wrong answer and, if written back, poisons the corpus for all future askers.
PII leak (03 variant G): a question quotes real legacy data; write-back would convert transient exposure into permanent, searchable exposure. Write-back is a leak amplifier if unguarded.

9. User stories (MVP-critical, inline)

Full set with acceptance criteria in 04-user-stories.md. The MVP-critical stories (all P0 unless noted):

CP-1 Reader self-serves before asking. Search corpus; hit returns provenance + expiry; proceed with no interrupt. (P0)
CP-2 Asker files a structured question through Atlas’s endpoint; five forced fields; workflow stamp attached for resume. (P0)
CP-3 Dedup attaches a duplicate to an open question instead of minting a second task. Exact-normalized-key auto-attach; fuzzy is human-confirmed only in v1. (P0)
CP-4 Tomas answers once in his existing completion surface; five-field answer (decision, rationale, scope, expiry, confidence). (P0)
CP-5 Answer fans out and resumes every attached asker (signal for stamped, poll-flip for pollers); resumed==attached is logged. (P0, mechanism flagged ASSUMPTION until a spike proves it.)
CP-6 Write-back converts the answer to a durable, human-gated, provenance-stamped artifact. No auto-commit. (P0)
CP-7 Next reader finds the artifact before asking (loop closes; this is the activation event, measured not new code). (P0)
ADM-1 Provision the agent-questions queue and membership. (P0, blocking)
ADM-2 Provision Atlas’s scoped service identity for fan-out. (P0, blocking; a real core-plane ask, see §21.)
RET-1/2/3 provenance+expiry at point of use; expired answers surfaced not silently served; weekly readout of the four numbers. (P1)
TS-1 no fuzzy merge without human confirmation; TS-2 no stale-served answer; TS-3 no sensitive-data leak (SEC-1 verified first); TS-4 no un-reviewed write-back merge. (P0)
SEC-1..4 boundary and confidentiality audits before go-live. (P0)

10. Functional requirements (numbered, testable)

Ingest and search:

FR-1. Atlas SHALL expose an internal-plane endpoint ask_question(rawText, askerRef, unitRef?, workflowAttachment?, classificationHint?) and a Claude Code skill wrapping it. Test: a call persists a Question row and returns {questionId, canonicalId, state}.
FR-2. Atlas SHALL expose search_answers(query, scopeHint?) returning ranked answers each carrying provenance (who, when, scope, expiry). Test: a query over a seeded corpus returns hits with all four provenance fields present.
FR-3. The asker agent SHALL reach Atlas, not Core, directly. Atlas (a backend service) mints the Core task in-cluster via _taskCreateFromWorkflow. This resolves the 04 §3 subagent-cannot-ask dependency: agents never call Core; a custom MCP proxy/skill calls Atlas’s endpoint. Test: an ask from a subagent-driven flow results in a Core task with no direct Core call from the agent.
FR-4. ask_question SHALL validate the five-field capture schema Atlas-side (Core has no payload validation, R1): blockedOn, searched[], smallestUnblockingAnswer, blastRadius, quotedDataClass in {NONE, CODE_SNIPPET, SAMPLE_DATA, CUSTOMER_PII_OR_SECRETS}. Test: a payload missing any field is rejected with a typed error before any Core call.
FR-5. The five fields SHALL render into the Core task description as structured markdown at mint time. No tasks schema change. Test: minted task description contains all five labeled fields.

Dedup:

FR-6. Atlas SHALL compute a normalized key (lowercase, strip punctuation, collapse whitespace, drop stopwords, extract entity tokens: service name, file path, symbol) per question. Test: two paraphrases of one entity-question produce the same key; two different-entity questions do not. (Runnable assert self-check required.)
FR-7. On an exact normalized-key match to an OPEN or ROUTED canonical, Atlas SHALL auto-attach the new Question to that canonical and SHALL NOT mint a second Core task. Test: two exact-key asks yield one Core task and attachedCount == 2.
FR-8. On an exact normalized-key match to an ANSWERED, unexpired, unrevised canonical of identical scope, Atlas SHALL auto-resolve: return the existing answer immediately, log the event, mint no task, interrupt no human. Test: an exact re-ask of a fresh answer returns the answer with zero new tasks and one logged auto-resolve.
FR-9. On any fuzzy or near match (paraphrase, different scope, or any match against an ANSWERED canonical that is not an exact re-ask), Atlas SHALL surface a candidate to a human and SHALL NOT auto-merge or auto-resolve. Test: a near-match produces a candidate record awaiting human confirm/split, never an automatic merge. (This resolves the conflict between 01/07/10, which permit exact auto-resolve, and 04 TS-1, which pushes all auto-resolve to EXPERIMENTAL: v1 auto-resolves only exact-key identical-scope re-asks, guarded and audited; everything fuzzier is human-confirmed. Fuzzy pg_trgm scoring is computed post-hoc for calibration in wave 1, not used to gate anything.)
FR-10. On any dedup lookup failure, Atlas SHALL degrade to “create new canonical” (false-new is safe; false-merge is not). Test: a forced lookup error yields a new canonical, not a merge.

Route, answer, fan-out:

FR-11. On a new canonical, Atlas SHALL mint exactly one INFORMATION_REQUEST task with assigneeGroupSlug="agent-questions", entityType="atlas_question", entityId=canonicalId. Test: the completed-task reconcile can map a task deterministically back to its canonical.
FR-12. If Core is unreachable at mint time, Atlas SHALL persist the Question OPEN with coreTaskId=null and retry via cron; the asker still receives a questionId to poll. Test: mint failure never loses a question.
FR-13. Tomas SHALL answer via POST /tasks/:id/complete with a five-field answer payload: decision, rationale, scope, expiry (date or no-expiry, DESIGN default 90 days out), confidence in {high, medium, low}. Test: a completion with those fields persists one Answer row with full provenance.
FR-14. Atlas SHALL own fan-out. On reconcile of a completed canonical task, Atlas SHALL resume every attached asker: signal each stamped WorkflowAttachment via workflow-proxy to _workflowSignalSend, and flip the canonical to ANSWERED so pollers pick it up on next search_answers/get_answer. Test: one completed task resumes N attached workflows and flips one canonical. (Design per 10 §5.1. This is the single highest technical risk, §23 R1; the alternative “N completion calls” from 04 CP-5 is the documented fallback if the attachment-signal path fails a spike.)
FR-15. A single failed fan-out resume SHALL NOT block the others and SHALL be logged and retryable. Test: 5 of 6 resumes succeed, the 6th is logged as failed, the batch completes.
FR-16. Reconcile SHALL be idempotent on coreTaskId. Test: re-processing a completed task is a no-op.

Write-back and renderings:

FR-17. When an Answer is persisted, the write-back worker SHALL draft a provenance-stamped artifact (a GLOSSARY.md entry and/or a decisions/NNNN-slug.md record) and open a review-gated PR. No auto-commit. Test: an answered canonical lacking an ArtifactLink produces exactly one PR and one ArtifactLink row (status proposed); idempotent per canonical.
FR-18. Every write-back artifact SHALL carry a provenance footer: question id, N attached, decided-by + date, drafted-by (model), confidence, scope, expiry, quotedDataClass. Test: a generated diff missing any footer field fails the write-back check.
FR-19. Write-back SHALL target Atlas’s own internal-plane lane docs/atlas/ (GLOSSARY.md, decisions/), self-mergeable within Robert’s CODEOWNERS partition, NOT the core-plane _documentation/ pipeline in v1. Decision and conflict noted: 07 point 1 argues _documentation/ is core-plane and human-gated, so every write-back there would be a Tomas-reviewed PR that recreates the review bottleneck and blows the three-ask cap; 10 §3.6 argues writing into _documentation/ gives free docs-MCP search. v1 takes 07’s position (zero new ask to Tomas) and accepts the cost: the corpus is invisible to Zaruba’s GET /docs/search/docs-MCP until a fourth ask is negotiated. Adopting the shared pipeline is a post-MVP move (§22 stage 3). Open verify item: whether the internal plane can write a subtree of _documentation/ without a Tomas-gated PR; if it can, 10’s free-search wins and this decision flips. Test: a merged write-back appears under docs/atlas/, not _documentation/ or reasons-and-decisions/.
FR-20. Agents SHALL discover docs/atlas/ via a one-line import in the internal-plane CLAUDE.md/AGENTS.md and plain grep/file-read. No new indexed search tool in v1. Test: a fresh agent session surfaces the glossary index at start via the import.
FR-21. Write-back SHALL hard-block automatic diffing when quotedDataClass == CUSTOMER_PII_OR_SECRETS; a human must redact before anything reaches docs/atlas/ or the digest. Test: a sensitive-classified answer never produces an auto-drafted diff.

Correction and expiry:

FR-22. Answers SHALL be append-only, supersede-never-edit, with a supersedesAnswerId chain. A revised answer creates a new record; the old artifact gets Status: superseded. Test: a revision leaves the old record intact and links forward.
FR-23. On revision, still-open attached questions SHALL be re-signaled with the corrected answer. Agents that already consumed the old answer and finished CANNOT be reached (no push-to-agent channel exists, R1); this SHALL be stated, not smoothed. Test: an open attachment receives the correction; a closed one is logged as unreachable.
FR-24. search_answers SHALL never return an answer past its expiry as bare fact; it SHALL append EXPIRED <date>, scope <X>, confirm before relying, file a new Question if unsure. Test: a past-expiry hit always carries the warning string.

Digest:

FR-25. Atlas SHALL contribute a capped block (DESIGN N = 3 to 5 items plus a link to the full index) to the fleet-monitor digest (plan 004), not send its own channel. Every count carries its passport (MEASURED for direct ledger reads). A zero-activity day renders “0 decisions today”, never an omitted section. Test: Atlas emits digest rows via the fleet-monitor interface, capped, passport-stamped. Interim exception: if the fleet-monitor digest is not live at wave time, Atlas MAY emit a single one-way GChat line itself (the ~20-line webhook of 10 §3.5), clearly marked interim, same channel, same cap; removed once fleet-monitor’s digest exists. (This reconciles 07 point 2, digest is fleet-monitor’s, with 09/10, which spec an Atlas digest cron: Atlas owns the render function, fleet-monitor owns the send.)

11. Non-functional requirements

NFR-1 Latency, search_answers: p95 < 300 ms (indexed Postgres query). DESIGN. This is the read that gates search-before-ask; if it is slow, agents skip searching.
NFR-2 Latency, ask_question: p95 < 500 ms (a write plus a pg_trgm lookup). DESIGN.
NFR-3 Resume latency: instant for a stamped asker (signal); at most one reconcile interval (DESIGN 60 s) for a poller. DESIGN.
NFR-4 Availability (honest, local-first): everything runs on encore run today; infra is 0% provisioned behind a billing gate (R1). There is no uptime SLA, no HA, one local Postgres, no Grafana until the gate clears. Availability in v1 is best-effort local development, stated plainly. The compounding asset is markdown-in-git, which survives any Atlas outage; a down loop blocks new asks but loses nothing already written. DESIGN targets (p-latencies, resume interval) are aspirational, not guaranteed.
NFR-5 Auditability: append-only answers with a supersede chain; every Answer carries provenance (who, when, which Core task); every ArtifactLink ties a rendered fact to the answer and PR that produced it. Any doc line SHALL be traceable to a human decision. Test: pick any glossary line, walk it back to a completed task and answerer.
NFR-6 Reliability of resume: a signal-send failure fails the whole completion by design in the substrate (R1); a dropped resume is a hard bug, tracked at zero tolerance, not a soft degradation.
NFR-7 Trust completeness: 100% of served answers carry complete passport metadata (who, when, scope, expiry) by construction; anything less is a defect, not a KPI to optimize gradually.

12. UX requirements

The UX is three objects, no screens Atlas owns. Full spec in 07-ux-ui.md.

Question capture form (agent-facing): the five forced fields (FR-4). Field descriptions in the skill SHALL be concrete (“paste the exact grep/search calls you ran”, not “what did you search”) to prevent schema-compliant garbage, since agents do not abandon forms, they rubber-stamp them (07 §7.1).
Answer form (Tomas-facing): the five fields (FR-13), attached as the task formSchema, filled via formPayload on completion. Surface caveat: “inside Zaruba’s tasks UI” is an ASSUMPTION, not a verified fact (07 point 4); no frontend completion route was confirmed in the substrate read. The form SHALL work against the backend contract either way; the named fallback is a direct POST /tasks/:id/complete (curl, a thin CLI, or dictated to an agent). Verify the frontend before treating “inside the tasks UI” as load-bearing.
Digest (Tomas/Robert-facing): capped rows into fleet-monitor’s digest (FR-25), plain English, no em-dashes, passports inline, confidence:low never rendered with the same certainty as high.

13. Accessibility

N/A for v1. Reason: Atlas owns no rendered human UI surface. The two humans use an existing task-completion surface (whose accessibility is its owner’s concern), a chat digest, and plain markdown in git. There is no Atlas-owned screen, form-render, or color/contrast decision to make accessible. Revisit only if a future audience forces an owned surface (§22 stage 3).

14. Data requirements (including PII classification)

Entities (full model in 10 §4): Question, CanonicalQuestion, Answer, WorkflowAttachment, ArtifactLink. Naming discipline (R2): never “ticket”, “issue”, or “FAQ”; the Core artifact is a Task of type INFORMATION_REQUEST, referenced by id only.

DR-1. One Question row per raw ask, even duplicates, carrying rawText, normalizedKey, classification in {none, internal, sensitive}, optional unitRef (work-ledger link, never duplicated).
DR-2 PII classification of question text. Question text may quote legacy Ruby/Java carrying credentials or customer data. Two-layer control: (a) the agent-declared quotedDataClass field (FR-4); (b) a deterministic regex denylist (gitleaks-style key patterns) at ingest, a hit sets classification=sensitive. No LLM in the redaction path. Test: a seeded secret pattern flips classification to sensitive.
DR-3. sensitive rows SHALL have rawText redacted after a retention window (DESIGN 30 days), keeping normalizedKey and metadata so dedup and audit still work.
DR-4. The digest SHALL never emit question bodies and SHALL skip sensitive items entirely, rendering “one redacted question routed to ”. Sensitive text SHALL never reach the digest or a write-back artifact without explicit human clearance (FR-21).
DR-5 Retention. Answers are kept indefinitely (the compounding asset). Supersede-never-edit means full history is reconstructable.
DR-6. Answer classification inherits the question’s; a sensitive answer follows the same redaction and clearance rules.

15. Integrations

Seam	Mechanism	PR to Core?
tasks (mint)	`tasks._taskCreateFromWorkflow` via Atlas’s core-client adapter with a service-account token (the path workflow-proxy already uses)	No
tasks (detect answer)	reconcile cron on `tasks.tasksList` filtered by group, type, status, `entityType=atlas_question`, cursor on `completedAt`	No
tasks (route)	mint with `assigneeGroupSlug="agent-questions"`; membership is a config act in the `user` service	No, config only
Temporal (resume)	fan-out signals each WorkflowAttachment via workflow-proxy to `workflow-management._workflowSignalSend`	No
git (write-back)	reuse the `github` internal service GitHub API writes; PR into the factory lane, target `docs/atlas/`	No
GChat (digest)	rows into fleet-monitor’s digest; interim one-way webhook POST if fleet-monitor not live	No

The one manual, non-code ask that is genuinely config: create the agent-questions group and add answerers (a user service act). See §21 for the full honest ask list.

16. Roles and permissions

Asking/reading agent: call ask_question/search_answers; read the corpus; treat all corpus content as data, never as instructions. No write access to Answers or Core tasks.
Atlas service identity: mint tasks; reconcile; fan out (signal attached workflows). Scoped to agent-questions only, never ADMIN (04 ADM-2, SEC-1). A standing privilege if it creeps to ADMIN, so it must not.
Tomas (answerer): complete canonical tasks (existing ACL: assignee, group member, or ADMIN); author Answers. No new grant needed beyond group membership.
Robert (operator/admin/reviewer): admin; wizard-of-oz dedup judge in wave 1; confirm/split fuzzy candidates; review write-back PRs for fidelity, not correctness (did the diff render what Tomas decided, not “was Tomas right”); merge in his lane; read the digest.
Write-back agent: PR-open rights only, never merge rights, in any configuration.
Security reviewer: audit-only; gates go-live on SEC-1..4.

17. Analytics and instrumentation

The counters the validation plan needs (RET-3, 09 §15). Each is instrumented from day one because the invisible-success case produces no rows unless deliberately logged (03 variant C):

questions_filed (raw volume; anti-metric alone, denominator for the rest).
duplicate/attach rate = attaches / total asks (auto-exact + human-confirmed), plus per-canonical attachedCount.
interrupts/day = new canonicals routed to Tomas (attaches are not interrupts).
re-ask rate = questions matching an already-ANSWERED canonical / total asks.
time-to-unblock (median): file to resume, split by stamped vs poller.
answers-worth-persisting/week = write-backs drafted/merged (the sizing number for the expansion).
North Star = interrupts per merged work unit (denominator borrowed from work-ledger, plan 002), trended weekly against fleet volume.
search-before-ask compliance = fraction of asks preceded by a search_answers call.
Tomas out-of-band answer rate (champion canary; the leading churn signal, 09 §15).
Guardrails: false-positive merge count (human-audited, any nonzero triggers threshold review); revert/rework rate downstream of a self-served or auto-resolved answer; resume-success rate (zero-tolerance); passport-completeness % (100% by construction); stale-served count (defect, zero-tolerance); auto-resolve share of all resolutions (capped, weekly-audited).

18. Security

Threat model (10 §6):

Prompt injection via answers into agents. Answers come only from trusted humans (completion ACL). The real injection surface is legacy quotes in question text and LLM write-back drafts, not the human answer. Agents treat GLOSSARY.md and answers as data, never instructions; provenance stamps expose authorship. Test: an answer containing instruction-shaped text does not alter a reading agent’s behavior.
Poisoned write-back. Write-back is a review-gated PR, never auto-merge; drafts are marked “DRAFT, machine-written from answer ”; scope/expiry/confidence bound blast radius; git history makes every artifact revertible and attributable. Review checks fidelity (§16). Test: no diff merges without a human approval in the CODEOWNERS config (SEC-4).
Secrets/PII in question text. Regex denylist at ingest (DR-2), redaction window (DR-3), digest emits no bodies and skips sensitive items (DR-4), write-back hard-blocks on CUSTOMER_PII_OR_SECRETS (FR-21). Regex is imperfect, so classification defaults conservative.
Wrong dedup merge. Auto-merge only on exact normalized key; fuzzy suggests, a human confirms; bias to false-new (FR-7..10).
Cross-plane trust (SEC-2). Atlas reaches expose:false Core endpoints only through the same path workflow-proxy already uses (service-account bearer, platform network isolation). Never a direct shortcut. Confirm before go-live.
Confidentiality (SEC-3). No agent skill, prompt, or write-back path may surface content from reasons-and-decisions/; add a tested negative case.
Task-list visibility (SEC-1). Verify whether GET /tasks?assigneeGroupSlug= scopes visibility to the caller’s group or exposes any VIEWER-role employee to the full question text of any queue. This is a go/no-go gate before any real question is filed.

19. Legal and compliance

One line: Atlas is an internal, non-shippable tool for a two-human program; there is no external customer, contract, or data-processing agreement. The only compliance surface is that legacy question text may quote real customer data, handled by DR-2..DR-4 and the SEC-1/SEC-3 gates; the adjudicated precedent that “the bot said it” is not a defense (Air Canada, 2024 BCCRT 149) is the reason write-back and auto-answer stay human-gated (N4).

20. Operational requirements

OR-1. Atlas adds one internal-plane service, one Postgres database, two crons (reconcile, digest), one write-back worker, one secret (the interim GChat webhook URL, if used), one Claude Code skill. It changes zero files Tomas owns.
OR-2. Steady-state operational load: one database to back up, two crons to watch, one queue of write-back PRs for a human to approve.
OR-3. The write-back review queue is the one place Atlas could recreate the bottleneck it exists to kill (RA-4). It SHALL be measured in the first wave; if answers-worth-persisting is low (< 5/week DESIGN) the review is trivial; if high, review must be batched or sampled before scaling (pivot P-1, §26).
OR-4. No Grafana/SLO dashboards until the billing gate clears; until then, the weekly four-number readout (§17) is the operational instrument.
OR-5. Everything is reversible: delete the service, keep the git history; the corpus is the deliverable, not the app.

21. Dependencies

D1. Factory-lane grant (A1). Atlas needs the internal-plane factory lane with a CODEOWNERS partition (Robert’s lane). Fallback if not granted: the Robert-owned A-lite proxy repo (plan 001). Design does not change; only where the service lives does.
D2. Billing gate. Cloud infra is 0% provisioned behind a billing gate; v1 runs entirely on encore run. No design depends on cloud; Encore provisions the same DB/cron/secret from the same code later (NFR-4).
D3. Work-ledger sibling (plan 002). The North Star denominator (merged work units) is borrowed from work-ledger. Whether 002’s unit definition is stable enough to borrow before 002 finalizes is an open item (09 §18.5). Fallback: a provisional Atlas-local unit count, replaced when 002 lands.
D4. Fleet-monitor sibling (plan 004). The digest send belongs to fleet-monitor. If it is not live at wave time, use the interim webhook (FR-25).
D5. The core-plane asks to Tomas (corrected count: plan 001’s final position already sent ONE ask - the OWNERSHIP.md line plus directory convention; the earlier “three-ask” draft was reduced to this single ask by the architect addendum before anything went out. Atlas introduces up to three ADDITIONAL candidate asks on top of that baseline, to be bundled into ONE Tomas conversation, not sent piecemeal; this corrects 04 ADM-2’s “three asks” framing, whose error was the baseline, not the total):
- Baseline, already sent/covered: the agent-questions group and directory convention (config in user), and the internal-plane factory lane (A1) with CODEOWNERS partition.
- Additional candidate 1: grant Atlas a scoped service identity (member of agent-questions only, never ADMIN) to fan out / complete on tasks it did not originate (ADM-2, core-plane service identity for fan-out).
- Additional candidate 2, deferred, NOT asked in v1: write access into the shared _documentation/ pipeline. v1 avoids this by writing to docs/atlas/ instead (FR-19).
- Additional candidate 3: sign-off on the PII/write-back security gate (SEC-1/SEC-3, AC-8). Plus SEC-1 (task-list visibility) as a verification gate, not an ask.
D6. Custom MCP ask_human proxy (build on Robert’s side, not an ask to Tomas): subagents cannot call AskUserQuestion and background subagents auto-deny permission prompts (R3); even top-level AskUserQuestion has an open notification-hook bug (#59908). Zero-PR-to-Tomas does not mean zero build on the agent-harness side.

22. Constraints

C1. Zero PRs to Tomas’s core-plane code in v1. Non-negotiable. All new code is Atlas’s own internal-plane service plus config.
C2. No new human UI.
C3. Postgres-first, no new infra without MEASURED evidence (dedup is pg_trgm, not a vector DB; search is a Postgres query, not embeddings).
C4. Ask surface to Tomas is tight (§21 D5). Anything that adds a fifth ask must be justified against the four numbers, not assumed free.
C5. Deterministic core, LLM at the edges with provenance. The LLM appears only in write-back drafting (human-approved) and, post-MVP, dedup similarity assist. No LLM decides who to interrupt, what is a real duplicate, or what lands in a doc unreviewed.

23. Risks

Ordered by blast radius of a silent failure (09 §11, 10 §10), not by likelihood.

R1. Fan-out correctness (highest technical risk). One answer must resume every attached asker and no more. The attachment-signal mechanism (FR-14) is unproven at N>1 on this substrate (03 fan-out gap, 04 CP-5 ASSUMPTION). A bug re-routes duplicates to Tomas (defeating the product) or strands askers silently. Mitigation: the attachment list is the single source; reconcile idempotent on coreTaskId; a dedicated fan-out test; the “N completion calls” fallback if the signal path fails a spike. Prototype this FIRST, before any docs/glossary work.
R2. Write-back doc-rot / poisoning at machine speed (highest product risk, RA-2). Atlas’s flagship benefit (a trusted reusable corpus) and its worst failure (a poisoned corpus) are the same mechanism. One wrong doc collapses trust in all docs, not gracefully (R8). Mitigation: human-gated PR, provenance, scope, expiry, git-revertibility, never auto-merge.
R3. False-positive dedup merge (RA-3). A wrong merge feeds N agents a wrong answer silently and, if written back, poisons the corpus for all future askers. Mitigation: exact-key auto-attach only; human-confirmed fuzzy; bias to false-new; ADM-5 un-merge path; zero-tolerance false-merge guardrail.
R4. Review becomes the new bottleneck (RA-4). If write-back must be gated and there are two humans, review could recreate the bottleneck Atlas exists to kill. Bounded: only answers-worth-persisting need review; if that number is small, review is cheap; pivot to sampling if large (P-1).
R5. Champion dependency. With one answerer, if Tomas answers out-of-band because the queue is slower, no artifact is created and the loop silently reverts to status quo. A single point of failure, tracked as the out-of-band canary.
R6. Value risk (RA-1, the single riskiest). If the real duplicate rate is low, the flagship benefit does not exist. This is what the MVP measures first.
R7. Scope creep (RA-5). The “layer/platform” framing drags Atlas toward the dead status-product and hallucinating-wiki categories. Mitigation: the name is dropped; renderings stay quiet byproducts; non-goals N1-N9 are load-bearing.
R8. Sherlock precedent. The legacy Chat-triage gateway (Sherlock) was deliberately not ported (R1); Atlas re-proposes a spiritual descendant. Resolve with Tomas directly (why was it cut) before the announcement (08 flag 4).
R9. Cold-start misjudgment. Week-1 corpus is empty by construction; interrupts look like baseline until it has depth. Judge at week 4, not week 1.

24. Open questions

Does the fan-out/many-to-one signal-resume actually work as designed, or does it need plumbing beyond what R1 confirms? (spike, feeds R1) The most load-bearing unverified assumption in the whole concept.
Exact dedup threshold and false-merge rate on real questions (feeds §22, validation plan 14).
Does human/PR-gated write-back review scale or bottleneck (RA-4)? (measure in wave 1)
Does _documentation/ accept internal-plane writes without a Tomas-gated PR? If yes, FR-19 flips to 10’s free-search model.
Is work-ledger’s unit-of-output definition stable enough to borrow for the North Star denominator before 002 finalizes? (D3)
Should the digest exist at all for one reader, or is it below threshold even as a generated line? (delete at zero cost if Tomas ignores it)
SEC-1 task-list visibility scoping: go/no-go before any real question is filed.

25. MVP scope (the smallest credible loop)

The MVP tests the four riskiest assumptions (RA-1 value, RA-2 trust, RA-3 dedup safety, RA-4 review load), it does not miniaturize the vision. Structure: build the real loop end-to-end with deterministic exact-key dedup; wizard-of-oz the one component with no precedent (the fuzzy matcher) for wave 1 (07 §6).

IN (numbered cutline):

ask_question + search_answers internal-plane endpoints + a Claude Code skill, including the custom ask_human MCP proxy (D6).
Five-field question capture schema, validated Atlas-side (FR-4).
Deterministic exact-normalized-key dedup: auto-attach to open canonicals (FR-7), auto-resolve of exact identical-scope unexpired re-asks, logged and audited (FR-8).
Fuzzy/near-match handling by human confirmation only (Robert wizard-of-oz in wave 1); pg_trgm scores computed post-hoc for calibration, gating nothing (FR-9).
Mint one INFORMATION_REQUEST task per new canonical into agent-questions (FR-11), zero-PR.
Five-field answer via POST /tasks/:id/complete, inside the tasks UI if a frontend exists, else the curl/CLI/dictate fallback (FR-13, §12).
Atlas-owned fan-out: reconcile completed tasks, persist Answer, resume all attached askers (FR-14/15/16).
Human/PR-gated write-back to docs/atlas/ (GLOSSARY.md + decisions/), provenance-stamped, quotedDataClass gate (FR-17..21).
Capped digest rows into fleet-monitor’s digest, or interim webhook (FR-25).
The instrumentation counters (§17) and a weekly four-number readout.
Expiry-aware serving with the EXPIRED warning (FR-24); supersede-never-edit (FR-22/23).
SEC-1..4 gates cleared before the first real question.

OUT (explicit):

No portal, wiki, website, dashboard, or control room. No new human UI. (N1)
No embeddings / RAG / vector search. Grep + Postgres exact/trigram only; LightRAG deferred. (N5)
No LLM auto-answer with no human in the chain. (N4) No fuzzy auto-merge or fuzzy auto-resolve; only exact-key auto-attach and exact-key auto-resolve run automatically. (FR-9)
No org/team comms platform, no standalone status product, no second daily message. (N2, N3)
No SLA/escalation/reminders/backpressure/multi-team routing. (N9)
No writing to core-plane _documentation/ or to reasons-and-decisions/. (FR-19, N10)
No first-class MCP server (HTTP endpoints + skill only).
No auto-merge of anything a human has not confirmed at the fuzzy tier.

26. Post-MVP roadmap (3 stages, each gated on a measured number)

Stage 1: Automate fuzzy dedup. Gate: >= 30 to 50 Robert-judged near-duplicate pairs collected (spanning true and false), AND measured true-duplicate volume >= 5 pairs/week (DESIGN), AND a calibrated pg_trgm threshold with false-merge rate == 0 on the judged set. Then ship fuzzy-suggest (still human-confirmed on ANSWERED canonicals). If the volume gate is not met, the matcher is not worth automating and Robert’s manual read stays cheaper.
Stage 2: Upgrade retrieval. Gate: measured exact+trigram+grep search miss-rate > 30% (DESIGN) on the real corpus. Then adopt LightRAG (already running locally) as the search/dedup backend behind the same interface. Not before.
Stage 3: Broaden surface (second audience). Gate: a second real audience materializes (a second fleet, a second human answerer, or program handover). Then, and only then: negotiate the fourth ask to promote renderings into the shared _documentation/ pipeline; consider a first-class Atlas MCP server; consider auto-resolve on high-confidence non-exact duplicates only after dedup precision is MEASURED zero-false-merge over a defined volume. Until this gate, expanding the surface is building for a customer who does not exist.

27. Acceptance criteria for MVP

The loop demonstrably closes once, safely, on one real wave:

AC-1. An asking agent files a well-formed five-field question; a new canonical mints exactly one agent-questions task. (FR-1..5, 11)
AC-2. Two agents hitting the same exact-key ambiguity produce ONE task Tomas sees, attachedCount==2. (FR-7; RA-1 core)
AC-3. Tomas answers once; every attached asker resumes; resumed==attached is logged; a partial failure is visible and retryable. (FR-13..16)
AC-4. The answer produces one provenance-stamped, human-approved write-back diff under docs/atlas/; idempotent per canonical; sensitive answers hard-block auto-diff. (FR-17..21)
AC-5. A later agent’s search_answers hits that artifact before filing a new question (the activation event, loop closes once). (FR-2, CP-7)
AC-6. No fuzzy or near match is auto-merged or auto-resolved without a human; only exact-key auto-attach/auto-resolve run automatically, both logged. (FR-9)
AC-7. No answer is served past its expiry without the EXPIRED warning; passport completeness is 100% on served answers. (FR-24, NFR-7)
AC-8. SEC-1 (visibility scoping) verified, SEC-3 (no reasons-and-decisions/ leakage) tested, the secrets/PII regex gate blocks sensitive text from write-back and digest. (FR-21, DR-2..4)
AC-9. The four validation numbers plus North Star are instrumented and produce a weekly readout. (§17)
AC-10. Zero PRs merged into Tomas’s core-plane code (compliance metric).

28. Release strategy (1-week live wave)

One real fleet wave on the factory build lane (the beachhead, 09 §5), not a dry run. A real wave because EOL/dead-owner code (VIS ~2013, orders ~2017) generates genuine “is this alive / who owns this” volume, and because only a real wave tests whether Tomas keeps answering through the sanctioned queue once it costs him something.
Throttle the first rollout to a small cohort (04 ACT-3) so a naive-dedup v1 is not flooded before precision is known (DARK today).
Wizard-of-oz the fuzzy matcher: Robert reads every incoming agent-questions task, judges merge/no-merge by eye, records each judgment plus a post-hoc similarity score for calibration. Everything else runs live.
Measure the four numbers plus North Star; put the raw (un-deduped) task list next to the deduped queue Tomas actually saw at end of week (08 demonstration).

29. Launch (internal announcement)

Full copy in 08-made-to-stick.md. Binding constraints on the announcement:

It is an internal notice for two people and the fleet, not a product launch, and it says so.
Headline: “You will not be asked the same question twice.” Value prop: “Answer it once. It stays answered.”
Never use the phrase “intelligence and communication layer” (it overclaims against week-1 scope and fails its own Simple test, 08 §1).
Open with the falsifiable kill test, not a promise. Passport every number (all four core numbers are DARK until measured).
Resolve the Sherlock question with Tomas directly (why was the legacy Chat-triage gateway cut) BEFORE the announcement, or it surfaces as an objection instead of a design decision (08 flag 4, R8).
State plainly that “docs nobody maintains, that nobody distrusts” is a hypothesis the write-back contract is designed to test, not a fact (08 flag 2).

30. Success metrics (from 09)

North Star: human interrupts per merged work unit, trended weekly against fleet volume. Falling ratio while output holds is the loop compounding. Passport: DESIGN for any target until the wave produces a first MEASURED number.
Activation: the first time a second distinct asker is unblocked by an existing answer with no new interrupt (proof the loop closed once).
Time-to-value: wave start to first activation. Poor in week 1 is expected (cold start); poor by week 4 is a failure signal.
Engagement: search-before-ask compliance (agent side); Tomas’s in-sanctioned-UI answer rate (human side).
Quality: dedup precision (audited sample); zero stale-served events.
Trust: 100% passport completeness on served answers.
Reliability: 100% of completions resume every attached workflow.
Anti-metrics (never reported as success): questions filed, docs pages generated, glossary term count, digest length, merges by volume, corpus size/token count.

31. Pivot criteria (adjust, do not abandon)

P-1 (review bottleneck, RA-4): answers-worth-persisting > 20/week (DESIGN) or write-back review consuming measurable architect/operator hours, pivot to sampled/batched write-back review, not full review of every answer.
P-2 (fuzzy unsafe, RA-3): any confirmed false-merge on the fuzzy tier, pivot to exact-key-only dedup (drop fuzzy suggest) or tighten the threshold; keep human-confirmed. Never ship fuzzy auto-merge.
P-3 (search too weak): measured grep/exact/trigram miss-rate > 30% (DESIGN), pivot retrieval to pg_trgm-assisted then LightRAG (roadmap stage 2), not a bespoke index.
P-4 (champion drift): Tomas out-of-band answer rate rising, pivot to fixing queue latency/UX before adding any scope; the queue is losing to chat.
P-5 (digest ignored): if Tomas skims and ignores the digest line, delete it at zero cost; do not staff, design, or “improve” it.

32. Kill criteria (concrete numbers)

KILL / COLLAPSE to plan-001 bare triage if, after 2 live waves, ALL of the following hold:
- duplicate/attach rate < 15% (DESIGN), AND
- answers-worth-persisting < 5/week (DESIGN), AND
- re-ask rate not measurably falling (interrupts per unit flat vs wave 1). Action: remove the dedup brain, the write-back contract, and the digest rows; keep only INFORMATION_REQUEST + the agent-questions queue + Temporal resume (plan-001 v1, option 4 of doc 11). Glossary and digest were a human habit, not a product, which is the correct outcome, not a failure to hide.
HARD KILL of the whole loop if the North Star (interrupts per merged work unit) is flat or rising after 4 weeks with no MEASURED, fixable cause (the pre-agreed R2 falsifiable test). Action: revert to the status-quo GChat relay or bare triage; the loop is not compounding.
SAFETY KILL (any time): a confirmed corpus-poisoning incident (a wrong written-back answer trusted and acted on downstream) that the human-gate did not catch, OR a confirmed sensitive-data leak into a written-back artifact or the digest. Action: halt write-back, audit the gate, do not resume until the gate is fixed. These are zero-tolerance, not thresholds.

Appendix: conflicts decided in this PRD

Write-back destination (07 docs/atlas/ vs 10 _documentation/): v1 writes to docs/atlas/ (zero new ask to Tomas), accepting invisibility to Zaruba’s docs search until a fourth ask; verify item and post-MVP flip in FR-19 / OQ-4.
Digest ownership (07 feeds fleet-monitor vs 09/10 Atlas-owned cron): Atlas owns the render, fleet-monitor owns the send; interim self-send only if fleet-monitor is not live (FR-25).
Auto-resolve tier (01/07/10 permit exact auto-resolve vs 04 pushes all auto-resolve to EXPERIMENTAL): v1 auto-resolves only exact-key identical-scope unexpired re-asks, guarded/logged/audited; everything fuzzier is human-confirmed (FR-8/9).
Fan-out mechanism (10 attachment-signal vs 04 N-completion-calls): 10’s model is primary, 04’s is the documented fallback if a spike fails (FR-14, R1).
“Three asks” cap (04 flagged it understated): the honest count is four core-plane asks plus the SEC-1 gate (D5).
Decision-record target (08/04 stray reference to reasons-and-decisions/ vs 07/09/10 forbid it): Atlas never writes there; records go to docs/atlas/decisions/ (N10, FR-19).