← Design · c133
plan.md
c133 plan: Remediation Training (draft, before kick-off)
Gate: c137's bones (a training assignment is a message type; c130 D9 ruled 2026-11-09) and a brief in market-analyst (/brief). The problem is promoted: problem:enforcement-without-local-context (2026-11-09).
Reader: Mark; then the executor who mocks it in the lab; later c131 (the native side) and c134 (the web side).
Defaults: D1–D8 confirmed by Mark on 2026-11-09; D9 (blocking) added the same day.
Problem: problem:enforcement-without-local-context, promoted 2026-11-09 from the 1b21a3ce candidate (Mark Peterson, first-hand advisor; standing observed, advisor-labelled). Advisor and team judgement; no customer evidence yet.
Mark's note (2026-11-09): he has a background in creating training meant to keep people safe and secure; Metamythic is a past venture of his and is cited as prior art. Neither is referenced beyond this line.
Why
When qcontrol blocks or flags something, the person at the keyboard sees a disruption and nothing else. Mark Peterson asked for local feedback with a path to IT. Mark Parson's prompt goes one step further: the finding is a teaching moment, and we are the only party who sees both the violation and the person. A short training, taken at the moment and recorded in the audit log, turns a censure into a proof of correction. Hard-hat training is the register: short, concrete, about this hazard, with a check that it landed, and no shaming.
The shape
A training is four things:
| Part | What it is | Where it shows |
|---|---|---|
| Trigger | a finding, a policy's enforcement, a censure from HQ, or an assignment ("you are now responsible for…") | the native app's notice; a link from the web app |
| Lesson | one to three minutes: an illustration or animation, a few sentences, what to do instead | a page on the web app (default) or inline in the native app |
| Check | one to three questions that verify the concept, not recall | the same page |
| Record | completion written to the audit log, linked to the finding, visible to the operator and in Reports | the audit log, the finding's history, Reports (c128) |
A training is assigned by a policy (on this finding, require this training), by an operator (from a finding), or by HQ (a notice). A person can take one on their own from a library.
Rules
- R1. Short. A training fits in the time the disruption already cost. Three minutes is the ceiling.
- R2. About this hazard. The lesson names what happened on this machine, in the person's words, and what to do instead. No generic security awareness.
- R3. The check verifies understanding, not memory of the lesson's sentences.
- R4. The record is proof, not surveillance: completion, the check's result, and the finding it answers. Nothing about how long or how many tries, unless Mark rules otherwise.
- R5. A path to a person. Every training ends with how to reach IT or the policy's owner.
- R6. Respectful by default. The tone of a safety briefing, not a reprimand. Censures are HQ's words, trainings are ours.
Decisions (defaults)
| # | Question | Default |
|---|---|---|
| D1 | Where a training runs | the web app (control plane), opened from the native app's notice; inline in the native app later if the content model is small enough. |
| D2 | Who assigns | policies first (a training field on a policy, c121's model), operators second, HQ notices third. |
| D3 | The pass rule | all check questions right, retake allowed; the record keeps the final result only (R4). |
| D4 | Authoring | the design site is the studio: trainings as a markdown content collection with illustration and animation assets, previewed in the lab, published as data the apps read. |
| D5 | Delivery to the native app | as content modules fetched from the control plane, not baked into the binary (gpui-shell / nsh signed modules are the candidate mechanism, c130 Patterns). |
| D6 | Pilots | three, matched to the lab's top policies: secrets in prompts, personal accounts for work, unapproved MCP servers. |
| D7 | Video | out for the pilots; illustrations and short animations in (pixel pawns and the existing illustration briefs are the asset base). |
| D8 | The assignment | a c137 message of type training-assignment with a start-training action; completion goes back as training-completed. No channel of its own. |
| D9 | Blocking | a training can in theory block access (no model access until taken); by default it does not: completion is recorded, not enforced. Ruled 2026-11-09. |
| D10 | The record and who sees it (ruled 2026-11-11, review 1) | the person's name on the finding and in the audit log; counts only in Reports. The first question for Peterson: does a completed training count as personnel data in the organisations he knows? |
| D11 | Languages (ruled 2026-11-11, review 1) | English for the pilots; lang with one file per language when the authoring pipeline exists (Phase 3); operator text shown as written, never translated by us. |
| D12 | The exception's reason in the lesson (ruled 2026-11-11, review 1) | the operator's words, as written, shown to the person. |
| D13 | What the plane learns between assignment and record (ruled 2026-11-11, review 1) | nothing: Assigned, then Recorded. Confirmed as the product (c137 bones §5: a training assignment needs no acknowledgement, so not even seen). |
| D14 | The Finish step (ruled 2026-11-11, review 1) | kept: the person sees what will be written before it is. |
| D15 | The retake (ruled 2026-11-11, review 1) | keeps what was right: only the missed questions return, with the steps to reread. |
| D16 | The record's home (ruled 2026-11-11, review 1) | the finding's history row now; a Corrections block on the finding when Phase 2 agrees the event shape with Tyler. |
| D17 | Corrections in Reports (ruled 2026-11-11, review 2) | read as a state, as of the data cutoff, like Open now, with "in this window" beside Completed; counts only (D10). |
| D18 | Assigned on detection (ruled 2026-11-11, review 2) | every finding under a policy with a training counts as assigned (D2), so Waiting can read high on a team where nobody has taken it yet; that is the point of the section. |
| D19 | The Corrections block's place (ruled 2026-11-11, review 2) | under History on the finding, before Details. |
| D20 | The block as default (ruled 2026-11-11, review 2) | once Tyler agrees the event shape, the Corrections block is shown by default and the history row stays as the same event. |
| D21 | Publishing (ruled 2026-11-11, before Phase 3) | published trainings are served by the design site's API, /api/trainings and /api/trainings/<id>, like the brand API; the content collection is the source. |
| D22 | The record's store (assumed 2026-11-11, to validate with Tyler) | the plane's audit log: one row per completion; the finding reads it by finding id, Reports sum it; a table of its own only if a read needs it. |
| D23 | The event's contract (assumed 2026-11-11, to validate with Tyler) | the existing event pattern (qevents': a tagged enum, type and payload, dotted names) as the base; the event stays small; the plane's richer record object consumes it and adds the metadata. Which crate declares it is Tyler's to say. |
| D24 | Assignment and completion as audit rows (assumed 2026-11-11, to validate with Tyler) | both are audit log rows; a completion links to the finding that triggered it, and the plane associates it with the person's earlier findings under the same policy, to show the remediation and to drive what remediation comes next. |
| D25 | Every completion is a row (ruled 2026-11-11) | no de-duplication; one grouped object per completion (Mark's sketch: type training, completed, the training's id and name, proof of understanding true), never one row per action. Reports count a finding as answered once. |
| D26 | Version and hash (ruled 2026-11-11) | a published training carries its integer version and a hash of its published JSON; the record names both; the publish step computes the hash and the API serves both. |
| D27 | Separate events per assigner (ruled 2026-11-11) | a completion after a policy's, an operator's or HQ's assignment is its own event type, so the audit log reads who asked without opening the message (training.completed.policy, .operator, .hq proposed; the naming is Tyler's to adjust). |
| D28 | The right answers in the published data (ruled 2026-11-12, review 3–4) | kept: the web app grades the check (D3), so /api/trainings/<id> marks the right choice; a check of understanding, not an exam (R3). |
| D29 | How the apps get the trainings (ruled 2026-11-12) | the publish step's JSON is copied into the plane's repository at release; no live dependency on the design site behind Access. |
| D30 | A language with no file (ruled 2026-11-12) | the English file, with one line saying it is not yet in the person's language. |
| D31 | When the version moves (ruled 2026-11-12) | on a change of meaning (a step, a question, a right answer); a typo fix does not bump it, though the content hash moves with any change (authoring.md). |
| D32 | The operator's reason that names the person (ruled 2026-11-12) | shown as written (D12 kept), even in the third person about the reader. |
| D33 | The self-report in the accounts lesson (ruled 2026-11-12) | kept; the question goes to Peterson with the personnel-data question (D10). |
| D34 | The right answer's position (ruled 2026-11-12) | varied in the file: T-MCP-1's choices reordered, no change of meaning, so no new version; the hash moves. No shuffling at render. |
| D35 | The seed finding F-G (ruled 2026-11-12) | stays in the base world, both lab worlds; the integrations mock's count is 23. |
| D36 | Naming the detection gap (ruled 2026-11-12) | the secrets lesson names the check that is off, read from the policy's configuration. |
| D37 | Key rotation and the record (ruled 2026-11-12) | stays outside the record (R4); rotation is IT's to confirm. |
| D38 | Library words (ruled 2026-11-12, review 5, call 1) | each training file gets its own words for a reading with no finding, in place of the derived reading that drops the steps about a machine. This changes the parser, authoring.md, the /training skill and each file's content hash. The build proposes the form (a library: paragraph on the steps that need a finding, or a # Library section) and whether the version moves (D31). |
| D39 | The self-taken record (ruled 2026-11-12, call 2) | shown on the person's earlier findings under that policy ("taken on their own on |
| D40 | The self-taken event (ruled 2026-11-12, call 3) | training.completed.self; Tyler confirms it with D22–D27. Mark: a high count can show a strong posture, and we can offer trainings on areas that confuse people, categorized as self (clarifying question 6). |
| D41 | What a self-taken record names (ruled 2026-11-12, call 4) | the published training's version and content hash, with no second hash; under D38 the library words are in the file, so the hash covers them. |
| D42 | Self-taken completions in Reports (ruled 2026-11-12, call 5) | counted in Posture as a strength (counts only, no names, D10); not in Corrections, since they answer no finding (D39). |
| D43 | The contact line on its own (ruled 2026-11-12, call 6) | the library page's line, one for every training: "Questions about this training or the policy? Ask IT, or contact.library field. |
| D44 | The library's examples (ruled 2026-11-12, call 7) | the organisation's own facts are kept: the server an exception allows another team (Vanta MCP), the policy's first detector (an AWS access key). No one's finding is shown, so D10 holds. |
| D45 | The library words' form (ruled 2026-11-12, review 6, call 1) | a file's optional # Library section, entries replacing a step or question by id in its own grammar (authoring.md). |
| D46 | The version after library words (ruled 2026-11-12, call 2) | stays at 1 for all three; the content hashes moved (D31, D41). |
| D47 | Where self-taken trainings count (ruled 2026-11-12, call 3) | their own section in the Compliance report, beside Enforcement Posture; not in the Executive Summary. |
| D48 | A lab self-taken record's date (ruled 2026-11-12, call 4) | the world's clock, like every lab record. |
| D49 | Trainings on a topic (ruled 2026-11-12, call 5a) | a training answers a policy or a topic, exactly one. A topic training has no finding and no assignment sentence about one; it is written for anyone, and its record is training.completed.self (or .operator when sent) naming the topic. |
| D50 | The seed topics (ruled 2026-11-12, call 5b) | all 18 concepts the c125 guide explains (guide-knowledge.ts), operator terms included, not only the person-facing ones. |
| D51 | Who offers a topic training (ruled 2026-11-12, call 5c) | the library lists them; an operator can send one; the c127 guide can suggest one when a person asks about the same area twice (later). |
| D52 | A topic training's id (ruled 2026-11-12, review 7, call 1) | named for what it covers, in the T-<HAZARD>-<n> pattern (c137 E7): T-MODES-1, not T-TOPIC-<n>. |
| D53 | Concepts per topic training (ruled 2026-11-12, call 2) | a topic may cover several of the guide's concepts where one doesn't stand alone (Observe, Enforce and Off in one); the seed list (D50) is a list of trainings, not one per concept. |
| D54 | "A finding is a record, not a verdict" (ruled 2026-11-12, call 3) | kept in T-MODES-1's Observe step: the register R6 asks for. |
| D55 | Some policies can only record (ruled 2026-11-12, call 4) | the claim in T-MODES-1's Enforce step is kept, with its example; checked with Tyler beside D22–D27. |
| D56 | The operator's send of a topic training (ruled 2026-11-12, call 5) | c134's: a place in the operator's UI to pick a topic and a person; recorded in handoff.md § 7, not mocked here. |
| D57 | F-H in the base world (ruled 2026-11-13, review 8, call 1) | kept: the one row T-INJECT-1 answers outside the simulation, as F-G is for secrets; prompt inspection is on, so the finding is honest. |
| D58 | Slots keyed by policy (ruled 2026-11-13, review 8, call 2) | kept as the pattern: a policy whose finding kind is shared keys its slots in POLICY_SLOTS and its configuration-only slots in POLICY_CONFIG_SLOTS; no new resource kinds in the detector. Five policies use it. |
| D59 | "An approval" in T-INJECT-1 (ruled 2026-11-13, review 8, call 3) | stays general: the agent's own permission prompt. A later version may add a sentence where P-TOOL-APPROVAL is at Enforce for the reader's team. |
| D60 | Base-world findings for the simulation trainings (ruled 2026-11-13, review 9, call 1) | a seed finding where the policy is on and has none: F-I for P-TOOL-APPROVAL (Hana merges a pull request through GitHub MCP, approval set to never). P-PROVENANCE and P-SPEND stay simulation-only while they are Off in the lab world. |
| D61 | T-APPROVAL-1's title (ruled 2026-11-13, review 9, call 2) | "Ask before an agent sends or publishes": S1 and S3 send, S4 publishes. |
| D62 | Advice that names an agent's setting (ruled 2026-11-13, review 9, call 3) | general for now ("a maximum number of turns", "a fixed version"); named settings in a later version, filled from {agent} once each tool's are checked. |
| D63 | The simulation trainings in the native app (ruled 2026-11-13, review 9, call 4) | each is bundled with the native scenario that opens it, as T-INJECT-1 went with S1 (qnative 32c9b03). |
Phases
0. Brief
The problem is promoted (problem:enforcement-without-local-context, 2026-11-09). Write the brief in market-analyst (/brief), with Peterson's quote marked first-hand advisor and Mark's prompt marked internal; the brief's Source block names what it is not grounded in (no customer has said it yet).
1. Content model and one mock
The four-part model as data; one training mocked in the phase-4 lab from a real finding in the lab world, in the web app's frame. Review stop. Built 2026-11-11; the review stop ruled D10–D16 the same evening (review-1.md).
2. The record
How completion appears in the finding's history, the audit log and Reports (c128's Findings report). Agree the event shape with Tyler (an events type in qevents?). Built 2026-11-11 (event-shape.md, the Corrections section and block); review stop 2 ruled D17–D20 the same night; Tyler's answers to event-shape.md §6 outstanding.
3. The authoring pipeline
The content collection, the asset conventions, a preview page, the publish step (D21: the design API). A /training skill if the loop repeats. Handed to an execution session with Phase 4 on 2026-11-11.
4. Three pilots
D6's three, each with a lesson, a check and illustrations. Reviewed one at a time.
5. Hand-off
To c134 (the pages and the record) and c131 (the notice and the link). The library page in the web app.
Clarifying questions
Hard-hat training and Metamythic?Answered 2026-11-09: a note only (see the header).Does HR or legal sensitivity change the record (training completion is personnel data in some organizations)? Who can see it?Answered 2026-11-11 (D10): the name on the finding and in the audit log, counts only in Reports; the personnel-data question goes to Peterson first.Do trainings need languages other than English for the pilots?Answered 2026-11-11 (D11): English for the pilots;langper file with the authoring pipeline.Blocking?Answered 2026-11-09: in theory yes, by default no (D9).- Where the person's page lives (the reduced frame they see signed in through the plane connection, c131 D13): c134's call, not ruled here.
- Trainings on areas that confuse people, not on a finding (Mark, D40, 2026-11-12): taken on their own and recorded as
training.completed.self, a sign of a strong posture when the count is high. Today every training answers one policy (policyIdis required, one training per policy, D2), so a training on a topic needs the model to allow one without a policy, or with a topic in its place. Open: which topics, and who assigns or suggests them. Ruled 2026-11-12 (D49–D51): a training answers a policy or a topic; the seed topics are all 18 of the c125 guide's concepts; the library, an operator and later the guide offer them. Phase 7 builds the first, Observe and Enforce.
Patterns to consider
- The finding as the lesson's data. The lab world already has the finding, the policy, the person and the session; the lesson is generated from them, with a hand-written core per hazard.
- Signed content modules so trainings update without an app release.
- Reports (c128) gain a "corrections" line: findings answered by a completed training.
- The tour layer (c125) as the inline medium in the web app: a training is a short scripted tour with a check at the end.
- Pixel pawns (c47, c57) as the illustration cast, so every training looks like Qpoint without new art per lesson.