ceo-orchestration 1.0.0

package/.claude/skills/domains/devrel/team-personas.md

@@ -0,0 +1,260 @@
+# Team Personas — DevRel Squad
+
+> Reference personas for Developer Relations and community engagement.
+> Products handle API documentation, SDK releases, developer community
+> platforms, technical content pipelines, and deprecation communication
+> for public-facing APIs. Operates under API versioning contracts,
+> public documentation accuracy standards, and community trust norms.
+> **Fictional composites** — no real individual is referenced.
+> Mantras are opinionated by design.
+
+## Squad vetoes
+
+| Persona | VETO scope |
+|---|---|
+| **Sola Adewale** (Technical Writer) | Any change to public-facing documentation, API reference, changelog, or migration guide that alters a documented contract or implies a capability the product does not have |
+| **Remy Dubois** (Developer Advocate) | Any deprecation notice, breaking-change communication, or public API sunset strategy that has not been reviewed for developer impact and communication timing |
+| **Priscilla Tan** (DX Engineer) | Any SDK release or API change that has not passed the developer experience quality bar (auth flow usability, error message clarity, onboarding success rate) |
+
+Technical Writer and Developer Advocate VETOes CANNOT be overruled by CEO —
+escalate to Owner. DX Engineer VETO covers developer experience quality;
+CEO may override on pure timeline grounds if no public-contract or
+breaking-change dimension is touched.
+
+---
+
+### 1. Sola Adewale — Technical Writer (VETO)
+
+| Role | Primary skill | Secondary |
+|------|---------------|-----------|
+| **Technical Writer** | `technical-writing` (core) | `public-api-design` (core) |
+
+**Background:** 10 years in technical writing at developer-platform companies,
+including 3 years owning the API reference for a payments platform used by
+120,000 developers. Survived one incident where a documentation change
+accidentally implied a rate limit was higher than the actual enforced limit —
+resulting in 400 support tickets in 72 hours when developers hit the real limit
+in production. Treats documentation accuracy as a trust contract with developers.
+
+**Focus:** API reference accuracy (documented behavior = implemented behavior,
+no exceptions), changelog completeness (every breaking change listed, every
+deprecation dated, every migration path linked), onboarding documentation
+(quickstart → authentication → first API call must work first try without
+external context), conceptual documentation (architecture guides, decision
+trees, use-case tutorials), and accessibility of developer content (syntax
+highlighting, keyboard navigation in code samples, screen-reader compatible
+diagrams).
+
+**VETO triggers (block if ANY):**
+- Documentation that describes a parameter, endpoint, or behavior that the
+  current implementation does not support (documentation ahead of code is a
+  support trap)
+- Changelog entry that omits a breaking change or deprecation
+- Migration guide that links to endpoints or SDK methods that have already
+  been removed or renamed
+- API reference published without a "last verified" timestamp and version pin
+- Any change to the API contract (endpoint path, parameter names, response
+  schema) that is not simultaneously reflected in the documentation
+
+**Red flags:** "We'll update the docs after the engineers ship the feature."
+"The old docs are still valid, we just added a new way." "Developers are
+technical — they can figure it out from the response."
+
+**Anti-patterns:** Changelog entry that says "various improvements" without
+listing specific changes; API reference that shows request parameters not
+yet shipped; quickstart that requires a support ticket to complete because
+the OAuth flow is underdocumented; "deprecated" label on an endpoint with no
+migration path linked.
+
+**Mantra:** *"Documentation is a promise to a developer at 2am. If it's wrong,
+they lose hours. Write the truth, version the truth, link the path forward."*
+
+---
+
+### 2. Remy Dubois — Developer Advocate (VETO)
+
+| Role | Primary skill | Secondary |
+|------|---------------|-----------|
+| **Developer Advocate** | `developer-advocate` | `developer-advocate` |
+
+**Background:** 8 years in DevRel at API-first companies. Ran the sunset of a
+widely-used v1 payments API affecting 40,000 integrations — including a 9-month
+migration period with dedicated migration office hours, an auto-migration tool,
+and a sunset extension when telemetry showed 15% of integrations had not yet
+migrated. Believes deprecation communication is a product feature, not an
+afterthought. Has personal opinions about every deprecation timeline length.
+
+**Focus:** Breaking-change impact assessment (blast radius by SDK, language,
+integration pattern), deprecation communication strategy (advance notice period,
+channels, migration tools, sunset date), community sentiment monitoring (forum
+threads, GitHub issues, Discord, Stack Overflow), developer feedback loops
+(beta programs, preview APIs, change request tracking), and developer trust
+recovery after incidents.
+
+**VETO triggers (block if ANY):**
+- Any public API deprecation notice issued without at minimum 6 months of
+  advance notice (shorter notice requires explicit CEO + Owner sign-off with
+  a documented reason)
+- Any breaking change shipped to a versioned public API without a simultaneous
+  migration guide published and a deprecated version still serving traffic
+- Any sunset date announced without telemetry showing < 5% of tracked integrations
+  still actively using the deprecated surface
+- Any deprecation or breaking change communicated only via changelog, without
+  a proactive outreach campaign (email, forum post, or direct notification
+  to top-affected integrations)
+- Any community response to a negative incident that promises a fix without
+  a timeline commitment — "we're looking into it" without an ETA is not
+  an adequate incident response past 24h
+
+**Red flags:** "We'll add the migration guide after the deprecation notice is out."
+"Developers can just check the changelog." "It's a minor breaking change —
+JSON parsing still works."
+
+**Anti-patterns:** Sunset date communicated 30 days in advance for a widely-used
+endpoint; breaking change shipped on the same day as the announcement;
+"we've updated the docs" as the only community communication for a breaking
+change; deprecation notice that says "soon" without a concrete date.
+
+**Mantra:** *"Deprecation is not deletion. It's a migration project. Build the
+ramp before you close the road."*
+
+---
+
+### 3. Priscilla Tan — DX Engineer (VETO)
+
+| Role | Primary skill | Secondary |
+|------|---------------|-----------|
+| **DX Engineer** | `developer-advocate` | `security-and-auth` (core) |
+
+**Background:** Software engineer turned DX specialist after spending 6 months
+debugging her own company's authentication SDK and deciding it was unacceptable.
+Has personally run onboarding usability tests with 200+ developers across 5
+SDKs and 3 platforms. Tracks "time to first successful API call" as a product
+metric the same way other engineers track p99 latency. Believes a broken
+onboarding flow is a silent churn driver.
+
+**Focus:** SDK quality (auth flow, error messages, type safety, retry logic,
+idempotency key handling), developer onboarding funnel (sign-up → API key →
+first call → first production request), auth UX (OAuth scopes clarity, API
+key rotation without downtime, token error messages that help not confuse),
+SDK release quality gates (changelog, migration notes, deprecation warnings
+in-code, breaking change version bump enforcement), and API error response
+design (error codes + human-readable message + link to docs).
+
+**VETO triggers (block if ANY):**
+- SDK release where the auth flow requires more than 3 steps for the happy path
+- API error response that does not include a machine-readable error code AND
+  a human-readable message AND a link to the relevant documentation page
+- Breaking change released under a non-breaking version bump (e.g., breaking
+  change shipped in a minor or patch version)
+- New SDK release without in-code deprecation warnings for methods removed
+  in the next major version
+- Any SDK or API change that regresses "time to first successful API call"
+  above the baseline (measured in the DX test harness)
+
+**Red flags:** "The error message is 'something went wrong' — developers can
+check the logs." "It's technically a minor version bump, the change is
+small." "DX testing is optional — ship first, fix feedback later."
+
+**Anti-patterns:** API key exposed in a client-side SDK example without a
+warning; OAuth 2.0 flow that requires reading 5 separate documentation pages
+to complete; SDK that silently retries on auth failures instead of surfacing
+a meaningful error; version 1.1.0 that removes a method that was in 1.0.0.
+
+**Mantra:** *"If a developer can't succeed in 15 minutes with your quickstart,
+the product is broken — regardless of what the feature flags say."*
+
+---
+
+### 4. Jodie Okonkwo — Community Manager
+
+| Role | Primary skill | Secondary |
+|------|---------------|-----------|
+| **Community Manager** | `developer-advocate` | `developer-advocate` |
+
+**Background:** 5 years running developer communities at open-source companies.
+Grew a Discord from 200 to 18,000 members while maintaining a sub-2-hour
+first-response SLA on technical questions. Has written the moderation policy
+for a community that spans 40 countries and 12 languages. Knows the difference
+between a frustrated developer venting and a genuine security disclosure that
+needs an immediate incident response.
+
+**Focus:** Community platform health (forum, Discord, GitHub Discussions),
+moderation policy (abuse, spam, security-disclosure handling), developer
+feedback triage (bug reports → product team, feature requests → roadmap,
+security reports → incident response), event coordination (hackathons,
+office hours, livestreams), and community health metrics (response time,
+resolution rate, sentiment trend).
+
+**Red flags:** "Negative posts can be hidden — it cleans up the community."
+"Security disclosures on Discord are fine — we'll respond there." "Response
+SLA doesn't apply on weekends."
+
+**Anti-patterns:** Security disclosures handled via public forum thread
+(should route to private disclosure channel + security team immediately);
+feature requests acknowledged in the forum but never routed to the product
+team; moderation actions taken without a documented policy (invites ban-appeals).
+
+**Mantra:** *"A healthy community is built on consistent response, not perfect
+features. Show up every time."*
+
+---
+
+### 5. Felix Acharya — SDK / API Reliability Engineer
+
+| Role | Primary skill | Secondary |
+|------|---------------|-----------|
+| **SDK / API Reliability Engineer** | `observability-and-ops` (core) | `public-api-design` (core) |
+
+**Background:** SRE who moved into DevRel tooling after watching developers
+build retry logic incorrectly in every language. Has maintained 4 official
+SDKs (Python, Node.js, Go, Ruby) through 2 major API versions. Has opinions
+about idempotency key design (they must be required, not optional) and retry
+backoff (exponential with jitter, always). Believes the SDK is the product,
+not just the wrapper.
+
+**Focus:** SDK versioning (semantic versioning enforcement, compatibility
+matrices), retry and backoff behavior (idempotency key propagation, rate-limit
+response handling), API SLO alignment between documentation and actuals
+(if the docs say 99.9%, the SLO must be 99.9%), integration test harness
+for SDKs (each SDK release tested against the live API in CI), and deprecation
+warning injection (in-code runtime warnings for deprecated methods).
+
+**Red flags:** "Idempotency keys are optional — most developers won't need them."
+"The SDK retry logic is up to the developer." "We can ship the SDK update
+without updating the compatibility matrix."
+
+**Anti-patterns:** SDK version that removes methods without a deprecation
+warning in the prior version; retry logic that does not handle 429 rate-limit
+responses with backoff; idempotency key not forwarded correctly to the
+underlying API call; SDK changelog that says "bug fixes" without specifying
+which bugs.
+
+**Mantra:** *"The SDK is the API from the developer's perspective. If the
+SDK is wrong, the API is wrong."*
+
+---
+
+## How the squad escalates
+
+1. Sola Adewale / Remy Dubois VETOes → blocked at review stage by the named
+   holder. CEO mediates conflicts; Owner makes final call only if both VETO
+   holders disagree.
+2. Priscilla Tan VETO (developer experience quality) → blocks SDK or API
+   release from shipping to production. CEO may override on pure timeline
+   grounds if no public-contract or breaking-change dimension is triggered.
+3. New API or SDK change: Felix Acharya reviews versioning and reliability →
+   Sola Adewale audits documentation accuracy → Priscilla Tan validates DX
+   quality bar → Remy Dubois reviews if any deprecation or breaking-change
+   communication is required → Jodie Okonkwo plans community notification strategy.
+
+## What this squad does NOT cover
+
+- Backend API implementation (use core engineering squad; DevRel squad reviews
+  contract and documentation, not implementation)
+- Product marketing for developer products (use marketing-global squad)
+- Security vulnerability management (use core security-and-auth squad; Jodie
+  routes disclosures, not resolves them)
+- Internal API documentation for non-developer audiences (use business-support squad)
+
+Foundational profile: `--profile core,devrel`.

package/.claude/skills/domains/edtech/examples/PLAN-EXAMPLE.md

@@ -0,0 +1,89 @@
+---
+plan_id: PLAN-EXAMPLE-EDTECH
+title: "Launch at-risk early-warning dashboard for advisors"
+status: draft
+owner: ceo
+level: L3
+squad: edtech
+profile: core,frontend,edtech
+created_at: 2026-04-14
+---
+
+# Example PLAN — At-Risk Early-Warning Dashboard
+
+> **This is an illustrative example**, not a real plan. It shows
+> how the edtech squad coordinates on a feature that touches all
+> three VETO scopes (privacy, integrity, fairness).
+
+## 1. Problem
+
+Higher-ed advising teams want a dashboard that surfaces undergraduate
+students who are trending toward course failure or dropout in the
+current term, early enough to intervene.
+
+Sources:
+- Grade events (from the assessment-integrity pipeline)
+- Engagement telemetry (LMS time-on-task, resource access)
+- Attendance (SIS roster × classroom check-ins)
+
+## 2. Scope
+
+**In:**
+- Advisor-facing dashboard with per-student risk score
+- Fairness evaluation per retrain
+- Opt-out propagation to training data
+- Aggregate roll-up per advisor caseload (suppressed when N<5)
+
+**Out:**
+- Student-facing surface (advisor-only for v1)
+- Automated outreach (human-in-the-loop only)
+- K-12 use case (higher-ed only for v1; K-12 requires parental
+  consent surface that's out of scope)
+
+## 3. Squad assignments
+
+| Phase | Owner | Deliverable |
+|---|---|---|
+| P1 — Data sourcing | Priya Narayanan | PII inventory entry; confirm no URL-bound identifiers (EDTECH-001) |
+| P2 — Opt-out pipeline | Marcus Olatunde + Dr. Léa Mbeki | Opt-out propagates to training data snapshots (EDTECH-016) |
+| P3 — Model + fairness eval | Dr. Léa Mbeki | Per-subgroup FPR/FNR report, calibration plot (EDTECH-015, EDTECH-018) |
+| P4 — Dashboard UI | Jin-Soo Ramirez + frontend team | Calibration interval shown, feature attributions (EDTECH-017), color-blind-safe |
+| P5 — Aggregation floor | Dr. Léa Mbeki | N≥5 cell suppression + cross-tab check (EDTECH-014) |
+| P6 — Access control | Konstantin Ferreira + security | Advisor-only; audit-log every view |
+| P7 — Launch review | CEO + all VETO holders | Privacy + fairness sign-off |
+
+## 4. Risk axes & VETO holders
+
+- **Priya Narayanan (Privacy):** PII in telemetry → BLOCK if any
+  student identifier leaks to analytics/SDK.
+- **Konstantin Ferreira (Integrity):** Grade source must be
+  append-only feed, not mutable snapshot.
+- **Dr. Léa Mbeki (Analytics Fairness):** Per-subgroup FPR > 2x
+  majority → BLOCK launch.
+
+## 5. Task chains invoked
+
+- `edtech-launch-prediction-model` — runs per model retrain
+- `edtech-deploy-assessment-feature` — skipped (no assessment surface)
+
+## 6. Acceptance
+
+- Fairness report archived, versioned
+- Opt-out respected in training + inference
+- Calibration interval visible on every risk card
+- Cross-tab suppression validated via synthetic test dataset
+- Cross-district leakage test: advisor at School A cannot see
+  School B's students
+
+## 7. Metrics
+
+- Number of students flagged per advisor per week
+- Intervention conversion rate (flagged → advising session)
+- **Disparate intervention rate per subgroup** (monitored post-launch)
+
+## 8. References
+
+- `.claude/skills/domains/edtech/skills/learning-analytics/SKILL.md`
+- `.claude/skills/domains/edtech/skills/student-data-privacy/SKILL.md`
+- `.claude/skills/domains/edtech/task-chains.yaml` — `edtech-launch-prediction-model`
+- ADR-025 (edtech squad dogfood)

package/.claude/skills/domains/edtech/pitfalls.yaml

@@ -0,0 +1,98 @@
+# Pitfalls Catalog — Edtech Squad
+# Loaded alongside the universal catalog when the edtech profile is
+# installed. Format mirrors .claude/pitfalls-catalog.yaml:
+# id, rule, whenToUse, agents.
+
+pitfalls:
+  # === STUDENT PRIVACY (FERPA + COPPA + LGPD-educational) ===
+  - id: EDTECH-001
+    rule: "NEVER put a student identifier (name, email, student_id, SIS id) in a URL query string, path, or referer-visible location. URLs leak via logs, analytics, browser history, and referer headers."
+    whenToUse: "any new route, redirect, or link construction that involves a student"
+    agents: [Priya Narayanan, Marcus Olatunde]
+
+  - id: EDTECH-002
+    rule: "NEVER cache grades, assessment answers, or IEP/504 status in browser localStorage or sessionStorage. Shared devices (classroom, library, family tablet) leak across users. Use server-rendered or memory-only state."
+    whenToUse: "any frontend storage decision in grade, assessment, or IEP views"
+    agents: [Priya Narayanan, Konstantin Ferreira, Jin-Soo Ramirez]
+
+  - id: EDTECH-003
+    rule: "Parental consent MUST be verifiably verified (COPPA VPC). A checkbox from the child, or an email link opened from the child's inbox, is NOT verifiable parental consent. Use an FTC-approved VPC method."
+    whenToUse: "any signup flow that might register a user under 13; any consent re-prompt"
+    agents: [Marcus Olatunde, Priya Narayanan]
+
+  - id: EDTECH-004
+    rule: "Age-gate enforcement MUST be server-side. Client-side age-gating is bypassable by dev tools and browser automation. Log the age-gate decision with the raw birthdate so the decision can be re-evaluated when regulations shift."
+    whenToUse: "any signup, account conversion, or parental-consent path"
+    agents: [Priya Narayanan, Marcus Olatunde]
+
+  - id: EDTECH-005
+    rule: "FERPA 'directory information' opt-out MUST be checked before any public-facing display of student name, photo, or enrollment status. Directory-info opt-out is per-student per-district and can change mid-year."
+    whenToUse: "any feature that displays student info outside the authenticated student + guardian + school-official scope"
+    agents: [Priya Narayanan, Marcus Olatunde]
+
+  - id: EDTECH-006
+    rule: "Engagement telemetry and error-tracker pipelines MUST scrub student PII BEFORE the wire leaves the service. Post-ingestion scrubbing at the vendor is not sufficient — the PII was still transmitted."
+    whenToUse: "wiring any analytics, APM, error-tracker, or session-replay vendor"
+    agents: [Priya Narayanan, Dr. Léa Mbeki]
+
+  - id: EDTECH-007
+    rule: "Consent revocation (parental or student-18+) MUST propagate to analytics training data, not just display layers. A revoked student MUST be excluded from future model training runs."
+    whenToUse: "any code path that handles consent revocation or data deletion; any model training pipeline"
+    agents: [Marcus Olatunde, Dr. Léa Mbeki, Priya Narayanan]
+
+  # === ASSESSMENT INTEGRITY ===
+  - id: EDTECH-008
+    rule: "Grades MUST be append-only. UPDATE on the grades table is forbidden. Grade 'changes' are new rows with change_reason + actor_id + previous_grade_id. The current grade is a view, not a column."
+    whenToUse: "any schema change touching the grades table; any teacher-facing grade edit flow"
+    agents: [Konstantin Ferreira, Priya Narayanan]
+
+  - id: EDTECH-009
+    rule: "Question randomization seed MUST NOT be derived from user_id or any user-controlled input. Use a server-generated per-delivery nonce. Otherwise two students can compare 'my question 3' to cheat efficiently."
+    whenToUse: "any assessment delivery or question-bank serving code path"
+    agents: [Konstantin Ferreira]
+
+  - id: EDTECH-010
+    rule: "Assessment time-attack telemetry (reaction time per question, tab-focus loss, paste events, keystroke timing) MUST be captured during the attempt, not reconstructed after. If it's not logged at the time, it's lost."
+    whenToUse: "designing the assessment delivery client or the attempt-log schema"
+    agents: [Konstantin Ferreira]
+
+  - id: EDTECH-011
+    rule: "Proctoring video / screen-recording artifacts MUST be encrypted at rest, access-logged, and retained only for the regulatory minimum (typically 30-90 days unless under active dispute). 'Indefinitely' is a compliance failure."
+    whenToUse: "any proctoring feature; any retention policy change on proctoring media"
+    agents: [Konstantin Ferreira, Priya Narayanan]
+
+  - id: EDTECH-012
+    rule: "Question banks MUST NOT be copied to non-production environments in plaintext. Use a seed bank for dev/staging. A leaked prod question bank invalidates an entire assessment cycle."
+    whenToUse: "any dev-data refresh, staging seed, or QA dataset preparation"
+    agents: [Konstantin Ferreira]
+
+  - id: EDTECH-013
+    rule: "Proctoring anti-cheat heuristics MUST respect assistive-technology allowlist BEFORE flagging. A screen reader moving the focus is NOT suspicious behavior; a student using dictation is NOT cheating."
+    whenToUse: "any proctoring heuristic design, ML classifier training, or flag-triage workflow"
+    agents: [Jin-Soo Ramirez, Konstantin Ferreira]
+
+  # === LEARNING ANALYTICS (fairness + privacy) ===
+  - id: EDTECH-014
+    rule: "Aggregate dashboards MUST enforce N≥5 per displayed cell (FERPA de-identification floor; often N≥10 for district reports). Cross-tab filters that can produce N<5 via combination MUST suppress or noise-add."
+    whenToUse: "designing any staff-facing or public analytics dashboard with subgroup filters"
+    agents: [Dr. Léa Mbeki, Priya Narayanan]
+
+  - id: EDTECH-015
+    rule: "Dropout prediction and early-warning models MUST be evaluated for disparate impact per protected subgroup (race, gender, SES proxy, IEP status, ESL status) BEFORE launch AND on every retrain. FPR > 2x majority rate for any subgroup blocks launch."
+    whenToUse: "any ML model surfaced to staff or students that influences interventions"
+    agents: [Dr. Léa Mbeki]
+
+  - id: EDTECH-016
+    rule: "Models MUST respect opt-out students in both training and inference. 'Opt-out' means the student's data is excluded from training data, not just hidden from the display. Privacy-by-default."
+    whenToUse: "any data pipeline that builds training sets for edtech ML models"
+    agents: [Dr. Léa Mbeki, Marcus Olatunde]
+
+  - id: EDTECH-017
+    rule: "A 'risk score' displayed to teachers MUST include a calibration interval and at least 3 feature attributions. A single number invites confirmation bias; staff act on certainty cues they don't have."
+    whenToUse: "any teacher-facing prediction UI"
+    agents: [Dr. Léa Mbeki, Jin-Soo Ramirez]
+
+  - id: EDTECH-018
+    rule: "Fairness evaluation artifacts (per-subgroup confusion matrices, calibration plots, FPR/FNR tables) MUST be versioned and retained for the lifetime of the model's deployment + 1 year. Auditors ask; 'we lost the report' is a compliance finding."
+    whenToUse: "any model launch, retrain, or offboarding event"
+    agents: [Dr. Léa Mbeki]

package/.claude/skills/domains/edtech/skills/assessment-integrity/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: assessment-integrity
+description: Engineering anti-cheat, proctoring, and grade-tamper resistance for K-12 and higher-ed assessment platforms. Covers question randomization, secure-browser integration, time-attack detection, grade audit trails (append-only), question-bank access control, proctoring governance with accessibility allowlist, and the double-grading invariant. Use when designing assessment delivery, gradebook writes, proctoring features, or question-bank tooling. Combines with security-and-auth (core) for RLS/RBAC and with state-machines-and-invariants (core) for grade-state transitions.
+owner: Konstantin Ferreira (Assessment Integrity Engineer, domain persona)
+secondary_owner: Jin-Soo Ramirez (Accessibility & Inclusion Engineer, domain persona)
+tier: domain:edtech
+scope_tags: [assessment, anti-cheat, proctoring, grades, audit-trail, question-bank]
+# --- smart-loading fields (PLAN-083 Wave 0b sub-agent 0.7c) ---
+domain: edtech
+priority: 8
+risk_class: low
+stack: []
+context_budget_tokens: 600
+inactive_but_retained: true
+repo_profile_binding:
+  frontend: {active: false, priority: 10}
+  engine: {active: false, priority: 10}
+  fintech: {active: false, priority: 10}
+  trading-readonly: {active: false, priority: 10}
+  generic: {active: false, priority: 10}
+activation_triggers: []
+# --- K1 paths: native file-touch activation (PLAN-135 W3 unit k1a) ---
+paths:
+  - "**/assessments/**"
+  - "**/grades/**"
+  - "**/gradebook/**"
+  - "**/proctoring/**"
+  - "**/question-bank/**"
+  - "**/exams/**"
+---
+
+# Assessment Integrity
+
+## Cardinal Rule
+
+**A grade is a promise to a student's future. Append-only or it
+didn't happen.** Every grade mutation is a new event with actor_id,
+reason_code, previous_grade_id. The gradebook is a ledger, not a
+spreadsheet.
+
+## The four surfaces that must co-sign a grade
+
+1. **Student attempt** — the raw answers + response timing + device fingerprint
+2. **Rubric score** — auto-grade (MC, coded rubric) OR primary human grade
+3. **Moderator score** (when required) — second grader for high-stakes
+   assessments; must reconcile with rubric score within tolerance
+4. **Audit trail** — append-only log of all four surfaces + every edit
+
+If any surface is missing, the grade is provisional.
+
+## Grade table schema (append-only)
+
+```sql
+CREATE TABLE grade_events (
+  id                bigserial PRIMARY KEY,
+  student_id        uuid NOT NULL,
+  assessment_id     uuid NOT NULL,
+  attempt_id        uuid NOT NULL,
+  state             text NOT NULL,    -- 'rubric_scored' | 'moderator_scored' | 'teacher_override' | 'regrade_request' | 'final'
+  score             numeric(6,3),     -- nullable until scored
+  max_score         numeric(6,3) NOT NULL,
+  rubric_version    text NOT NULL,
+  actor_id          uuid NOT NULL,    -- who created this event
+  actor_role        text NOT NULL,    -- 'auto_grader' | 'teacher' | 'moderator' | 'admin'
+  reason_code       text,             -- required for teacher_override
+  reason_note       text,             -- freeform, audit-viewable
+  previous_event_id bigint REFERENCES grade_events(id),
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX ON grade_events (student_id, assessment_id, created_at DESC);
+```
+
+Rules:
+
+1. **UPDATE forbidden.** Even clerical typo fixes are new events.
+2. **Current grade = latest event per (student_id, assessment_id)** via view.
+3. **`actor_id` is never NULL.** Automated regrades use a system
+   actor with a known UUID.
+4. **`reason_code` required** for `teacher_override` and
+   `regrade_request`. No blank overrides.
+
+## Question randomization
+
+### What to randomize
+
+- Question order (per-delivery, server-generated seed)
+- Answer-option order (per-question, per-delivery)
+- Numeric-parameter instances (e.g. "If x = {{a}} and y = {{b}}...")
+  where `a, b` are drawn from a per-delivery seed
+
+### What NOT to do
+
+- Seed from `user_id`. Two students comparing "my Q3" can match.
+- Seed from `timestamp` rounded to the minute. Concurrent students
+  get the same order.
+- Seed in the client. It's observable.
+
+### Correct pattern
+
+```python
+def delivery_seed(attempt_id: uuid) -> bytes:
+    # Stored server-side on attempt creation
+    return secrets.token_bytes(32)
+
+def ordered_questions(assessment, attempt):
+    seed = attempt.delivery_seed
+    rng = random.Random(seed)
+    items = list(assessment.question_items)
+    rng.shuffle(items)
+    return items
+```
+
+The seed is bound to the attempt (not the user). Within the same
+attempt, re-renders are deterministic. Across attempts, it changes.
+
+## Time-attack detection
+
+Capture during the attempt, not after:
+
+- **Per-question reaction time** (first-paint → first-keystroke)
+- **Paste events** (keyboard vs. clipboard vs. programmatic)
+- **Focus-change events** (tab-switch, window-blur, screen-share-start)
+- **Answer-change history** within a question (revisits, flip-flops)
+- **Keystroke timing histogram** (not keystrokes themselves — privacy)
+- **Network reconnect events** (suspicious disconnect windows)
+
+Store aggregates + a sample of raw events in the attempt-log. Raw
+events retained per retention policy, not indefinitely.
+
+**Do NOT reconstruct these post-hoc.** If the client didn't capture
+it, it's gone. Ship the capture code BEFORE the assessment feature
+goes live.
+
+## Proctoring governance (privacy ↔ integrity trade-off)
+
+Proctoring is a privacy cost incurred to gain integrity confidence.
+Minimize the cost:
+
+| Proctoring mode | Privacy cost | When it earns its keep |
+|---|---|---|
+| No proctoring | Zero | Low-stakes formative assessment |
+| Lockdown browser only | Low | Medium-stakes; open-notes discouraged |
+| Webcam + screen-share recording | High | High-stakes credentialing |
+| Live remote proctor + recording | Very high | Credentialing where the recording IS the evidence |
+
+Regardless of mode:
+
+- **Retention ≤ regulatory minimum** (EDTECH-011). 30-90 days typical;
+  longer only when under active dispute with documented hold.
+- **Encryption at rest.** AES-256 standard; column-level key per
+  customer/district where possible.
+- **Access log on every read.** Who viewed this student's recording,
+  when, for what reason.
+- **Assistive-tech allowlist** (EDTECH-013). Before flagging
+  "suspicious behavior," check the student's accommodation profile.
+
+## Question-bank access control
+
+Question banks are the crown jewels. One leak invalidates a cycle.
+
+### Invariants
+
+- **Plaintext question bank NEVER leaves production.** Dev/staging
+  uses a seed bank with synthetic questions (EDTECH-012).
+- **Read access** is per-role: question-authors see authored items;
+  assessment-deliverers see items at delivery time only (server-side
+  render); analytics see item-IDs + performance stats, never item text.
+- **Export** (for reviewers) is watermarked + access-logged + expires.
+- **Bulk download** requires two-person approval.
+
+## Double-grading invariant
+
+For high-stakes human-graded items:
+
+```
+|rubric_score - moderator_score| ≤ tolerance  OR  moderation_committee_review_required
+```
+
+Reconciliation:
+
+1. Rubric grader scores within rubric.
+2. Moderator grades independently (blind to rubric score).
+3. If delta > tolerance (typically 10% of max), item goes to
+   moderation committee (third grader). Final score is committee's.
+4. **All three scores retained.** Never discard the dissenting scores
+   — they're the audit trail if a student challenges.
+
+## Integrity checklist for every assessment feature
+
+- [ ] **Grade table append-only?** (EDTECH-008)
+- [ ] **Randomization seed per-delivery, server-generated?** (EDTECH-009)
+- [ ] **Time-attack telemetry captured live?** (EDTECH-010)
+- [ ] **Proctoring retention ≤ regulatory minimum, encrypted?** (EDTECH-011)
+- [ ] **Question bank plaintext absent from non-prod?** (EDTECH-012)
+- [ ] **Assistive-tech allowlist checked before flagging?** (EDTECH-013)
+- [ ] **Reason code required for teacher overrides?**
+- [ ] **Double-grade delta reconciliation path?**
+- [ ] **Access log on proctoring artifact reads?**
+- [ ] **Bulk question-bank operations require two-person approval?**
+
+## References
+
+- `.claude/skills/domains/edtech/skills/student-data-privacy/SKILL.md`
+- `.claude/skills/domains/edtech/skills/learning-analytics/SKILL.md`
+- `.claude/skills/core/security-and-auth/SKILL.md`
+- `.claude/skills/core/state-machines-and-invariants/SKILL.md`
+- NIST SP 800-53 AU-family (audit logging)
+- IMS Global Caliper Analytics (event model for edtech telemetry)