superdev-cli 0.1.0

package/skills/docs/assets/templates/module-inventory.md

@@ -0,0 +1,19 @@
+<!-- Template: module inventory. Every module folder is registered here or is an orphan. -->
+# {{project-name}} - Module Inventory
+
+- **Status:** generated projection of the `modules` table; the database is canonical and this file is rebuilt from it
+- **Last verified:** {{revision}} on {{date}}
+
+| Module | Purpose | Primary users | Owns | Status | Doc root |
+|---|---|---|---|---|---|
+| {{module}} | {{purpose}} | {{roles}} | {{data-and-surfaces}} | planned / in-progress / implemented / deprecated | {{path}} |
+
+## Status rules
+
+- `implemented` is derived, not asserted: it requires the module's features to be complete and their acceptance criteria to carry current verification evidence.
+- Deprecated modules keep their row and doc root; history is never deleted.
+- Editing this file does not change a module's status. Change it in the database, then regenerate; a manual edit here is detected and raised as a proposal.
+
+## Deliberate exclusions
+
+Folders under the modules root that are intentionally not modules (fixtures, archives): {{list-or-none}}

package/skills/docs/assets/templates/module.md

@@ -0,0 +1,50 @@
+<!-- Template: module specification. Built by the twenty-step decomposition loop;
+     every step filled or "N/A - reason". -->
+# Module: {{module-name}}
+
+- **Status:** draft | accepted
+- **Purpose:** {{one-sentence}}
+- **Primary users:** {{roles}}
+- **Owns:** {{entities-surfaces-processes}}
+- **Does not own (consumes):** {{consumed-from-other-modules}}
+- **Last verified:** {{revision}} on {{date}} against {{code-paths}}
+
+## Surfaces
+
+(per the pages/UI/actions template - link or inline)
+
+## API surface
+
+| Operation | Purpose | Doc |
+|---|---|---|
+| {{operation}} | {{purpose}} | {{link}} |
+
+## Data
+
+| Entity | Role in module | Doc |
+|---|---|---|
+| {{entity}} | {{owner/consumer}} | {{link}} |
+
+## Wiring (key actions end-to-end)
+
+| Action | Path |
+|---|---|
+| {{action}} | {{surface}} → {{handler}} → {{service}} → {{data}} → {{side-effects}} |
+
+## State machines
+
+{{list-with-links-or-deliberate-none}}
+
+## Events
+
+| Event | Direction | Payload owner | Consumers |
+|---|---|---|---|
+| {{event}} | emits / consumes | {{owner}} | {{consumers}} |
+
+## Edge cases
+
+{{category-walk-outcome-link}} - every category filled or `N/A - reason`
+
+## Remaining loop steps
+
+Telemetry: {{or-N/A}} · Accessibility: {{summary}} · i18n: {{or-N/A}} · Flags: {{or-N/A}} · Responsive: {{summary}} · Copy: {{link-or-inline}} · URL state: {{or-N/A}} · Performance: {{evidence-based-or-N/A}} · SEO: {{or-N/A}} · Compliance: {{declared-regimes-or-N/A}} · Test plan: {{link}}

package/skills/docs/assets/templates/nfr.md

@@ -0,0 +1,22 @@
+<!-- Template: non-functional requirements. Every number has a source: a measurement,
+     a platform limit, or an owner decision. Invented budgets are forbidden. -->
+# {{project-name}} - Non-Functional Requirements
+
+- **Status:** draft | accepted
+- **Last verified:** {{revision}} on {{date}}
+
+| # | Requirement | Target | Source (measurement / platform limit / decision) | Measured how | Current status |
+|---|---|---|---|---|---|
+| {{NFR-id}} | {{statement}} | {{target}} | {{evidence-or-adr}} | {{method}} | met / unmet / unmeasured |
+
+## Rules
+
+- A target without a source is a **question for the owner**, not a requirement - list it under Open below.
+- A requirement without a measurement method is a draft.
+- `unmeasured` is an honest status; fabricated compliance is drift.
+
+## Open (awaiting owner targets)
+
+| Area | Why it matters here | Proposed measurement |
+|---|---|---|
+| {{area}} | {{why}} | {{how-we-would-measure}} |

package/skills/docs/assets/templates/observability.md

@@ -0,0 +1,28 @@
+<!-- Template: observability. Vendor names only from evidence or decision. -->
+# {{module-or-project}} - Observability
+
+- **Status:** draft | accepted
+- **Tooling in use:** {{from-evidence-or-none-declared}}
+- **Last verified:** {{revision}} on {{date}}
+
+## Signals that prove it works
+
+| Capability | Signal (event/metric/log) | Where emitted |
+|---|---|---|
+| {{capability}} | {{signal}} | {{code-path}} |
+
+## Operator views
+
+| View/dashboard | Shows | Exists at |
+|---|---|---|
+| {{view}} | {{content}} | {{location-from-evidence}} |
+
+## Alerts
+
+| Condition | Threshold (evidence/decision) | Who is notified |
+|---|---|---|
+| {{condition}} | {{threshold-with-source}} | {{destination}} |
+
+## First-response pointers
+
+When {{failure-class}} → look at {{signal/view}} first.

package/skills/docs/assets/templates/pages-ui-actions.md

@@ -0,0 +1,47 @@
+<!-- Template: pages, UI surfaces, and complete action/state inventories. -->
+# {{module-name}} - Surfaces and Actions
+
+- **Status:** draft | accepted
+- **Last verified:** {{revision}} on {{date}} against {{code-paths}}
+
+## Pages/surfaces
+
+| Path/route | Surface | Purpose | Primary role | Key components | Entities shown |
+|---|---|---|---|---|---|
+| {{route}} | {{name}} | {{purpose}} | {{role}} | {{components}} | {{entities}} |
+
+## Action inventory ({{surface-name}})
+
+| Field | Value |
+|---|---|
+| Trigger | {{control-and-location}} |
+| Who | {{role}} - enforced at {{enforcement-point}} |
+| Precondition | {{state/visibility-conditions}} |
+| Effect | {{api-operation-or-local-effect}} |
+| Input/validation | {{fields-rules-limits}} |
+| Side effects | {{events-notifications-derived}} |
+| Confirmation | {{required?-copy}} |
+| Loading | {{behavior}} |
+| Disabled | {{conditions-and-affordance}} |
+| Success | {{feedback}} |
+| Empty | {{if-applicable}} |
+| Error | {{behavior-and-copy}} |
+| Offline | {{if-in-scope-else-N/A-deliberate}} |
+| Keyboard | {{reachability/shortcut}} |
+| Accessible name | {{name}} |
+| Focus behavior | {{after-complete/cancel}} |
+| Responsive | {{breakpoint-behavior}} |
+| Telemetry | {{only-if-approved-else-none}} |
+| Acceptance test | {{reference}} |
+
+## Role × action matrix
+
+| Action | {{role-1}} | {{role-2}} |
+|---|---|---|
+| {{action}} | ✓ / own / - | ✓ / own / - |
+
+Legend: `✓` full · `own` only own records · ` - ` blocked. Matrix must agree with the enforcement points above.
+
+## State completeness
+
+Every surface: empty / loading / error / success documented. Every action: disabled conditions documented. Undocumented states found in code are drift (`code-ahead-of-spec`).

package/skills/docs/assets/templates/project-summary.md

@@ -0,0 +1,44 @@
+<!-- Template: cited project summary. Written only on request (see summarize reference);
+     every load-bearing claim cites a source path and carries an epistemic label. -->
+# {{project-name}} - Project Summary
+
+- **Generated:** {{date}} against {{revision}}
+- **Method:** code-first read; claims labeled Confirmed / Inferred / Unknown; citations per claim
+
+## What it is
+
+{{one-paragraph}} ({{citation}})
+
+## Who uses it
+
+| Role | Goal | Evidence |
+|---|---|---|
+| {{role}} | {{goal}} | {{path}} |
+
+## What it does
+
+| Area/module | Capabilities | Evidence |
+|---|---|---|
+| {{area}} | {{capabilities}} | {{paths}} |
+
+## How it is built
+
+{{stack-from-evidence-with-citations}}
+
+## How it runs
+
+Entry points: {{paths}} · Environments: {{names-only-never-values}} ({{citations}})
+
+## State of the project
+
+Tests: {{summary+citation}} · Docs freshness: {{summary}} · Known drift: {{count-and-link}}
+
+## Docs vs code (drift found while summarizing)
+
+| Class | Code side | Doc side |
+|---|---|---|
+| {{drift-class}} | {{path}} | {{path}} |
+
+## Could not be established
+
+- {{unknown-item}} - {{what-would-resolve-it}}

package/skills/docs/assets/templates/roles-permissions.md

@@ -0,0 +1,26 @@
+<!-- Template: roles and permissions - the three nested matrices. -->
+# {{project-name}} - Roles and Permissions
+
+- **Status:** draft | accepted
+- **Permission source of truth (code):** {{declared-path}}
+- **Last verified:** {{revision}} on {{date}}
+
+## 1. Role × module visibility
+
+| Module | {{role-1}} | {{role-2}} |
+|---|---|---|
+| {{module}} | ✓ / - | ✓ / - |
+
+## 2. Role × action capability (per module - link module inventories)
+
+{{links-to-per-module-matrices}}
+
+## 3. Role × field sensitivity
+
+| Entity.field | Class | {{role-1}} | {{role-2}} |
+|---|---|---|---|
+| {{entity.field}} | personal/financial/secret | read / write / redacted / - | … |
+
+## Enforcement
+
+Every row names its enforcement point: {{middleware/policy/guard-paths}}. Matrix-vs-code disagreement is a P1 parity finding (validation category K).

package/skills/docs/assets/templates/test-plan.md

@@ -0,0 +1,23 @@
+<!-- Template: module test plan. Tooling names come from project evidence. -->
+# {{module-name}} - Test Plan
+
+- **Status:** draft | accepted
+- **Test tooling in use:** {{from-evidence}}
+- **Last verified:** {{revision}} on {{date}}
+
+## What must be true
+
+{{acceptance-criteria-rollup-from-features}}
+
+## Coverage map
+
+| Area | Level (unit/integration/e2e) | Cases | Status |
+|---|---|---|---|
+| Happy paths per feature | {{level}} | {{cases}} | exists / planned / missing |
+| Applicable edge-case categories | {{level}} | {{cases-per-category}} | … |
+| Permission boundaries (per matrix) | {{level}} | {{role×action-cases}} | … |
+| State machines (incl. illegal transitions) | {{level}} | {{transition-cases}} | … |
+
+## Evidence conventions
+
+Results live at {{where}}; a claim of "tested" cites a run. Tests claimed but absent is a P1 finding (validation category N).

package/skills/docs/assets/templates/workflow-state-machine.md

@@ -0,0 +1,43 @@
+<!-- Template: workflow and/or state machine. Use the sections that apply. -->
+# {{workflow-or-entity-name}}
+
+- **Status:** draft | accepted | implemented
+- **Module:** {{owning-module}}
+- **Last verified:** {{revision}} on {{date}} against {{code-paths}}
+
+## Workflow
+
+- **Purpose:** {{why}}
+- **Actors:** {{people-systems-jobs}}
+- **Trigger:** {{what-starts-it}}
+
+| Step | Owner | Action | On failure |
+|---|---|---|---|
+| {{n}} | {{actor}} | {{action}} | {{retry/compensate/park/abort}} |
+
+- **Completion:** {{criteria}}
+- **Observability:** {{how-progress-is-visible}}
+
+```mermaid
+sequenceDiagram
+  {{swimlane-if-multi-actor}}
+```
+
+## State machine
+
+| State | Meaning | Permits (UI/API) |
+|---|---|---|
+| {{state}} | {{meaning}} | {{allowed-actions}} |
+
+| From | Event | Guard | To | Actor |
+|---|---|---|---|---|
+| {{state}} | {{event}} | {{guard}} | {{state}} | {{who}} |
+
+- **Illegal transitions:** explicitly rejected at {{enforcement-point}} (documented-but-unenforced = drift)
+- **Terminal states:** {{list}}
+- **Timeouts/expiry:** {{time-driven-transitions}}
+
+```mermaid
+stateDiagram-v2
+  {{states-and-transitions}}
+```

package/skills/docs/references/adr-authoring.md

@@ -0,0 +1,24 @@
+# ADR Authoring (Docs-side)
+
+Docs owns the authoring quality of decision records; the decision skill owns conflict behavior and lifecycle enforcement. Template: `assets/templates/adr.md`; fields and statuses follow the shared project record (`${CLAUDE_PLUGIN_ROOT}/references/project-record.md`) §6.
+
+## Authoring rules
+
+- **Context before decision:** the problem, constraints, and evidence (with epistemic labels) come first; a reader must be able to disagree intelligently.
+- **Options considered is mandatory** - including the rejected ones with honest reasons; "we didn't consider alternatives" is itself the recorded truth when so.
+- **Observable rationale only:** criteria, tradeoffs, consequences, revisit triggers - never private reasoning.
+- **Consequences include the negative ones.** A decision with only upsides is under-analyzed.
+- **Enforcement points:** name where the decision is enforced (validator rule, review checklist, code location) - unenforced decisions drift.
+- **Revisit triggers:** concrete conditions that reopen the decision (evidence changes, scale thresholds, dependency EOL), not vague "revisit later".
+- **Declined and deferred are first-class:** record them with reasons and revisit conditions - "declined, not forgotten".
+
+## Supersession (authoring side)
+
+- New record lists `supersedes:`; the old record gains `superseded-by:` plus a dated banner explaining **why** - especially when superseded outside its own revisit triggers.
+- **Bodies are immutable.** The old record's text is history; only status, banner, and cross-references change.
+- **Partial supersession** names exactly which statements/scope fell and which stand, on both records.
+- Same-decision-different-places drift (log entry vs index row vs record status) is a validation finding; the record file is authoritative, indexes are regenerated.
+
+## Escalation rule
+
+Changes crossing a system-design seam (new datastore, tenancy model, external dependency, public contract, security model) require a decision record before implementation - this is step 6 of the change-tracking protocol.

package/skills/docs/references/apis-and-data.md

@@ -0,0 +1,23 @@
+# APIs and Data/Schema
+
+Universal structure lives in templates; style-specific sections come from fragments activated by evidence or decision - never defaults.
+
+## APIs (`assets/templates/api.md` + `assets/fragments/api/*`)
+
+Per operation, regardless of style: name/route/procedure · purpose · caller surfaces/actions · auth requirement + permission · request contract (fields, validation, limits) · response contract (success shape, error shapes with codes and user-facing meaning) · idempotency (key/semantics for anything retried) · rate/size limits (from evidence) · side effects (events, jobs, notifications) · versioning/compatibility expectations · test references.
+
+Style fragments add the style's specifics: REST (methods/status codes/resource shape), GraphQL (schema types/resolvers/authorization points), RPC (procedures/middleware), events (topics/payloads/delivery), local-only (in-process contracts).
+
+API docs map to real code: each operation names its implementing file(s). Unmapped operations are drift.
+
+## Data/schema (`assets/templates/data-schema.md` + `assets/fragments/data/*`)
+
+Per entity: purpose · owning module · fields (name, type, nullability, default, constraints) · relationships · lifecycle (created/updated/deleted by which operations) · sensitivity class (what is personal/secret/regulated under declared regimes) · retention (from decisions, not invented) · indexes/uniqueness from evidence · migration notes.
+
+Persistence fragments add style specifics: SQL-with-ORM (model↔table mapping, migration tool in use), SQL-without-ORM (DDL location, migration discipline), document (collection shape, denormalization rules), key-value (key schema, TTL), external SaaS (owned-by-vendor caveats, sync), no-persistence (explicit statement).
+
+## Shared rules
+
+- Schema docs cite the schema source files; prose never outranks the schema file (authority ladder).
+- Cross-module data access is documented on both sides (owner and consumer).
+- Breaking-change candidates (field removal/retype, contract change) trigger the API-contract / schema-migration change classes in `change-tracking.md`.

package/skills/docs/references/capability-fragments.md

@@ -0,0 +1,25 @@
+# Capability Fragments - Inventory and Activation Rules
+
+A fragment supplies the style-specific sections of universal templates. **Activation rule:** a fragment activates only when (a) detected from current code/configuration - with the evidence recorded - or (b) selected in an accepted decision. Never by default, never from genre expectations.
+
+## Layout
+
+One directory per capability axis under `assets/fragments/`, one file per style. Each fragment states its activation evidence patterns and the template sections it fills. `none.md` variants make absence an explicit, documentable state.
+
+## Inventory
+
+| Axis | Styles |
+|---|---|
+| `assets/fragments/api/` | rest · graphql · rpc · events · local-only |
+| `assets/fragments/data/` | sql-orm · sql-plain · document · key-value · external-saas · none |
+| `assets/fragments/async/` | queue · scheduler · event-bus · platform-jobs · none |
+| `assets/fragments/auth/` | neutral-base · detected-provider |
+| `assets/fragments/ui/` | web · mobile · desktop · cli · api-only |
+| `assets/fragments/env/` | envx · conventional · managed-platform · none |
+
+## Usage
+
+1. Determine the relevant axis from the operation (API doc → `api/`, entity doc → `data/`, …).
+2. Pick the style whose activation evidence is present, or the style an accepted decision selects; record which and why in the produced artifact.
+3. If no style's evidence exists and no decision selects one, use the `none.md` variant where the axis has one, or state the absence - never pick a plausible default.
+4. Fragment content fills the template's designated section; universal template text is never edited to embed style specifics.

package/skills/docs/references/change-tracking.md

@@ -0,0 +1,62 @@
+# Change Tracking, Impact, Sync, Drift, and Indexes
+
+Always on. Documentation catches up with accepted changes **before the next unrelated task begins**; the only alternative is a tracked deferral (a visible pending-sync entry), never silence. Completion claims with required sync missing are refused.
+
+## Contents
+1. The seven-step protocol
+2. Code-edit triggers
+3. Change classes → minimum artifacts
+4. Silent-edit exceptions
+5. Drift taxonomy and reporting
+6. Indexes
+7. Deferred engine boundary
+
+## 1. The seven-step protocol (every accepted mutation)
+
+1. **Identify** what changed (actual diff, not intention).
+2. **Classify** the change (table below).
+3. **Confirm** material sibling updates with the user before making them.
+4. **Rewrite** the affected current-state artifacts (mark drift where intent and code now disagree - never silently pick a side).
+5. **Record** the change: one coherent change entry (fields per the shared project record, `${CLAUDE_PLUGIN_ROOT}/references/project-record.md` §6).
+6. **Escalate to a decision record** when the change is architectural (crosses a system-design seam: new datastore, tenancy, external dependency, public contract, security model).
+7. **Re-verify:** links resolve; parity holds for touched specs; version/freshness markers updated.
+
+## 2. Code-edit triggers
+
+The profile's ownership map (index or adapter) maps code paths → owning artifacts. On any code edit - the agent's, the user's, or co-edits - walk the changed paths against the map. "No doc impact" is a valid outcome **only after walking the map**, never a default. Bulk refactors and migrations are walked once as a set, with one coherent change entry.
+
+## 3. Change classes → minimum affected artifacts
+
+| Class | Minimum artifacts |
+|---|---|
+| behavior addition | feature spec (accepted, right depth) · action/state inventory if UI · test plan · change entry |
+| behavior change | spec delta · affected inventories · change entry |
+| behavior removal | spec status update (removed, not erased) · inventories · change entry |
+| bug fix | change entry; spec/docs only if intended behavior or operations changed |
+| refactor | change entry; ownership map if paths moved |
+| dependency | decision record (or reminder of the declining decision) · stack slot · change entry |
+| schema/migration | data/schema doc · migration note · affected API docs · change entry |
+| API contract | API doc · consumers notified in docs · versioning note · change entry |
+| UI interaction | action/state inventory · acceptance tests · change entry |
+| security/privacy | roles/permissions matrices · compliance doc if regime-relevant · change entry |
+| operations | observability/runbook content · change entry |
+| documentation-only | change entry (docs are artifacts too) |
+| decision-only | decision record · decision index · change entry |
+
+## 4. Silent-edit exceptions (the only two)
+
+Typo fixes and user-facing copy corrections that change no meaning may be applied directly - and still appear in the next checkpoint's change entry. Everything else follows the protocol.
+
+## 5. Drift taxonomy and reporting
+
+`code-ahead-of-spec` · `spec-ahead-of-code` · `stale-current-state-prose` · `legitimate-historical-reference` · `missing-ownership` · `broken-cross-reference` · `unverified-assumption` · `implementation-defect` · `unknown`.
+
+Drift reports (template `assets/templates/change-impact-drift-report.md`) list each item with class, evidence (both sides), and the resolution owner (code, docs, or decision). Documentation drift is never reported as runtime failure, nor vice versa. Contradictions stay visible until resolved.
+
+## 6. Indexes
+
+Generated views (module inventory rollups, decision index, ownership rollups) are rebuildable, regeneration-marked, and never hand-edited. Update the affected index at the checkpoint; full rebuilds are the recovery path.
+
+## 7. Engine commands
+
+Durable writes go through the record engine: append the change entry with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/events.mjs" append --root <project> --event <file|-> --apply` (immutable, collision-safe, secret/reasoning-content rejected), map changed paths with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/ownership.mjs" match`, and regenerate views with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/index.mjs" rebuild --apply`. Generated views are never hand-edited - rebuild them.

package/skills/docs/references/diagrams.md

@@ -0,0 +1,31 @@
+# Diagram Catalogue
+
+Diagrams are contracts, not decoration: each has an owner artifact, stays in sync through change tracking, and a stale diagram is drift (validation category O). Use Mermaid unless the project already uses another convention (adapter declares it).
+
+## Project-wide (in architecture/foundations)
+
+| Diagram | Shows | When required |
+|---|---|---|
+| System context | Actors, the system, external dependencies | Always (even one box + actors) |
+| Container/deployment | Running pieces and their communication | More than one runtime piece |
+| Module map | Modules and their dependencies | More than one module |
+| Data-ownership map | Which module owns which entities | Shared persistence |
+| Auth flow | Session/token issuance and checks | Any authentication |
+| Critical-path sequence | The one flow the product exists for | Always |
+
+## Per-module / per-artifact
+
+| Diagram | Lives with | When |
+|---|---|---|
+| Navigation map | Module doc | Module has multiple surfaces |
+| Feature sequence | Feature spec (standard+) | Cross-component flows |
+| State machine | State-machine spec | Every lifecycle entity |
+| Workflow swimlane | Workflow spec | Multi-actor flows |
+| Job/webhook flow | Jobs spec | Async paths with failure branches |
+
+## Rules
+
+- Node names are the project's real names (routes, modules, entities) - never invented vendors or placeholder stacks; external dependencies appear only from evidence.
+- Every diagram carries a one-line caption stating what it claims; a diagram that cannot be captioned is decoration - cut it.
+- Diagrams participate in the change-tracking walk: a change touching a diagrammed path updates or explicitly defers the diagram.
+- Prefer several small accurate diagrams over one mural; a diagram nobody updates is worse than none.

package/skills/docs/references/discovery.md

@@ -0,0 +1,59 @@
+# Project Classification, Requirement Discovery, and Question Discipline
+
+## Contents
+1. Classify the project
+2. Discover requirements
+3. Question discipline
+4. Push-back catalogue
+5. Proactive suggestions
+
+## 1. Classify the project
+
+From evidence, never assumption: delivery shape (web / mobile / desktop / CLI / API-only / library), persistence style, API style, async needs, auth needs, environment handling, deployment shape. Each classification cites its evidence (file, config, dependency) and gets an epistemic label. Classifications feed **fragment activation** (`assets/fragments/`) - a capability fragment activates only from detected evidence or an accepted decision.
+
+## 2. Discover requirements
+
+Work section by section - product intent, users and roles, scope boundaries, core flows, data, integrations, quality attributes - and for each: state what the evidence already answers, then ask only what remains material. Requirements land as drafts with provenance; acceptance is explicit.
+
+## 3. Question discipline
+
+- One important question at a time; group only trivial factual selections.
+- Recommend first: every question carries a recommendation, why, and when not to take it (the question-packet format in the shared evidence contract).
+- Skip what evidence answers; never ask for facts visible in code, lockfiles, routers, or existing docs.
+- Ask only when the answer materially changes the deliverable; otherwise proceed with a declared assumption.
+
+## 4. Push-back catalogue
+
+Push back when an answer cannot drive implementation - require the missing dimension, propose a concrete default, and record the resolution:
+
+| Vague answer | Require |
+|---|---|
+| "secure" | threat model scope + data classes |
+| "real-time" | latency + consistency expectation |
+| "admin can manage X" | role boundary + exact capabilities |
+| "multi-tenant" | tenant axis + isolation level |
+| "scalable" | load assumption + growth horizon |
+| "AI-powered" | model responsibility, failure behavior, cost boundary |
+| "audit everything" | which events, retention, who reads them |
+| "works offline" | which operations, conflict resolution |
+| "fast" | budget with a measurement point, from evidence - never invented |
+
+Do not push back on every answer; push back when building on the answer as-is would produce rework.
+
+## 5. Proactive suggestions
+
+When a capability appears, volunteer its commonly forgotten neighbors - as questions, at capability level, never as vendor choices:
+
+| Trigger | Volunteer |
+|---|---|
+| authentication | session revocation, MFA policy, password reset, account lockout |
+| payments/billing | refunds, disputes, dunning, tax handling, webhooks idempotency |
+| file upload | size/type limits, virus scanning policy, storage lifecycle, access control |
+| search | empty results, indexing lag, permission filtering |
+| notifications | preferences, batching, quiet hours, delivery failure |
+| invitations/teams | expiry, re-invite, role at accept, member removal |
+| background jobs | retry policy, dead-letter handling, idempotency, monitoring |
+| i18n | date/number formats, RTL, translatable content ownership |
+| deletion | soft vs hard, cascades, export-before-delete, legal holds |
+
+Suggestions are offers; declined ones are recorded as declined-not-forgotten with a revisit condition.

package/skills/docs/references/edge-cases.md

@@ -0,0 +1,45 @@
+# Edge-Case Coverage
+
+Walk every applicable category for each feature or module. **No category is left silent:** each is either specified or marked `N/A - <deliberate reason>`. A category marked N/A without a reason is a validation finding.
+
+## Contents
+1. The categories (behavioral · operational · distribution · data integrity and lifecycle)
+2. Per-capability starter sets
+
+## The categories
+
+### Behavioral
+1. **Empty states** - no data yet, filtered-to-empty, first-run.
+2. **Boundary values** - zero, one, maximum, overflow, truncation, pagination edges.
+3. **Invalid input** - type, format, range, injection-shaped input at trust boundaries.
+4. **Permission boundaries** - each role attempting each action, including URL/API access without UI affordance.
+5. **State-machine violations** - actions attempted in wrong states; double-submits; replayed transitions.
+6. **Concurrent actions** - two actors editing/deleting the same entity; optimistic-lock behavior.
+7. **Ordering** - out-of-order arrival of events/webhooks/responses.
+8. **Duplication** - retried requests, duplicate submissions, idempotency expectations.
+
+### Operational
+9. **Network failure** - timeouts, partial failure mid-flow, retry behavior, user feedback.
+10. **Dependency failure** - downstream service down, degraded mode, circuit behavior.
+11. **Slow paths** - long-running operations, progress feedback, cancellation.
+12. **Time** - timezones, DST, clock skew, expiry boundaries, date rollover, leap cases.
+13. **Data migration states** - old-shape data encountered by new code and vice versa.
+14. **Recovery** - crash mid-operation; what is resumable, what is orphaned, cleanup.
+15. **Limits and quotas** - rate limits, storage limits, plan limits; behavior at and past the limit.
+
+### Distribution
+16. **Multi-device/session** - same account concurrently; stale-tab actions; session expiry mid-flow.
+17. **Offline/degraded** - if in scope: queued actions, conflict resolution, reconnect.
+18. **Localization** - long strings, RTL, unsupported locale fallback (if in scope).
+19. **Platform variance** - browser/OS/device classes in scope.
+20. **Versioning** - old clients against new APIs; deprecation windows.
+
+### Data integrity and lifecycle
+21. **Deletion semantics** - soft/hard, cascades, references to deleted entities, export-before-delete.
+22. **Consistency** - derived data staleness, cache invalidation, eventual-consistency visibility.
+23. **Privacy lifecycle** - data subject requests, retention, anonymization (declared regimes only).
+24. **Auditability** - who did what when, for actions that require it.
+
+## Per-capability starter sets
+
+When a capability is present, its typical hot spots (start here, then walk all categories): **auth** - expiry mid-flow, revoked session, role change mid-session · **payments** - webhook replay/ordering, partial refund, currency rounding · **upload** - oversize, wrong type, interrupted upload, orphaned blobs · **search** - empty, injection-shaped queries, permission filtering, index lag · **realtime** - reconnect gaps, missed events, ordering · **multi-tenant** - cross-tenant reference attempts, tenant deletion · **mobile** - backgrounding mid-flow, push permission denied, app-version skew against the API, deep-link cold start · **i18n** - long-string overflow, RTL layout, locale fallback, pluralization rules · **AI features** - model failure/timeout, unsafe output handling, cost runaway, nondeterminism in tests.

package/skills/docs/references/foundations-modules.md

@@ -0,0 +1,18 @@
+# Foundations and Module Inventory
+
+## Foundations (`assets/templates/foundations.md`)
+
+The accepted base every other artifact builds on. Sections: **product** (what it is, for whom, the problem, explicit non-goals) · **users and roles** (actors and their goals; role list feeds the permission matrices) · **scope** (in/out for the current horizon, with the out-list as discipline) · **architecture** (per `assets/templates/architecture.md`: system shape, boundaries, key flows, diagram inventory per `diagrams.md`) · **stack** (capability slots - delivery, persistence, API style, async, auth, environment - each filled by the active fragment with its evidence; no vendor appears without evidence or decision) · **design direction** (pointer to the project's design system if one exists; UI depth belongs to the ui skill) · **glossary** (project vocabulary; one meaning per term).
+
+Foundations claims carry epistemic labels; greenfield foundations are drafts until accepted; brownfield foundations are built via `reverse-engineer.md` with inferred claims marked.
+
+## Module inventory (`assets/templates/module-inventory.md`)
+
+The registry that makes module docs discoverable and orphans detectable:
+
+| Module | Purpose | Primary users | Owns (data/surfaces) | Status | Doc root |
+
+Rules:
+- Every module folder under the profile's modules root appears here; folders present but unregistered are **orphans** (validation reports them distinctly - they are either registered, archived, or deliberate exclusions listed in the adapter).
+- Status reflects reality: `planned` / `in-progress` / `implemented` / `deprecated`; `implemented` requires parity validation to have passed at least once.
+- Cross-module ownership disputes resolve here (one owner per entity/surface), during the reconciliation pass of `module-decomposition.md`.