superdev-cli 0.1.0

package/skills/init/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: init
+description: Start a Superdev project and run product discovery, or adopt a repository that already exists. Use for "set up superdev here", "I want to build X", "start a project", "initialize", "adopt this codebase", or when the orchestrator finds no project in the database. Detects new versus existing, inspects the repository before asking anything, checks provider readiness without installing, runs brainstorming and discovery, records sources and assumptions, walks the production-readiness checklist so no capability area is silently skipped, presents a high-level plan for acceptance, stores accepted content in the database, generates the Markdown projection, derives the first tasks, and opens the control center.
+---
+
+# Initialize or Adopt
+
+Initialization creates the container and the accepted plan. It does not create
+implementation work until a person has accepted the plan.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call. Full surface:
+`the plugin's skills/project/references/commands.md`.
+
+## Which path
+
+| Input | Command |
+|---|---|
+| An idea in a sentence, a Markdown brief, a folder of notes | `SD init` |
+| Empty or nearly empty repository | `SD init` |
+| Existing code, existing documentation, existing conventions | `SD adopt` |
+
+If both apply (a real codebase plus a brief for what comes next), adopt first,
+then run discovery for the new direction on top of what adoption found.
+
+## Order of operations
+
+1. **Inspect before asking.** Repository instructions, README, manifests,
+   routes, schemas, migrations, configuration, existing docs, tests. Every
+   question the repository already answers is a question you must not ask.
+2. **Check provider readiness.** `SD doctor`. It installs nothing. Report what
+   is ready and what is not before relying on it.
+3. **Run `SD init` or `SD adopt`.** This creates the database at
+   `.superdev/superdev.db`, adds `.superdev/` to `.gitignore`, opens a discovery
+   session, and records supplied material as immutable source records with
+   content hashes. Original notes are never rewritten.
+4. **Brainstorm with the provider.** Superpowers brainstorming shapes the
+   product when it is ready. If it is not, say so plainly, run the discovery
+   questions below, and do not present your own interview as that methodology.
+5. **Build the concept map**: users, problems, desired outcomes, possible
+   modules, capabilities, constraints, assumptions, unknowns, risks.
+6. **Walk the readiness checklist.** Below. Every applicable area gets an
+   answer or an explicit deferral.
+7. **Ask the smallest set of material questions.** Below.
+8. **Produce the high-level plan before any implementation task exists.**
+   `SD plan` assembles goals, milestones, modules and feature candidates from
+   what has been accepted so far.
+9. **Present the plan and the material decisions for acceptance.** Nothing is
+   stored as accepted until a person accepts it.
+10. **Store the accepted content**, then `SD docs generate` to render the
+    Markdown projection under `talks/`.
+11. **Derive tasks** from the accepted specifications with `SD derive`, and
+    present that plan for acceptance too. See the `task` skill.
+12. **Open the control center** with `SD ui`.
+
+## Production-readiness checklist
+
+Discovery evaluates each applicable area. Silent gaps are invalid.
+
+Product purpose and success criteria; users, roles, permissions and tenancy;
+frontend delivery shape; navigation and information architecture; design system
+and accessibility; backend boundaries; API style and public contracts;
+authentication and session lifecycle; authorization enforcement; database and
+data ownership; migrations and rollback; file or object storage; search and
+indexing; real-time behavior; offline behavior and conflict handling;
+background jobs and scheduling; events and webhooks; external integrations;
+notifications; rate limiting and abuse controls; security and privacy;
+compliance (only when explicitly declared); observability and operational
+response; performance and capacity targets; environments and secret management;
+CI and CD; infrastructure and deployment; backups, recovery, retention and
+deletion; product analytics (only when approved); testing strategy for the
+product; release and rollback.
+
+Each area ends as exactly one of:
+
+- **Applicable and specified.**
+- **Applicable and awaiting a decision** (it becomes an owner question).
+- **Not applicable, with a reason.**
+- **Deferred, with owner, revisit trigger and consequence.**
+
+"Not discussed" is not one of the four. An area nobody has looked at is an open
+question, not an absence.
+
+## Questions
+
+For each: plain language, why the answer matters, a recommended default, and an
+example when it helps.
+
+- Batch three to five related questions.
+- Ask one at a time for architecture, data, security, identity, billing, or
+  anything irreversible.
+- Accept "I do not know". Record the recommended default as a reversible
+  assumption with what would make it wrong.
+- Do not front-load every feature question. A feature's questions belong to the
+  moment that feature enters discovery.
+
+## Adopting an existing project
+
+- Existing documentation is never moved, rewritten, restructured or duplicated.
+  Adoption reads it and records what it found.
+- Adopt the repository's conventions rather than imposing new ones.
+- Label every inferred fact as inferred, with the file it came from. An
+  inference presented as a specification is a lie the project will inherit.
+- Where detection is genuinely ambiguous, ask rather than guess.
+- Reverse-engineering existing behavior into specifications is a Docs operation:
+  route to the `docs` skill for that, then store what is accepted.
+- Migrating an existing documentation system into the generated projection is a
+  separate decision, taken later and deliberately. Never create two editable
+  copies of one specification.
+
+## Verify before handing back
+
+- `SD db status` reports integrity, foreign keys and schema version cleanly.
+- `SD status` shows the project, the accepted plan and a next action.
+- `SD docs diff` is empty, or the pending proposals are explained.
+- `.superdev/` is git-ignored, and no per-record tracking file was created
+  anywhere in the repository.
+- Re-running `SD init` or `SD adopt` reports an existing project rather than
+  overwriting one.
+
+Then hand back to the `project` skill. Initialization creates the container and
+the plan; it does not build the product.
+
+## Boundaries
+
+- Writes stay under the project root and under `.superdev/` plus generated
+  `talks/` documentation.
+- No network installation happens here. Provider gaps are reported with their
+  remediation and consent is asked separately.
+- Never store secrets, personal data, private identifiers or absolute machine
+  paths in a record or a generated file.
+- A dirty worktree is preserved. Conflicts are surfaced, never forced past.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/project/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: project
+description: The Superdev entry point for anything about building or understanding a product. Use when someone describes something they want built ("I want to build X"), asks to plan or implement a feature, asks what the project does or why it works a certain way, asks for status ("what is done?", "what is blocked?"), wants the control center opened, or when it is unclear which Superdev skill applies. Clarifies intent, routes to init or adopt, runs discovery, keeps goals, milestones, modules, features, workflows, APIs, data, decisions and tasks in the project database, derives tasks from accepted specifications, enforces the find-or-create, link, claim sequence before any product-changing work, records activity and completes work with evidence, and routes specialist work to its provider.
+---
+
+# Superdev Project Orchestrator
+
+The single entry point. People describe what they want in ordinary language.
+You run the loop below, keep the database true, and route specialist work.
+Nobody should have to learn a command name or a provider name.
+
+`SD` below means:
+the installed `superdev` command, with `--root <project>` on every call.
+Full surface: `the plugin's skills/project/references/commands.md`.
+
+## What is authoritative
+
+One normalized database at `.superdev/superdev.db` holds the product definition
+and all execution state. Markdown under `talks/` is generated from it: a
+projection, never a second place to write. `.superdev/` is git-ignored.
+
+A manual edit to generated Markdown is never overwritten silently. It becomes a
+proposal that a human reviews, and accepting it updates the database first.
+
+## Writing style, always
+
+Never emit the em dash character (U+2014) and never emit emoji, in anything
+Superdev writes or stores: records, documentation, commit messages it drafts,
+interface copy, generated comments, summaries. Use a comma, colon, semicolon,
+parentheses or a hyphen. This binds text taken from a provider too, so rewrite
+it before storing it. Canonical writes are screened and refused with
+`E_STYLE_EM_DASH` or `E_STYLE_EMOJI`.
+
+## The loop
+
+Run in order. Skip a step only when it plainly does not apply, and say so.
+
+1. **Orient.** Read repository instructions, layout, manifests, routes, schemas,
+   git state. Never ask what the repository already answers.
+2. **Understand intent.** Build, plan, question, status, debug, review, docs,
+   decision, or an external action.
+3. **Check the project exists.** `SD status --json`. Nothing in the database
+   means new or unadopted, so go to **Starting a project**.
+4. **Check governing decisions.** `SD decision list --json`, then read the ones
+   touching this capability, its dependencies or its files. Surface a conflict
+   before proposing anything, never after.
+5. **Determine what is genuinely missing.** Only what changes the product.
+6. **Ask** per **Questions** below.
+7. **Update the model before building.** New or changed behavior is a
+   specification change first: feature, acceptance criteria, workflow steps,
+   surfaces and UI actions, API operations, data entities, migrations,
+   integrations, jobs, webhooks, permissions, NFRs. Route to the `feature`
+   skill for the interview and the depth choice.
+8. **Derive tasks** from the accepted specification, never from a feature title.
+   `SD derive <FEAT-id>`, then present the plan for acceptance. The feature is
+   positional: as a flag it is ignored and every accepted feature is derived.
+9. **Run the before-implementation sequence.** Below. It is not optional.
+10. **Implement** against the accepted specification: smallest sufficient
+    change, existing conventions preserved.
+11. **Verify for real.** Run the product's own required check and read its
+    output. Never claim a result you did not observe. Superdev itself has no
+    test suite, so never tell anyone to run tests for the plugin.
+12. **Complete with evidence.** Below.
+13. **Refresh.** The control center updates from the committed transaction and
+    waits for no Markdown rebuild. Run `SD docs generate` when accepted
+    specification content changed.
+14. **Report** the outcome and the single next action.
+
+## Starting a project
+
+| Situation | Route |
+|---|---|
+| Empty or new repository, an idea, a brief, or a folder of notes | `SD init`, through the `init` skill |
+| Existing code, existing docs, existing conventions | `SD adopt`, through the `init` skill |
+
+Discovery belongs to `init`. What this skill guarantees is that implementation
+does not start before there is an accepted plan: the high-level plan and the
+material decisions are presented and accepted, stored in the database, rendered
+to Markdown, and only then turned into tasks.
+
+## Before implementation
+
+Before any product-changing work, in this order (brief section 12.2):
+
+1. **Search for an existing task.** `SD task list --status ready --json`, or
+   `SD task show <TASK-id>` when the user named one.
+2. **If none exists, create a draft task.**
+   `SD task create --feature <FEAT-id> --name <t>`.
+3. **Link it to a feature.** Mandatory. A task with no feature is invalid and
+   the database refuses it.
+4. **Link it to a contract**: workflow step, UI action, API operation, data
+   entity, migration, integration, job, webhook, NFR, document or accepted
+   decision. Links are passed on creation: `SD task create --link <kind>:<id>`. If the work is
+   genuinely enabling, mark it so and name the feature it unblocks:
+   `--enabling --unblocks <FEAT-id>`. The refusals `E_TASK_WITHOUT_CONTRACT`
+   and `E_ENABLING_WITHOUT_TARGET` are the database telling you the work is not
+   yet understood.
+5. **If no feature exists, stop.** Create or update the feature specification
+   first, through the `feature` skill. Do not invent a feature to satisfy the
+   constraint.
+6. **Check governing decisions** for this capability, dependency or path. A
+   conflict routes to the `decision` skill before any code changes.
+7. **Claim it.** `SD task claim <TASK-id>` records developer, agent, branch and
+   session.
+8. **Move it to In Progress.** `SD task update <TASK-id> --status in_progress`.
+
+Lifecycle detail, categories, dependencies, subtasks and blocked work live in
+the `task` skill.
+
+## During implementation
+
+- Record meaningful activity at natural boundaries:
+  `SD task evidence <TASK-id> --summary "<what changed and why>"`. Every mutation
+  writes an activity event on its own, so do not narrate every file read or
+  shell command. The test is whether a human would want to read it.
+- Scope changed? Update the specification and the task before continuing. New
+  work must not live only in conversation or in the code.
+- Blocked? `SD task block <TASK-id> --reason <why>` immediately, not at the end.
+- Behavior outside the accepted scope needs the feature and its docs updated
+  first.
+
+## Completion
+
+Before completing a task:
+
+1. Run the product's required verification and observe the output.
+2. `SD task evidence <TASK-id> --summary <what was observed> --result <pass|fail|inconclusive> --reference <path or command>`, once per stated verification requirement, then `SD task complete <TASK-id>`.
+3. Update affected documentation with `SD docs generate`, then `SD docs diff` to
+   see whether anything on disk is now a pending proposal.
+4. Verify the related acceptance criteria are genuinely satisfied.
+5. Let dependent work reopen or proceed as the dependency graph says.
+6. The assignment releases on completion. Use `SD task release <TASK-id>` when
+   stepping away without finishing.
+7. Write the session outcome and the exact next action.
+
+Parent progress is derived, never asserted. No command marks a feature,
+milestone or goal complete. If a parent will not close, the open child work
+named in `SD status` is the answer.
+
+## Task derivation
+
+Tasks come from accepted specifications: acceptance criteria, workflow steps,
+surfaces and UI actions, API operations, data entities and migrations,
+integrations, jobs and webhooks, permissions, NFRs, observability, the product
+test plan, documentation synchronization, rollout and rollback.
+
+- Outcome sized, assignable, verifiable. Not one task per database row.
+- Combine what must change together; split what can be delivered or blocked
+  independently.
+- Each task states why it exists, what contract it implements, the expected
+  outcome, the boundaries it likely touches, completion criteria, verification
+  requirements, documentation impact and dependencies.
+- Present the derived plan for acceptance before implementing any of it.
+- A scope change updates the specification first, then regenerates a task delta.
+- Never rewrite completed tasks. Supersede or reopen them with history.
+- Product test work is derived from the accepted product test plan. Never create
+  a test task for the Superdev plugin itself.
+
+## Questions
+
+Ask only what changes the product. For each: plain language, why the answer
+matters, a recommended default, and an example when it helps. Accept "I do not
+know", propose the safe default, and record it as a reversible assumption.
+
+- Batch three to five related questions.
+- Ask one at a time for architecture, data, security, identity, billing, or
+  anything irreversible.
+- Never ask what you can safely infer from the repository.
+- Ask a feature's questions when that feature enters discovery, not up front.
+
+Owner questions are durable records. `SD question answer <Q-id> --answer
+<text>` closes one. Unanswered material questions appear in `SD status` and in
+the control center, so an open gap is never silent.
+
+## Providers
+
+Specialist work is routed outward. These are externally owned: orchestrate them,
+never reimplement, rename or approximate their methodology.
+
+| Need | Provider |
+|---|---|
+| Product brainstorming | Superpowers brainstorming |
+| High-level and implementation planning | Superpowers planning |
+| Product-code test discipline | Superpowers TDD |
+| Debugging | Superpowers systematic debugging |
+| Code review and finishing a branch | Superpowers review and finish workflows |
+| Frontend product direction | Frontend Design |
+| UI critique, accessibility and polish | Impeccable |
+| "Is there a skill for X?" | Find Skills and skills.sh |
+| Reusable methodology observations | Task Observer |
+| Secrets and environment stages | envx (names only, never values) |
+| Transitional recall, when installed | Claude Mem (a cache, never authority) |
+
+Rules:
+
+- Check readiness first with `SD doctor`. It installs nothing.
+- Never install without explicit consent to a named plan. No `--all`, no silent
+  `-y`, and strip those flags from any command you relay.
+- A provider that did not run is named as not run, with its remediation. Work
+  you did yourself is never presented as that provider's methodology.
+- Screen provider output before it enters the database: no secrets, no machine
+  paths, no em dash, no emoji, no private reasoning.
+- Superdev's own local memory is the durable project memory. Claude Mem may
+  supplement recall during the transition and never becomes project authority.
+
+## Control center
+
+`SD ui` opens the local control center and starts the service if it is not
+running. `SD services` lists what is running; `SD start`, `SD stop` and
+`SD restart` manage it. The interface reads only the local API and updates from
+committed transactions, so it cannot show anything the database does not say.
+
+Open it after initialization, after a derived task plan is accepted, and
+whenever someone asks to see where the project stands.
+
+## Harness honesty
+
+Correctness never depends on a lifecycle hook firing.
+
+- Claude Code runs the Superdev session hooks, which show the active task and
+  persist handoff state.
+- Codex hooks fire only after the user explicitly trusts them. Untrusted means
+  no lifecycle automation there.
+- skills.sh has no lifecycle-hook guarantee at all.
+
+Where hooks are not active, run the explicit commands: `SD resume` at session
+start, the before-implementation sequence by hand, and `SD status` before any
+handoff. Say which one you ran.
+
+## Routing to other skills
+
+| Intent | Skill |
+|---|---|
+| Set up a new project or adopt an existing one | `init` |
+| New or changed product behavior | `feature` |
+| Task lifecycle: claim, block, reopen, derive | `task` |
+| Where the project stands | `status` |
+| Continue after a break or compaction | `resume` |
+| Environment, providers, database health | `doctor` |
+| Inspect, record or supersede a decision | `decision` |
+| Something is failing | `debug` |
+| Review a change before it lands | `review` |
+| Documentation operation or template question | `docs` |
+
+## Boundaries
+
+- Completion is evidence, never assertion. If a gate refuses, report why; do not
+  route around it.
+- Never silently rewrite or delete a prior decision. Supersede it.
+- Never put secrets, personal data, absolute machine paths or private
+  identifiers into a record or a generated file.
+- Superdev is a development orchestrator, not a security sandbox. External,
+  destructive, publishing and installation actions need explicit confirmation on
+  top of the harness permission model.
+- The plugin has no test suite, by design. Products built with Superdev do get
+  tests, derived from their accepted product test plan.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/project/references/commands.md

@@ -0,0 +1,213 @@
+# Command surface
+
+One entry point. Users never have to type these; the skills invoke them and
+report the outcome in ordinary language.
+
+```
+superdev <command> --root <project> [options]
+```
+
+Always use that absolute plugin-root form. A bare relative path would resolve
+against whatever the current working directory happens to be.
+
+Conventions:
+
+- `--root <project>` names the project root. Every command accepts it.
+- `--json` gives machine-readable output for anything you need to parse.
+- `--apply` performs the change. Without it, every mutating command prints its
+  plan and changes nothing.
+- Exit `0` ok, `1` refused or findings present, `2` usage error.
+- Mutations are one database transaction and each writes an activity event.
+- **There is no per-command help.** `--help` is read before the command is
+  resolved, so `task list --help` prints the same global text as `--help`. This
+  file is the flag reference. If it disagrees with `src/cli.mjs`, the code wins
+  and this file is the bug.
+- `--actor <name>` records who is responsible for the change and lands in the
+  permanent activity trail. It defaults to `superdev`.
+- `--out <path>` writes this command's output to a file. It is global, not
+  specific to `export`, where it names the export file itself.
+- An unrecognised flag is not refused by name. Every flag outside a small
+  boolean set is parsed as taking a value, so `--bogus` alone exits 2 asking for
+  one, and `--bogus TASK-0001` swallows the id and the command then complains it
+  was given none. If a command reports a missing argument you are sure you
+  passed, suspect the flag before the argument.
+
+## Project lifecycle
+
+| Command | Purpose |
+|---|---|
+| `init [--idea <text>] [--brief <path>] [--name <text>] [--notes <text>]` | Detect new versus existing, run discovery, store accepted content, generate Markdown, derive tasks |
+| `adopt` | Bring Superdev into a repository that already has code or documentation, without restructuring what is there |
+| `plan [<FEAT-id>]` | The shape of the work: goals, milestones, modules, features, and what deriving would create. The optional feature narrows only the derivation preview, not the listing |
+| `status` | Project state: active work, progress with its counts, blockers, freshness, next action |
+| `readiness` | The production-readiness checklist, gap by gap |
+| `resume [--objective <text>]` | Reconstruct working context from the database after a break, a new session, or compaction |
+| `resume --end [--session <SES-id>] [--note <text>]` | Close the session and write its outcome. Without `--session` it ends the active one. `--note` applies only here |
+| `doctor` | Storage engine, database, migration history, integrity, documentation, alignment and freshness |
+
+`doctor` reports the storage engine, the project database and its
+documentation. It does **not** report provider readiness or harness coverage.
+Those come from a separate program:
+
+```
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor/doctor.mjs" inspect --root <project>
+```
+
+The `doctor` skill covers both and says which answers which.
+
+## Service and control center
+
+| Command | Purpose |
+|---|---|
+| `ui` | Open the local control center (starts the service if it is not running) |
+| `start` / `stop` / `restart` | Manage the one local service for this project |
+| `services` | List running Superdev services and their ports |
+
+The service is local only, reads through its own HTTP API, and never reads
+project files. The interface can show nothing the database does not say.
+
+## Database
+
+| Command | Purpose |
+|---|---|
+| `db status` | Schema version, pending migrations, integrity, drift and row counts |
+| `db migrate` | Apply ordered migrations (a backup is taken first) |
+| `db backup [--label <text>]` | Rolling local backup under `.superdev/` |
+| `db restore <file>` | Replace the database with a named backup |
+| `export [--out <path>]` | Portable JSONL snapshot under `.superdev/` |
+| `import <file>` | Load records from a verified export, inserting only what is absent |
+
+`db migrate`, `db restore` and `import` all refuse while the control center is
+running. The refusal names the command that frees the database.
+
+`.superdev/` is git-ignored in full. Writing an export into the repository
+happens only when the user explicitly asks for it.
+
+## Tasks
+
+| Command | Purpose |
+|---|---|
+| `task list [--status <s>] [--feature <FEAT-id>] [--limit <n>] [--all]` | Find work. Oldest first |
+| `task show <TASK-id>` | Full task: contract links, dependencies, subtasks, activity, evidence |
+| `task create --feature <FEAT-id> --name <text> ...` | New task. See the full flag set below |
+| `task update <TASK-id> [fields]` | Change scope or content. Cannot change status |
+| `task claim <TASK-id> [--developer <DEV-id>] [--agent <AGT-id>] [--branch <BR-id>] [--session <SES-id>]` | Assign to this developer, agent, branch and session |
+| `task start <TASK-id> [--note <text>] [--session <SES-id>]` | Move to In Progress |
+| `task release <TASK-id> [--reason <why>]` | Give up the assignment without closing the task |
+| `task block <TASK-id> --reason <why>` | Record a blocker immediately |
+| `task unblock <TASK-id> [--to <status>] [--note <text>]` | Put a blocked task back where it was |
+| `verify [--task <TASK-id>] [--limit <n>]` | Re-run the checks recorded evidence stands on |
+| `task evidence <TASK-id> --summary <what was observed> [--result <pass\|fail\|inconclusive>] [--type <kind>] [--reference <path>] [--criterion <AC-id>] [--command <re-runnable check>]` | Record what verifying it actually showed |
+| `task complete <TASK-id> [--note <text>]` | Close it, once its verification requirements have passing evidence |
+| `task cancel <TASK-id> --reason <why>` | Stop work that should not continue |
+| `task reopen <TASK-id> --reason <why> [--to <status>]` | Reopen with history preserved; never rewrite a completed task |
+| `derive [<FEAT-id>]` | Derive the task plan from accepted specifications. The feature is positional, not a flag |
+
+`task create` requires `--feature` and `--name`. Everything else is optional:
+`--description`, `--outcome`, `--why`, `--criterion`, `--verify`, `--boundary`,
+`--priority`, `--risk`, `--category`, `--estimate`, `--due`, `--parent`,
+`--dependsOn`, `--link`, `--status`, and for enabling work `--enabling` with
+`--enabledFeature` and `--rationale`. `--criterion`, `--verify`, `--boundary`,
+`--dependsOn` and `--link` may be repeated.
+
+`task update` accepts `--name`, `--description`, `--outcome`, `--why`,
+`--priority`, `--risk`, `--estimate`, `--due`, `--parent`, `--rationale`,
+`--enabledFeature`, `--criterion`, `--verify` and `--boundary`. It **refuses
+`--status`**: status moves through `task claim`, `task start`, `task block`,
+`task unblock`, `task complete` and `task reopen`, so every change leaves
+history.
+
+`task claim` flags take identifiers, not names. Passing a person's name gets a
+refusal naming what does not exist. Leaving them off lets Superdev resolve the
+identity itself, which is the normal case.
+
+`task complete` records no evidence of its own. Evidence is a
+`verification_evidence` record written by `task evidence`, and completion
+refuses until every verification requirement the task states carries its own
+passing one. So `task evidence` runs once per requirement, and a requirement
+that could not be run takes `--result inconclusive`: that records the attempt
+honestly and leaves the task open rather than closing it on silence.
+
+Passing evidence against an acceptance criterion is the only thing that ever
+marks that criterion met, and failing evidence takes it back to unmet.
+
+Pass `--command` whenever a command proved it. `superdev verify` re-runs every
+recorded command and marks the evidence stale when a check that used to pass
+stops passing, so a task completed months ago can notice the ground moved.
+Evidence with no command is not a failure: reading a screenshot or confirming a
+decision with the owner are real checks that no command reproduces, and
+inventing one to look rigorous is worse than saying the check is manual. A
+command that cannot run is reported separately from one that ran and failed,
+because a broken check says nothing about whether the product is correct.
+
+Statuses, as printed: Draft, Ready, In Progress, In Review, Verifying, Blocked,
+Paused, Complete, Cancelled, Superseded. Status history is append-only.
+
+Those are display labels. Every flag that takes a status wants the stored value,
+which is lower case with underscores: `in_progress`, not `In Progress`. Nothing
+normalises them and nothing refuses an unknown one, so a filter written in the
+printed form is not an error, it just quietly matches nothing.
+
+Refusal codes worth recognizing:
+
+- `E_TASK_WITHOUT_CONTRACT` - the task has no workflow step, UI action, API
+  operation, data entity, migration, integration, job, webhook, NFR, document or
+  decision behind it, and is not marked enabling.
+- `E_ENABLING_WITHOUT_TARGET` - enabling work that names no feature it unblocks.
+- `E_OPEN_SUBTASKS` - a parent cannot complete while required child work is open.
+- `E_VERSION_CONFLICT` - the record changed under you. Re-read and retry.
+- `E_DB_LOCKED` - another process holds the write lock. Retry; do not remove a
+  lock by hand.
+
+## Specifications
+
+| Command | Purpose |
+|---|---|
+| `feature depth [<FEAT-id>]` | Whether each feature carries what its declared depth promises |
+| `feature accept <FEAT-id>` | Accept a feature. Refused while its declared depth is unmet, naming everything missing at once |
+
+## Documentation
+
+| Command | Purpose |
+|---|---|
+| `docs generate [--only <path>] [--reports]` | Render accepted database content to Markdown under `talks/`. `--reports` adds the summary, status and drift reports |
+| `docs diff [<path>]` | Show manual edits to generated Markdown as pending proposals |
+| `docs accept <path>` | Apply a reviewed proposal to the database, then regenerate |
+| `docs reject <path>` | Discard the manual edit and write the generated version back |
+
+Every generated file opens with a marker carrying its source record, database
+revision, and body hash. An authored projection whose on-disk hash differs
+raises a proposal and is never silently overwritten. Derived views (changelog,
+status and drift reports) are always rewritten and carry a do-not-hand-edit
+banner.
+
+## Knowledge
+
+| Command | Purpose |
+|---|---|
+| `memory search <text> [--kind <k>] [--task <TASK-id>] [--feature <FEAT-id>] [--limit <n>]` | Session outcomes, facts, blockers, handoffs, with their links. The text is positional, or `--text` |
+| `question answer <Q-id> <text>` | Answer a durable owner question. The answer is positional, or `--answer` |
+| `decision record --title <t> --decision <what was decided> [--context <t>] [--rationale <t>] [--verification <t>] [--governs <type>:<id>] [--status <proposed\|accepted>]` | Record a decision |
+| `decision supersede <DEC-id> --title <t> --decision <t> [--partial --scopeDelta <what stops applying>]` | Replace a decision that no longer holds |
+| `decision list [--all]` | Decisions with status, scope and supersession chain |
+
+## Task categories
+
+| Command | Purpose |
+|---|---|
+| `category list` | Categories, what they mean, and how many tasks use each |
+| `category add <name> [--description <text>]` | Add a category of your own |
+| `category rename <CAT-id> <name> [--description <text>]` | Rename one |
+| `category describe <CAT-id> <text>` | Say what a category means in this project |
+| `category retire <CAT-id>` | Take it off the pickable list, keeping history |
+| `category restore <CAT-id>` | Put a retired one back |
+
+Memory is recall, not authority. Verify a recalled fact against the current
+specification, decision, code or evidence before acting on it.
+
+## What has no command, deliberately
+
+Nothing marks a feature, milestone or goal complete directly. Parent status and
+progress are derived from accepted contract components and completed child work.
+If a parent will not close, the answer is the open child work that `status`
+names, not a manual override.