thoth-agents 0.1.11 → 0.1.16

package/src/skills/requirements-interview/SKILL.md

@@ -29,9 +29,10 @@ handoff path before implementation begins.
 
 This skill is normally loaded by the root/main orchestrator at the start of a
 new root session. When thoth-mem tools are available, the root/main
-orchestrator MUST also load `thoth-mem-agents`, call `mem_session_start` with
-the active project and session identity, and save the real user prompt with
-`mem_save_prompt` before later delegation.
+orchestrator MUST also load `thoth-mem-agents`, call
+`mem_session(action="start")` with the active project and session identity,
+and save the real user prompt with `mem_save(kind="prompt")` before later
+delegation.
 
 If thoth-mem tools or the required identity values are unavailable, disclose
 that memory bootstrap could not run and continue without claiming memory was
@@ -81,6 +82,8 @@ scaffolding as user prompts.
 9. Always ask and confirm; never choose on the user's behalf.
 10. Do not ask for details that the codebase, task artifacts, or gathered
    context already answer.
+11. Enforce scope faithfulness: scope calibration must not silently shrink the
+    user's stated intent.
 
 ### Phase 3: Complexity Assessment
 
@@ -108,6 +111,10 @@ Evaluate these 6 dimensions. Rate each as **Low**, **Medium**, or **High**:
 Present:
 
 - Summary of understanding
+- Broad user intent and product goal
+- Accepted scope boundaries
+- Deferred or unresolved affected areas that still belong to the accepted goal
+- Explicit exclusions and why they are excluded
 - Scope classification and why
 - Recommended approach options
 - Proposed handoff path
@@ -130,12 +137,12 @@ user to confirm it:
 - Contract sensitivity is Low
 - Failure cost is Low
 
-**Accelerated SDD** (`propose -> tasks`) — when:
+**Accelerated SDD** (`sdd-explore -> propose -> tasks`) — when:
 - 2-3 dimensions are Medium, or
 - 1 dimension is High in logic depth, context span, or discovery need
 - But contract sensitivity and failure cost are not High
 
-**Full SDD** (`propose -> spec -> design -> tasks`) — when any of:
+**Full SDD** (`sdd-explore -> propose -> spec -> design -> tasks`) — when any of:
 - Contract sensitivity is High
 - Failure cost is High
 - 2 or more dimensions are High
@@ -148,11 +155,13 @@ Quick decision heuristics:
 1. Cosmetic work routes direct regardless of file count.
 2. Dense logic rewrites route to at least accelerated SDD regardless
    of file count.
-3. External contracts (API, schema, migration, auth, privacy) usually
+3. End-to-end UX redesign across screens/workflows is usually full SDD when
+   user-flow contracts, behavior contracts, or multiple concerns are involved.
+4. External contracts (API, schema, migration, auth, privacy) usually
    need full SDD.
-4. If the model must remember decisions across many steps, write them
+5. If the model must remember decisions across many steps, write them
    down — that means SDD.
-5. Tie-breaker: unsure between direct and accelerated, choose
+6. Tie-breaker: unsure between direct and accelerated, choose
    accelerated. Unsure between accelerated and full, ask: 'Do we
    need a durable behavior contract?' If yes, full SDD.
 
@@ -182,6 +191,7 @@ corresponding SDD pipeline phase. The handoff MUST include:
 
 Hand off to:
 
+- **Explore**: delegate read-only repository discovery to explorer before artifact-producing phases.
 - **Propose**: [../sdd-propose/SKILL.md](../sdd-propose/SKILL.md)
 - **Spec** (full SDD only): [../sdd-spec/SKILL.md](../sdd-spec/SKILL.md)
 - **Design** (full SDD only): [../sdd-design/SKILL.md](../sdd-design/SKILL.md)
@@ -201,6 +211,9 @@ ask, and wait.
 - Never convert recommendations into unilateral decisions.
 - Do not replace blocking input prompts with plain-text interview questions
   when the harness exposes a blocking user input surface.
+- Do not narrow accepted scope by omission; surface broad intent, accepted
+  scope, deferred or unresolved affected areas, and explicit exclusions before
+  SDD handoff.
 
 ## Anti-Patterns
 

package/src/skills/sdd-propose/SKILL.md

@@ -51,6 +51,7 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    ## Intent
    ## Scope
    ### In Scope
+   ### Deferred / Needs Discovery
    ### Out of Scope
    ## Approach
    ## Affected Areas
@@ -82,8 +83,19 @@ Return a short report with:
 
 - Use canonical OpenSpec filenames only.
 - Keep the proposal focused on why, scope, and success criteria.
-- Always include rollback guidance and explicit out-of-scope items.
+- Preserve the original user intent and product goal in proposal scope. Do not
+  silently shrink broad goals such as full UX redesigns.
+- Describe material behavior changes with `From`, `To`, `Reason`, and `Impact`
+  when applicable.
+- Use `Deferred / Needs Discovery` for unresolved affected areas that are still
+  part of the accepted goal.
+- Keep `Out of Scope` disciplined: include only explicit exclusions, rejected
+  options, ownership-separated future work, or deliberately deferred phases.
+- Do not move parts of the stated user goal to `Out of Scope` only because the
+  implementation path is unknown.
+- Always include rollback guidance and explicit out-of-scope items when they
+  exist.
 - Never reference engram.
-- Never rely on compact search output alone when the mode uses thoth-mem.
-  Follow the 3-layer recall protocol: `search(mode: "compact")` →
-  `timeline` → `get_observation` to retrieve the full artifact body.
+- Never rely on compact recall output alone when the mode uses thoth-mem.
+  Use `mem_recall(mode="compact")` -> `mem_recall(mode="context")` ->
+  `mem_get(id=...)` to retrieve the full artifact body.

package/src/skills/sdd-tasks/SKILL.md

@@ -129,6 +129,12 @@ Return:
 - Tasks must be small, actionable, and verifiable.
 - Order tasks by dependency.
 - Include testing and verification work explicitly.
+- Preserve accepted proposal or spec scope and success criteria in tasks.
+- Use boundaries and non-goals to express phase, file, or ownership limits,
+  not to shrink the accepted goal.
+- Convert deferred or unresolved affected areas into discovery,
+  coordination, or follow-up tasks, or emit an explicit warning when follow-up
+  cannot be planned yet.
 - Do not create vague tasks such as "implement feature".
 - The governance validator is advisory only at this stage; it documents
   handoff placement and report findings, but it does not block task generation

package/src/skills/thoth-mem-agents/SKILL.md

@@ -9,347 +9,199 @@ metadata:
 # thoth-mem Agents Skill
 
 Use this skill whenever memory work crosses the orchestrator/subagent boundary.
-Its job is to prevent silent ownership bugs such as prompt pollution,
-implicit `manual-save-{project}` sessions, or subagents writing session-level
-artifacts that belong to the orchestrator.
+It prevents prompt pollution, implicit fallback sessions such as
+`manual-save-{project}`, and session-level writes from the wrong agent.
 
 ## Shared References
 
-Read these first instead of re-inventing conventions:
+Read these first:
 
 - [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
 - [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
 
-This skill ADDS the orchestrator/subagent split that those files imply. Do not
-duplicate their SDD persistence details unless needed to make a decision.
+## Active MCP Surface
 
-Adapter bindings may differ, but the same semantic ownership boundaries must
-hold.
+Use thoth-mem through these MCP tools:
 
-## Hard Ownership Split
-
-### Root/main orchestrator identity
-
-The current root/main agent owns root/main orchestrator-owned tools and responsibilities
-for the session. In harnesses where the initial agent is not named
-`orchestrator`, all "orchestrator-only", "root-only", and
-"orchestrator-owned" rules still apply to that initial/root agent.
+- `mem_recall` for fused retrieval and search
+- `mem_save` for observations, prompts, session summaries, and passive learnings
+- `mem_context` for recent session/project continuity
+- `mem_get` for full memory content and optional timeline context
+- `mem_project` for project summaries, graph facts, topics, and topic context
+- `mem_session` for root-owned session lifecycle and checkpoints
 
-### New Root Session Bootstrap
+Admin/export/import/sync/migration/rebuild/index/trace operations are CLI/HTTP/dashboard operations, not MCP tools.
 
-At the start of every new root session, when thoth-mem tools are available, the
-root/main orchestrator MUST:
-
-1. Load `thoth-mem-agents` and `requirements-interview`.
-2. Call `mem_session_start` with the active project and session identity.
-3. Save the real user prompt with `mem_save_prompt`.
-
-In prose: call `mem_session_start` before delegation, then save the real user prompt with `mem_save_prompt`.
+## Hard Ownership Split
 
-Only save real user prompts with `mem_save_prompt`. Never save generated
-subagent prompts, internal handoffs, tool scaffolding, summaries, or delegated
-task text as user intent.
+### Root/main orchestrator identity
 
-If thoth-mem tools or required project/session identity are unavailable, state
-that memory bootstrap could not run and continue without claiming memory was
-saved.
+The initial/root agent in the harness is the orchestrator owner for this
+session, even when the runtime does not label it `orchestrator`.
 
-### Orchestrator-only tools
+### Root-only session and prompt ownership
 
-ONLY the root/main orchestrator owns these tools:
+At new root session start, when tools and identity are available, the root:
 
-- `mem_session_start`
-- `mem_session_summary`
-- `mem_save_prompt`
+1. Loads `thoth-mem-agents` and `requirements-interview`.
+2. Calls `mem_session(action="start")` with root session identity.
+3. Saves real user intent with `mem_save(kind="prompt")`.
 
-Subagents MUST NOT call them.
+Root owns these operations:
 
-If the active harness cannot hard-enforce this ownership split, treat it as
-instruction-level governance and disclose that limitation when reporting
-memory-governance status. Lack of hard enforcement is not permission for a
-subagent to create sessions, close sessions, or save prompts.
+- `mem_session(action="start")`
+- `mem_session(action="checkpoint")` when used for root progress checkpoints
+- `mem_session(action="summary")`
+- `mem_save(kind="prompt")`
+- root-owned session summaries/checkpoints, including `mem_save(kind="session_summary")` when used as the summary carrier
 
-Why:
+Subagents must never start/checkpoint/summarize sessions or save prompts.
 
-- `mem_session_start` defines the session boundary.
-- `mem_session_summary` closes or repairs that boundary.
-- `mem_save_prompt` is only valid for real user requests, and subagent prompts
-  are orchestration artifacts, not user intent.
+If tools or required identity are missing, report that bootstrap/compaction
+could not be persisted and continue without claiming memory was saved.
 
-## Root Memory Protocol
+## Root Recall and Save Protocol
 
-### Durable Saves
+### Durable saves
 
-The root/main orchestrator should call `mem_save` after durable work or
-decisions, including:
+Root should persist durable outcomes with `mem_save`:
 
-- architecture, design, or workflow decisions
-- accepted or rejected recommendations
-- bug fixes with root cause
-- non-obvious discoveries, gotchas, or edge cases
-- configuration changes or environment setup
-- reusable patterns or conventions
-- durable user preferences or constraints
+- decisions and architecture constraints
+- bug fixes and root cause
+- non-obvious discoveries and patterns
+- configuration changes
+- durable preferences/constraints
 
-Use stable topic keys for evolving topics. If unsure, call
-`mem_suggest_topic_key` before saving. Keep the observation content structured:
+Keep content structured:
 
 ```text
 What: concise description
 Why: reason or problem solved
 Where: files, paths, systems, or artifacts
-Learned: edge cases, caveats, or follow-up notes
+Learned: caveats or edge cases
 ```
 
-Do not claim memory was saved unless the tool call succeeded.
-
-### Recall
-
-Broad recovery at root session start or after compaction may use the root-owned
-recent-session overview tools when available. For precise retrieval, use
-Targeted 3-layer recall:
-
-1. `mem_search` with compact results to scan IDs and titles.
-2. `mem_timeline` around promising observation IDs.
-3. `mem_get_observation` only for records needed in full.
-
-Use preview search only when compact results are insufficient to disambiguate.
-
-### Session Close
+### Recall funnel (canonical)
 
-Before ending the root session, the root/main orchestrator MUST call
-`mem_session_summary` when the tool is available. Use a concise summary with:
+1. `mem_recall(mode="compact")`
+2. `mem_recall(mode="context")`
+3. `mem_get(id=...)`
 
-- Goal
-- Instructions
-- Discoveries
-- Accomplished
-- Next Steps
-- Relevant Files
+Use `mem_get(id=..., include_timeline=true)` when chronology matters.
+Use `mem_context(..., recall_query="...")` only as optional fused context, not
+as a replacement for the recall funnel.
 
-If the summary cannot be saved, disclose that limitation rather than implying
-the next session will recover it from memory.
+### Project navigation
 
-### After Compaction
+Use `mem_project` for project-level navigation:
 
-After compaction, first preserve the compacted summary with
-`mem_session_summary`, then recover recent context and use Targeted 3-layer
-recall before continuing. Do not invent missing memory.
+- `action="list"`
+- `action="summary"`
+- `action="graph"`
+- `action="topics"`
+- `action="topic"`
 
-### SDD Topic Keys
+### Session close and compaction
 
-SDD artifacts saved to thoth-mem use deterministic topic keys:
+Before ending meaningful work, root records continuity with either:
 
-`sdd/{change}/{artifact}`
-
-Examples: `sdd/add-user-auth/spec`, `sdd/add-user-auth/design`,
-`sdd/add-user-auth/tasks`.
+- `mem_session(action="summary")`, or
+- root-owned `mem_save(kind="session_summary")`
 
-Never reuse the `sdd/...` namespace for general durable observations.
+Before delegation after meaningful context changes, root may refresh a
+checkpoint/summary context using root-owned session tools. Subagent prompts must
+carry recovery instructions, never the raw handoff body.
 
-## Project-Scoped Read Tools
+## Project-Scoped Context Rules
 
-These tools are read/context only, not session-owned artifacts:
-
-- `mem_project_summary`
-- `mem_project_graph`
-- `mem_topic_keys`
-
-Use them only when the dispatch includes parent `session_id` and `project`,
-and only for bounded project/topic context that helps before the usual
-3-layer recall.
+`mem_context` and `mem_project(...)` are bounded context reads, not ownership
+transfers.
 
 Rules:
 
-- Treat them as safer alternatives to broad session context for project-scoped
-  discovery.
-- Keep them bounded with project/topic filters and explicit limits.
-- Do not use them to create, close, or summarize sessions.
-- Do not use them to save prompts or durable observations.
-
-## Prompt Saving Rule
+- Use only with parent `session_id` and `project` when delegated.
+- Keep calls bounded to the task scope.
+- Do not use them to bypass the recall funnel.
+- Do not use them to create session summaries or save prompts.
 
-- Never save a subagent prompt.
-- Never ask a subagent to save its prompt.
-- Treat the subagent prompt as generated execution scaffolding from the
-  orchestrator.
-
-If a workflow says “save the prompt for future context,” that applies to the
-root user conversation only.
+Operational note: semantic lanes can be pending/degraded; lexical/KG fallback is
+valid and expected. Treat fallback metadata as state, not failure.
 
 ## Dispatch Contract
 
-When a subagent is allowed to touch thoth-mem, the orchestrator MUST pass:
+When subagents may use thoth-mem, dispatch MUST include:
 
 - parent `session_id`
 - `project`
-- any thoth-mem limits or ownership constraints relevant to the task
-
-If a subagent does NOT receive both `session_id` and `project`, it MUST NOT call
-any thoth-mem tool.
+- persistence mode
+- memory permissions (read-only vs delegated write)
+- bounded recall instructions
 
-Reason: thoth-mem can create implicit fallback sessions such as
-`manual-save-{project}`. That splits history away from the root workflow.
+Without both `session_id` and `project`, subagents must not call thoth-mem.
 
 ## Capability Split by Agent Type
 
 ### Read-only subagents
 
-Semantic roles: explorer, librarian, oracle.
+Roles: explorer, librarian, oracle.
 
-Allowed pattern only:
+Allowed:
 
-1. `mem_search`
-2. `mem_timeline`
-3. `mem_get_observation`
-4. `mem_project_summary` when project overview is needed
-5. `mem_project_graph` when relationship/lineage investigation is needed
-6. `mem_topic_keys` when topic-key discovery or inspection is needed
+- recall funnel: `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get`
+- optional bounded context: `mem_context`, `mem_project`
 
-Rules:
+Not allowed:
 
-- Use the parent `session_id` and `project` from dispatch.
-- Do not call `mem_save`, `mem_update`, `mem_session_start`,
-  `mem_session_summary`, or `mem_save_prompt`.
-- Do not treat `mem_search` output as the artifact body.
-- Keep project-scoped read tools bounded by project/topic filters and the task
-  scope.
+- `mem_save`
+- any root session ownership action (`mem_session(...)`)
+- `mem_save(kind="prompt")`
 
 ### Write-capable subagents
 
-Semantic roles: deep, quick, designer.
+Roles: deep, quick, designer.
 
-Allowed thoth-mem behavior:
+Allowed:
 
-- same 3-layer recall as read-only agents when reading
-- project-scoped read tools when a broader project/topic context is explicitly
-  needed
-- `mem_save` for delegated durable observations that arise from their
-  implementation work
+- same recall funnel as read-only roles
+- optional bounded context via `mem_context`/`mem_project`
+- delegated durable saves via `mem_save(kind="observation")`
+- deterministic SDD artifact saves only when explicitly delegated
 
 Rules:
 
-- Use the parent `session_id` and `project` from dispatch on every thoth-mem
-  call.
-- Do not call `mem_context`; writable subagents stay on the same bounded
-  3-layer recall path, using project-scoped read tools only when explicitly
-  granted in dispatch.
-- Never create or close sessions.
-- Never save prompts.
-- You do not own durable memory of your own. Any `mem_save` is a delegated
-  write under the orchestrator's session/project, not a subagent-owned
-  session.
-- Save only durable information: decisions, bugfixes, patterns,
-  configuration changes, discoveries, and explicitly assigned SDD artifacts.
-
-## Memory Types and Topic Keys
-
-Prefer stable, non-colliding topic keys.
-
-### General durable observations
+- every thoth-mem call uses parent `session_id` and `project`
+- never start/checkpoint/summarize sessions
+- never save prompts
+- report missing/stale/contradictory/insufficient recall context
 
-Use keys outside the SDD namespace, for example:
+## Topic-Key Rules
 
-- `decision/thoth-mem/subagent-ownership`
-- `bugfix/thoth-mem/prompt-pollution`
-- `pattern/thoth-mem/parent-session-dispatch`
-- `config/thoth-mem/root-hook`
-- `discovery/thoth-mem/manual-save-fallback`
-
-### SDD artifacts
-
-Use the shared deterministic format from the convention files:
+General durable observations must stay outside `sdd/*`.
+SDD artifacts use deterministic keys only:
 
 `sdd/{change}/{artifact}`
 
-Never reuse the `sdd/...` namespace for general notes. That causes artifact
-collisions and corrupts recovery assumptions.
-
-## Orchestrator Checklist
-
-Before dispatching subagents in a thoth-mem workflow, verify all of this:
-
-- `mem_session_start` has already run for the root session before any later
-  `mem_session_summary`.
-- The dispatch includes parent `session_id` and `project`.
-- The dispatch states whether the subagent may read memory only or may also
-  `mem_save` delegated observations under the parent session/project, and
-  whether project-scoped read tools (`mem_project_summary`, `mem_project_graph`,
-  `mem_topic_keys`) are allowed.
-- The dispatch does NOT ask the subagent to save prompts.
-- The dispatch does NOT ask the subagent to write session summaries.
-- If the work is SDD-related, the dispatch preserves the shared topic-key rules
-  and avoids collisions with `sdd/{change}/{artifact}`.
-- The dispatch identifies the active binding surface when it matters for tool
-  names or enforcement. Explicitly note when memory ownership and tool-boundary
-  controls are instruction-level rather than runtime-enforced.
+Examples: `sdd/add-user-auth/spec`, `sdd/add-user-auth/design`,
+`sdd/add-user-auth/tasks`.
 
 ## Anti-Patterns
 
-Reject these patterns immediately:
+Reject immediately:
 
-- Subagent calls `mem_save_prompt`.
-- Subagent calls `mem_session_start` or `mem_session_summary`.
-- Subagent uses thoth-mem without parent `session_id` and `project`.
-- Writable subagent calls `mem_context` instead of the bounded 3-layer recall.
-- Subagent uses project-scoped read tools without explicit permission in the
-  dispatch.
-- Read-only subagent writes memory.
-- General observation saved under `sdd/...`.
-- Orchestrator asks a subagent to “remember this user request” by saving the
-  generated dispatch prompt.
-- A harness-specific tool alias is treated as permission to bypass the
-  orchestrator/subagent ownership split.
-
-## Dispatch Examples
-
-### Correct
-
-```text
-Load skill thoth-mem-agents and follow it.
-Parent session_id: ses_root_123
-Project: thoth-agents
-Memory limits: read-only recall only; do not write memory.
-Task: inspect prior thoth-mem ownership decisions for the hook redesign.
-```
-
-```text
-Load skill thoth-mem-agents and follow it.
-Parent session_id: ses_root_123
-Project: thoth-agents
-Memory limits: you may mem_save durable implementation observations, but never
-save prompts or call session tools.
-Task: implement the prompt ownership fix and persist any durable bugfix notes.
-```
-
-### Incorrect
-
-```text
-Check memory and save your prompt for traceability.
-```
-
-Why wrong: no parent `session_id`/`project`, and it asks the subagent to save a
-generated prompt.
-
-```text
-Use mem_session_summary when done so we keep the session updated.
-```
-
-Why wrong: session summaries are orchestrator-owned.
+- asking a subagent to save a generated dispatch prompt
+- subagent use of root session operations (`mem_session(...)`)
+- subagent save of `kind="prompt"`
+- inventing thoth-mem tools outside the six-tool MCP surface
+- treating `mem_context` as a substitute for recall funnel
+- saving general notes under `sdd/*`
 
 ## Response Standard
 
-When you apply this skill, be explicit about:
-
-- which agent owns the memory operation
-- which thoth-mem tools are allowed for this task
-- whether parent `session_id` and `project` were provided
-- whether project-scoped read tools are allowed and which ones
-- whether a proposed topic key is safe or collides with `sdd/...`
-- which binding surface is active when the distinction affects tool names,
-  role invocation, or enforcement
-- whether any governance rule is instruction-level because the harness cannot
-  hard-enforce the boundary
+When applying this skill, state clearly:
 
-If any of those are missing, stop using thoth-mem and continue only with local
-context unless the orchestrator provides the missing ownership data.
+- memory owner for each operation (root vs subagent)
+- allowed tools for the task
+- whether parent `session_id` and `project` are present
+- whether context reads are bounded and explicitly allowed
+- whether topic keys collide with `sdd/*`
+- whether any rule is instruction-level due to runtime enforcement limits