thoth-agents 0.4.2 → 0.5.1

package/skills/thoth-sdd/SKILL.md

@@ -1,130 +1,177 @@
 ---
 name: thoth-sdd
-description: Run thoth-agents Direct, Accelerated, or Full specification-driven development with Spec Kit-grade artifacts, OpenSpec-style durable deltas, fast-forward planning, and proportional independent verification.
+description: Apply proportional understanding and risk-aware SDD classification, with one ID-named record for substantial changes.
 license: MIT
-compatibility: Requires Node.js >=22.19 for bundled validation scripts.
+compatibility: Requires Node.js >=22.19 for bundled product validation.
 metadata:
   author: thoth-agents
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Thoth SDD
 
-Assess the work, recommend the lightest route that preserves correctness, and
-let the user select:
-
-- **Direct**: `implement -> verify`
-- **Accelerated**: `specify -> plan -> tasks -> implement -> verify -> archive`
-- **Full**: `explore -> specify -> plan -> tasks -> implement -> verify -> archive`
-
-Conditional phases are `clarify`, `checklist`, `plan-review`, and `converge`. Direct creates no
-SDD artifacts and may cover multiple documentation or mechanical files when the
-intent is clear and risk is low.
-
-Accelerated is a **fast-forward** route: root writes `spec.md`, `plan.md`, and
-`tasks.md` in one uninterrupted pass and creates optional artifacts only for a
-concrete risk. After `ready`, both artifact-backed routes offer
-`Review plan with Oracle (Recommended)` or `Proceed without review`. Full uses
-separate planning gates because uncertainty or failure cost justifies them.
-
-An explicitly named route counts as the user's selection. Otherwise assess and
-recommend Direct, Accelerated, or Full, first summarize the relevant request
-context, scope, clarity, risk, and why the recommendation fits, then ask. When a
-native route question returns answerless, make at most three total attempts;
-after the third answerless result, treat the recommended route as selected. Any
-explicit answer wins. A generic request to “use SDD” makes Accelerated the
-minimum recommendation but does not force it.
-
-At the post-`ready` review choice, an explicit answer wins, including
-`Proceed without review`. When the native question returns answerless, make at
-most three total attempts; after the third answerless result, treat
-`Review plan with Oracle (Recommended)` as selected. Once review is selected,
-repair actionable same-intent planning blockers, revalidate affected gates, and
-use a fresh Oracle for every new approval round until `[OKAY]`; stop instead on
-a material human-owned blocker.
-
-These bounded fallbacks apply only to the route, plan-review, and implementation
-questions. Never apply them to secrets, destructive or security-sensitive
-actions, or material human-owned product or architecture decisions.
-
-## Ownership
-
-- Root owns sequential coordination artifacts, gate execution, and archive.
-- Explorer owns Full-route repository discovery.
-- SDD routes govern artifacts and gates, not implementation ownership. Root,
-  `designer`, `quick`, or `deep` may implement in Direct, Accelerated, or Full.
-- Root decides ownership from explicit safe user direction and demonstrated net
-  gain. Delegation benefits include specialization, context isolation,
-  independent bounded work, quality, latency, or total cost; root continuity
-  benefits include short or sequential work, shared mutable state, accumulated
-  context, rediscovery, and coordination overhead. Route, file count, or cheaper
-  model price alone never selects an owner.
-- Only after deciding to delegate implementation, select `designer` for UI/UX,
-  `quick` for known narrow low-risk work, or `deep` for coupled, edge-case-heavy,
-  migration, concurrency, shared-contract, or high-risk work.
-- Each mutable surface has one writer; independent non-overlapping surfaces may
-  split, while coupled surfaces use one `deep` writer and ordered handoffs.
-- Oracle owns `plan-review` when review is explicitly selected or chosen by the
-  bounded recommended fallback. Every route requires
-  mandatory verification, but final-verification ownership is proportional:
-  trivial deterministic Direct work may be verified by Root when Root is not
-  self-approving its own implementation; materially risky Direct work and every
-  Accelerated or Full final verify require a fresh read-only Oracle. The
-  implementation writer never approves its own work.
-
-## Progressive loading
-
-Resolve `<skill-dir>` as the directory containing this `SKILL.md`, and resolve
-`<skills-root>` as its parent directory. Every bundled path below is anchored to
-one of those installed roots, never to the project or current working directory.
-
-Use only installed local contracts during the pipeline. Never invoke the
-thoth-agents CLI, `npx skills add`, or a network fetch to advance an SDD phase.
-If a required contract or external skill is missing, stop and report an
-incomplete installation instead of provisioning it mid-workflow.
-
-Read only the current phase contract:
-
-| Phase | Contract |
-| --- | --- |
-| explore | `<skill-dir>/references/phases/explore.md` |
-| specify | `<skill-dir>/references/phases/specify.md` |
-| clarify | `<skill-dir>/references/phases/clarify.md` |
-| plan | `<skill-dir>/references/phases/plan.md` |
-| checklist | `<skill-dir>/references/phases/checklist.md` |
-| tasks | `<skill-dir>/references/phases/tasks.md` |
-| plan-review | `<skills-root>/plan-reviewer/SKILL.md` |
-| implement | `<skill-dir>/references/phases/implement.md` |
-| verify | `<skill-dir>/references/phases/verify.md` |
-| converge | `<skill-dir>/references/phases/converge.md` |
-| archive | `<skills-root>/thoth-archive/SKILL.md` |
-
-## Validation gates
-
-Run the validator from its installed absolute path:
+Every change begins with three proportional reasoning steps, in order:
+
+1. **Explore** enough repository and user context to understand the current
+   behavior, constraints, and uncertainty.
+2. **Specify** the intended outcome, non-goals, and observable acceptance in
+   concise working notes.
+3. **Clarify** material uncertainty. Use evidence or a safe bounded assumption
+   when it preserves the user's intent; ask only when a material human-owned
+   decision cannot safely be inferred. An unresolved material decision blocks
+   classification and implementation.
+
+The root orchestrator owns completing these steps at a scale appropriate to the
+change; discovery ownership follows the root delegation policy. The sequence
+does not itself force a saved document, specialist-agent dispatch, or interview;
+the root delegation policy determines staffing. The understanding sequence is
+mandatory. Only after all three steps are complete does the orchestrator classify
+using scope, uncertainty, and risk. Scope or risk that increases during implementation
+reopens understanding and classification before further work. Never silently
+resolve material product, architecture, security, or destructive choices.
+
+## Proportional classification
+
+- **Small** means local impact, clear intent, and low risk. Local work may touch
+  several files within one area; file count alone never increases scope. Use
+  test-first implementation and focused verification; create no persistent
+  change record.
+- **Substantial** means coordinated impact across multiple areas, cross-cutting
+  contract changes, material uncertainty, or elevated failure/contract risk. A
+  small patch can still be substantial when its risk demands planning. Persist
+  one record, plan and validate before implementation, then independently
+  verify and archive.
+
+A user request cannot bypass the understanding sequence or material clarification.
+Do not auto-increment package versions. Use native harness lifecycle and status;
+never build a scheduler, state mirror, or process tooling.
+
+## Ownership and decisions
+
+Root owns user intent, scope, material decisions, classification, and final
+acceptance. Root also owns completing understanding, while the specific discovery
+ownership policy determines who gathers evidence; that policy takes precedence
+over generic permission for root to inspect directly. Choose an implementation
+owner from the actual task shape after classification, following
+specialist-default ownership and bounded direct-work exceptions.
+Root retains known low-risk mechanical work, including reviewed commits, without
+rediscovery.
+Explicit direct-work or no-delegation instructions win. Preserve operator-selected
+model and effort, including max. Keep one writer per mutable surface.
+
+Every orchestrator choice with a meaningful recommended action states that
+recommendation. Track confirmed answerless native returns separately per
+question: after the first and second, repeat the same question without starting
+dependent work; after the third, select the recommendation. Explicit answers win
+and explicit `Stop` always wins. Pending, unavailable, failed, interrupted, or
+host-prohibited attempts do not count. Report higher-priority host limits
+accurately; do not claim three returns or an explicit user choice when they did
+not occur. Never invent missing facts or secrets. When a human-owned choice
+remains unresolved, a safe deferral can be the recommendation and leaves the
+decision open.
+
+At substantial `ready`, first show the user a concise plan summary (goal,
+acceptance, key decisions, units, risks, record path), then always offer
+`Review plan with Oracle (Recommended)` or `Proceed without review`, even when implementation was already authorized.
+Silence is never an explicit review skip; run a fresh read-only review only when
+selected. After a selected `[OKAY]`, separately offer `Implement (Recommended)` /
+`Stop`; prior explicit authorization remains valid, while an explicit later
+`Stop` supersedes it. Record the plan-review selection as
+`EXPLICIT_REVIEW`, `EXPLICIT_SKIP`, or `DEFAULT_REVIEW_AFTER_3`; `SKIPPED`
+requires `EXPLICIT_SKIP`, and `OKAY` requires an explicit review or the third-
+return review default. A review result does not authorize implementation. Final
+verification is always required: small low-risk work can use focused root
+verification, while substantial or materially risky work requires a fresh
+independent Oracle. An implementation writer never approves its own work. If the
+user forbids delegation, perform authorized work directly but report unavailable
+independent review; never claim independent PASS or archive.
+
+## Bounded execution
+
+Apply these rules across all workflow stages. Each assignment names one
+independently acceptable outcome, exact known entrypoints and skill paths,
+concrete accepted inputs and dependencies, its produced result, owned writes and
+interface boundaries, focused checks with pass evidence, and a meaningful return
+milestone and stop condition. A task row names one outcome and may repeat an
+`AC-n` when useful; split phases with separately acceptable outcomes and keep
+tiny cohesive mechanical edits together. Independent, precise Explorer questions
+may run in parallel within native capacity; dependent questions wait until root
+accepts the named upstream output. Do not duplicate discovery. Missing inputs or
+interfaces, conflicting ownership, a new independent outcome, or material scope
+growth returns bounded progress to root for reassessment before expansion. Root reacts to
+native attention or a missed agreed milestone; a timeout is not a progress plan.
+After two consecutive attempts without new evidence or progress, return the
+smallest blocker rather than looping. Use native notifications/waits without
+polling or custom timers. Freeze relevant inputs before final validation, reuse fresh checks,
+and preserve substantive handoffs across late notifications. Load the
+[implementation phase](references/phases/implement.md) for the concrete procedure.
+
+## The sole substantial-change record
+
+After substantial classification, create only
+`.thoth/changes/<id>/<id>.md` from
+`<skill-dir>/templates/change.md`. Use a safe lowercase kebab-case ID; reject
+Windows-reserved names and unsafe path components. The record covers grounded
+exploration, intent, non-goals, acceptance, material clarifications and settled
+decisions, declared durable deltas, technical plan, tasks, authorization,
+verification, and closeout. The record is the only per-change artifact. Do not
+create sidecar specifications, plans, task lists, checklists, review or
+verification reports, evidence directories, worker reports, scripts, execution
+wrappers, or evidence generators, including temporary ones.
+
+A durable delta uses `- \`ADDED capability\` **Exact title** — Normative statement.`
+(or `MODIFIED`, `REMOVED`, `RENAMED capability FROM Previous title`). Every
+non-removal includes `  - GIVEN ...; WHEN ...; THEN ... .` Before review, verify
+the exact canonical baseline under `.thoth/specs/<capability>/spec.md`. In the
+same change record's Verification section, include exactly one reviewed source
+entry for every affected capability: the existing file's `sha256:<digest>` or
+`absent` if no canonical spec exists. `ADDED` may target either an existing or
+absent capability; other operations require an existing matching baseline. The
+validator checks each digest or reviewed absence at `verify` and `closeout`,
+not semantic quality.
+
+Archiving moves the same record to
+`.thoth/changes/archive/YYYY-MM-DD-<id>/<id>.md`; the date prefixes only the
+directory and never changes the record filename or identity. Preserve historical
+changes and fail closed on collisions or symlinked ancestors.
+
+## Progressive phase loading
+
+Resolve `<skill-dir>` as this SKILL.md's directory and `<skills-root>` as its
+parent. Read only the current phase under
+`<skill-dir>/references/phases/{explore,specify,clarify,plan,checklist,tasks,implement,verify,converge}.md`;
+plan review and archive are sibling skill contracts. Use installed local assets
+only; do not provision skills or run a network installer mid-workflow.
+
+## Gates and CLI
 
 ```text
-node "<skill-dir>/scripts/validate.mjs" --change openspec/changes/<feature> --route <accelerated|full> --through <specify|plan|tasks|checklist|ready|closeout> --json
+node "<skill-dir>/scripts/validate.mjs" --change .thoth/changes/<id> --through <explore|specify|clarify|plan|tasks|checklist|ready|verify|closeout> --json
 ```
 
-- **Accelerated**: `specify`, then `ready` after the fast-forward planning pass,
-  then `closeout` after independent verification and an archive report marked
-  `READY`.
-- **Full**: `specify`, `plan`, `tasks`, then `ready` before the optional review
-  choice or implementation, and `closeout` after independent verification.
-- **Checklist**: run only when activated; the later `ready` gate includes it if
-  present.
-
-`ready` validates the artifacts needed before the explicit or bounded-default
-`Review plan with Oracle (Recommended)` / `Proceed without review` choice.
-Review approval remains separate from implementation confirmation and never
-satisfies final verification.
-`closeout` additionally requires completed tasks, independent oracle PASS,
-complete FR/buildable-SC evidence, an observed PASS or explicit residual RISK
-for every outcome SC, and an archive report ready for the transactional archive
-transition.
-
-When implementation evidence refines the same intent, root updates the canonical
-artifact and revalidates only affected downstream artifacts/gates. A changed
-intent starts a new change. Structural validation prevents malformed artifacts;
-oracle still judges completeness, correctness, coherence, and evidence.
+The early gates validate the one record proportionally. `plan` validates without
+requiring tasks. `tasks` and `ready` require concrete coverage of every accepted
+outcome. `ready` requires settled material decisions before the mandatory
+plan-review offer or implementation authorization. Run `--through verify`
+before requesting final Oracle: it requires everything `ready` does plus complete
+tasks, review disposition and `**Plan review selection**` provenance,
+implementation authorization, and reviewed source digests/baselines. It permits
+final-review and Archive placeholders. `closeout` additionally requires a fresh
+independent Oracle PASS, every acceptance outcome with concrete PASS
+check/evidence, exactly one matching record SHA-256 field, and Archive READY.
+The initial `PENDING` selection placeholder is allowed before `verify` only.
+`SKIPPED` requires `EXPLICIT_SKIP`; `OKAY` requires `EXPLICIT_REVIEW` or
+`DEFAULT_REVIEW_AFTER_3`. Every canonical spec affected by a durable delta must
+have exactly one `Source` entry in the same record:
+`- Source: .thoth/specs/<capability>/spec.md | sha256:<digest>` when present, or
+`- Source: .thoth/specs/<capability>/spec.md | absent` when absent. Missing or
+stale coverage blocks `verify`, closeout, and archive. Calculate the record hash
+from exact UTF-8 bytes preceding the case-sensitive `## Authorization` heading.
+After PASS, edits confined to Authorization, Verification, or Closeout need no
+new review; any edit before `## Authorization` requires fresh independent review
+and a new digest. This allowance never waives structural checks, truthful
+provenance, stale-source rejection, or review of changed implementation.
+Structural validation is not human authorization or independent approval. Oracle
+examines the actual diff and checks, not just listed file digests.
+
+Archive with the installed sibling `thoth-archive` only after closeout passes.

package/skills/thoth-sdd/references/phases/checklist.md

@@ -1,23 +1,3 @@
-# Checklist contract
+# Checklist
 
-**Owner**: root<br>
-**Output**: `checklists/requirements.md`<br>
-**Activation**: high contract/failure risk, compliance sensitivity, or
-ambiguity-prone scope
-
-When activated, start from `<skill-dir>/templates/checklist.md`, where
-`<skill-dir>` is the directory containing the installed `thoth-sdd/SKILL.md`.
-
-Record the concrete activation reason. Use sequential `CHK###` items to audit
-the requirements—not implementation—across the base taxonomy: Completeness,
-Clarity, Consistency, Measurability, and Coverage.
-
-Add only applicable domain lenses, such as security, privacy, accessibility,
-compliance, performance, migration, or domain-specific failure rules. If none
-apply, record an evidence-backed `None` decision instead of boilerplate checks.
-Map every US, FR, SC, actor, failure mode, and relevant constraint to evidence.
-
-After clarification or planning changes, check affected revalidation items. If
-no requirement-affecting artifact changed, record an evidence-backed `Not
-required` no-op. Unresolved high-risk gaps return to specify; checklist status
-must never be inferred from code tests.
+Optional audit for risk or acceptance ambiguity after planning. Assess completeness, clarity, consistency, measurability, and relevant domain coverage in the sole substantial record. Correct gaps there and revalidate affected gates; never create a second checklist artifact. An unresolved material gap blocks implementation. Checklist is not a prerequisite to planning or tasks.

package/skills/thoth-sdd/references/phases/clarify.md

@@ -1,15 +1,17 @@
-# Clarify contract
+# Clarify
 
-**Owner**: root<br>
-**Activation**: material ambiguity only
+Required for every change, but often satisfied by recording that no material
+question remains. Use repository evidence or safe bounded assumptions for local
+technical details. Ask only when unresolved human-owned intent materially
+changes scope, behavior, architecture, security, or destructive impact; do not
+force an interview.
 
-Classify requirement dimensions as **Clear**, **Partial**, or **Missing** across
-scope, actors, data, interactions, non-functional constraints, failure behavior,
-and success evidence. Resolve from repository evidence or a safe documented
-assumption first. Ask one targeted human question only when the answer materially
-changes the result; Full SDD should normally ask no more than five high-impact
-questions in one clarification pass.
+When an orchestrator choice question has a meaningful recommended action, state
+it and follow the per-question retry rule in the [Thoth SDD entrypoint](../../SKILL.md):
+repeat after the first and second confirmed answerless returns without dependent
+work, then select the recommendation after the third. Pending, unavailable,
+failed, interrupted, and host-prohibited attempts do not count. Do not fabricate
+facts or secrets; a safe deferral may preserve a human-owned choice as unresolved.
 
-Write every accepted answer directly into `spec.md`, cite the changed FR/SC/story,
-then re-run structural validation and revalidate any existing requirements
-checklist. Do not create a parallel clarification document.
+Record the outcome in the one substantial record if one exists. An unresolved
+material decision blocks classification, planning, and implementation.

package/skills/thoth-sdd/references/phases/converge.md

@@ -1,14 +1,3 @@
-# Converge contract
+# Converge
 
-**Owner**: root<br>
-**Activation**: failed artifact-backed verification
-
-Classify every oracle gap as `missing`, `partial`, `contradicts`, or
-`unrequested`. Append one traceable remediation task per actionable gap to a new
-Convergence section in `tasks.md`, ordered by severity and linked to its finding,
-FR/buildable SC, exact writer surface, and verification outcome.
-
-Never rewrite, renumber, reorder, or delete earlier tasks, and never edit product
-code during convergence. If no actionable gap exists, leave `tasks.md`
-byte-for-byte unchanged. Return to implement, then always ask oracle to verify
-again.
+Optional after verification finds actionable defects. Root records only bounded remaining acceptance-linked work in the same substantial record; for small work, keep the in-session scope concise. Repair within settled intent, then repeat implementation and independent verification as warranted. If intent, scope, or risk materially changes, stop and reopen understanding and classification; do not widen silently. No convergence report.

package/skills/thoth-sdd/references/phases/explore.md

@@ -1,10 +1,5 @@
-# Explore contract
+# Explore
 
-**Owner**: explorer (read-only)<br>
-**Applies to**: Full
+Required for every change, proportional to its scope and uncertainty. Root owns completing understanding and accepting evidence; the specific discovery ownership policy decides who gathers local evidence and takes precedence over generic permission for root to inspect directly. Use a bounded known-source question only where that policy permits it, and return before another unlocated discovery path. Do not repeat accepted discovery.
 
-Resolve only repository uncertainty that affects requirements or design. Inspect
-the smallest useful anchors and return relevant paths/symbols, confirmed current
-behavior, constraints, safe assumptions, unresolved human-owned decisions, and
-recommended specification anchors. Do not write files or return raw logs. Stop
-when root can specify without repeating discovery.
+When evidence gathering is assigned, give each unit one precise question and one bounded result. Independent, precise Explorer questions can run in parallel within native capacity; dependent questions wait until root accepts the producer's concrete output. Return useful partial evidence at the agreed milestone, and stop before classification if a material human-owned decision cannot be safely inferred. No agent, document, report, or evidence directory is forced.

package/skills/thoth-sdd/references/phases/implement.md

@@ -1,57 +1,58 @@
-# Implement contract
-
-**Owner**: adaptive root, `designer`, `quick`, or `deep` in every route; exactly
-one writer per mutable surface
-
-SDD routes govern artifacts and gates, not implementation ownership. Before
-implementation or dispatch, root records the decided owner, task-shape/net-gain
-rationale, exact paths, accepted FR/buildable-SC scope, non-goals, and
-verification commands. Route, file count, or cheaper model price alone is not an
-ownership rationale.
-
-Root may retain implementation when short or sequential work, shared mutable
-state, accumulated context, rediscovery, or coordination overhead outweighs
-delegation benefit. Delegate when specialization, context isolation, independent
-bounded work, quality, latency, or total cost creates demonstrated net gain. If
-root owns the surface, do not dispatch a writer. If a specialist owns it, send a
-bounded handoff with the exact surface, requirements, and checks.
-
-Root marks selected artifact-backed tasks `[~]`; Direct or no-artifact work has
-no task state. Use the mandatory `tdd` skill for behavior changes and work in
-vertical red/green slices. Child writers never edit task state; root marks `[x]`
-only after checking task-specific evidence.
-
-After deciding delegation creates net gain, select deterministically:
-
-- `designer` for user-facing UI/UX, interaction, accessibility, responsive, or
-  visual-quality work;
-- `quick` for a known narrow mechanical low-risk surface with exact targets;
-- `deep` for coupled multi-file, shared-contract, migration, concurrency,
-  edge-case-heavy, or high-risk work.
-
-Proven independent surfaces may use different writers only with non-overlapping
-ownership. Overlapping or compatibility-coupled work uses one `deep` writer and
-ordered handoffs. A writer escalates before expanding beyond its routing
-boundary. Every route requires mandatory verification, and the implementation
-writer never approves its own work. For trivial deterministic Direct work, Root
-may run the proportionate focused checks when Root is not self-approving its own
-implementation. For materially risky Direct work and every Accelerated or Full
-final verify, root hands the unchanged candidate to a fresh read-only Oracle.
-
-Implementation evidence may refine an artifact without restarting the workflow:
-
-- If it preserves the accepted intent, return the evidence to root; root updates
-  the canonical artifact and revalidates only affected downstream artifacts and
-  gates.
-- If it changes intent or accepted product scope, start a new change rather than
-  silently expanding this one.
-
-Report files changed, checks executed, deviations, and remaining work.
-
-## Native dispatch groups and waves
-
-For each ready group, confirm prerequisites, ordered lane tasks, exact path
-union, owner, requirements, and checks. Select the capacity-bounded set of
-undispatched ready lanes and create one fresh native specialist assignment per admitted lane. Issue every dispatch in that native wave before any wait, status,
-result collection, or root implementation action. Retain handles; when terminal evidence frees capacity, dispatch the next undispatched ready lane before waiting again. Validate terminal evidence per lane, while root alone updates task state. Cross the declared barrier only after every lane is terminal and reconciled. Preserve truthful capability/capacity fallback: when native
-concurrency is unavailable or width is one, use a truthful sequential fallback.
+# Implement
+
+Use the settled small request or authorized substantial record, exact mutable
+bounds, and focused checks. Root owns user decisions and acceptance. Keep one
+writer per surface. No process tools, wrappers, reports, or temporary artifacts.
+
+## Choose ownership, then bound the outcome
+
+- Root retains known low-risk mechanical work, including reviewed commits;
+  inspect the relevant diff/index, check it, commit, and stop. Do not restart
+  exploration, planning, delegation, or full tests for an unchanged reviewed tree.
+- Explicit direct-work or no-delegation instructions win. Otherwise delegate for
+  a concrete discovery, implementation, parallelism, or judgment benefit. Another
+  targeted search or file count does not force a new agent.
+- Preserve operator-selected model and effort, including max. Efficiency comes
+  from bounded work and supervision, not changing those settings.
+- Each assignment delivers one independently acceptable outcome. Start from its
+  accepted inputs and named dependencies; state the concrete output, exact known
+  entrypoints and skill paths, owner, owned writes and interface boundaries,
+  focused checks with pass evidence, and a meaningful return milestone and stop
+  condition. Read-only assignments state `none` for writes. Do not delegate an
+  entire broad integration without separately acceptable outputs or split by
+  file count.
+- A dependent assignment starts only after root accepts the producer's output.
+  Missing inputs or interfaces, conflicting ownership, a new independent
+  outcome, or material scope or risk growth returns bounded progress to root for
+  reassessment before expansion. Keep one writer per surface and preserve the
+  native lifecycle, configured effort, and required independent verification.
+
+## Work until the outcome is satisfied, not until time runs out
+
+- Start with supplied evidence. Read further only to answer a specific missing
+  fact; do not rediscover unchanged facts or search the user home for known skills.
+- Behavior changes use focused red -> green tests. Batch independent short reads
+  or checks where supported. Stop cleanup at the assigned outcome's boundary.
+- After two consecutive attempts without new evidence or progress, return the
+  partial result and smallest blocker. Escalate a missing interface or ownership
+  conflict before expanding scope. Productive long work is not failure by time.
+- Root responds to native attention or a missed agreed milestone: inspect the
+  delta and next action, then continue concretely, narrow, or stop safely. A long
+  timeout is a safety ceiling, not a progress plan. Do not merely extend it.
+- Use native completion notifications/waits, never polling, custom timers, or
+  scheduler tools. Without attention delivery, bound an assignment to return at
+  an agreed milestone. Reconcile termination before assigning a replacement.
+
+## Finish once, with fresh evidence
+
+- Freeze relevant inputs before final validation. Reuse fresh checks for unchanged
+  inputs; rerun only checks invalidated by edits. Consolidate whole-project checks
+  after integration, not in every child. Report known external failures rather
+  than repeatedly rerunning identical checks without changed prerequisites.
+- Reconcile owned background commands before returning. The final handoff includes
+  the actual outcome, changed surfaces, checks, limitations, and next action. A
+  late notification must preserve that handoff, not replace it with an acknowledgment.
+- Final independent review remains separate. If explicitly prohibited, report
+  root-only checks and leave independent PASS/archive unavailable; no self-approval.
+
+These are instruction-level safeguards, not a runtime scheduler or latency guarantee.

package/skills/thoth-sdd/references/phases/plan.md

@@ -1,19 +1,3 @@
-# Plan contract
+# Plan
 
-**Owner**: root<br>
-**Output**: `openspec/changes/<feature>/plan.md`
-
-Start from `<skill-dir>/templates/plan.md`, where `<skill-dir>` is the directory
-containing the installed `thoth-sdd/SKILL.md`. Read active constitution
-principles and record evidence-backed pre-design and post-design Constitution
-Checks. Extract the exact active numbered principle headings once, then reuse
-that same ordered name set in both checks; only status and evidence may differ.
-Routine SDD does not amend the constitution or run its lifecycle validator;
-activate `thoth-constitution` only when an explicit constitution amendment is
-in scope.
-
-Map each technical choice to FR/SC or a confirmed repository constraint. Name
-affected components, interfaces, exact paths, migrations, risks, rollback, and
-verification seams. Create `research.md`, `data-model.md`, `contracts/`, or
-`quickstart.md` only when that artifact resolves a concrete implementation risk.
-Any unexplained constitution failure blocks tasks.
+For substantial work, translate settled intent into a compact technical approach in the same ID-named `.thoth/changes/<id>/<id>.md` record. Capture relevant interfaces, mutable surfaces, durable deltas, dependencies, risks, and focused verification seams. Describe useful work-unit boundaries with concrete accepted inputs, produced outputs, and dependencies; identify owned writes, interface boundaries, focused checks with pass evidence, and meaningful return and stop conditions where known. Keep the approach decision-ready without writing task rows before the tasks phase. Plan validation is independent of tasks: the `plan` gate must pass before tasks exist. A later material change reopens understanding and classification. Do not make an auxiliary plan document or auto-increment package versions.

package/skills/thoth-sdd/references/phases/specify.md

@@ -1,34 +1,3 @@
-# Specify contract
+# Specify
 
-**Owner**: root<br>
-**Output**: `openspec/changes/<feature>/spec.md`
-
-Start from `<skill-dir>/templates/spec.md`, where `<skill-dir>` is the directory
-containing the installed `thoth-sdd/SKILL.md`, and remain
-implementation-neutral.
-
-- Record **Why**, **Impact**, and affected kebab-case capability slugs (or
-  `None`).
-- Define prioritized, independently testable `US#` stories. Every story needs
-  `Covers: FR-###, SC-###` and Given/When/Then acceptance scenarios.
-- Before choosing durable delta metadata, read
-  `openspec/specs/<capability>/spec.md` when it exists and compare the exact
-  `### Requirement:` titles and normative behavior:
-  - use `ADDED` only when no canonical requirement already expresses the
-    behavior;
-  - use `MODIFIED` or `REMOVED` only with the exact existing title;
-  - use `RENAMED <capability> FROM <exact previous title>` when the title changes;
-  - only `ADDED` is valid when the canonical capability does not exist.
-  A validator warning on `ADDED` into an existing nonempty capability requires
-  semantic-overlap review; exact-title validity alone does not prove new intent.
-- Give every sequential FR a descriptive title, a normative `MUST`/`SHALL`
-  statement, and exactly one delta marker: `INTERNAL`, `ADDED`, `MODIFIED`,
-  `REMOVED`, or `RENAMED ... FROM ...`.
-- Type each measurable SC as `buildable` or `outcome`. Buildable criteria require
-  implementation coverage; outcome criteria remain product/operational
-  verification targets without fake tasks.
-- State assumptions, dependencies, edge cases, and explicit non-goals.
-
-Do not advance while a material ambiguity would change scope, behavior,
-architecture, or durable delta intent. Run the `specify` gate before planning;
-do not defer canonical delta reconciliation until archive.
+Required for every change, proportional to its impact. From accepted user intent and exploration, define concise observable outcomes, non-goals, and meaningful edge cases. Do not create a document or dispatch a specialist as a prerequisite. After all understanding steps, a substantial classification creates the sole `.thoth/changes/<id>/<id>.md` record; small work leaves no persistent record. Check `.thoth/specs/` baselines for declared durable deltas. A material ambiguity must be clarified before classification; do not invent authorization.