@iowarp/clio-coder 0.5.1 → 0.5.2

package/docs/guide/context-continuity.md

@@ -0,0 +1,49 @@
+# Context continuity and recovery
+
+Clio can reduce a long native session while preserving the assistant's exact handoff note and the original task. Open `/context` to inspect the next request's input, output reservation, headroom, and pending handoff. The model can read the same accounting with `context(scope="budget")`.
+
+## Choosing a reduction
+
+| Action | Use it for |
+| --- | --- |
+| Automatic compaction | Routine pressure management under your configured threshold. |
+| `/context compact [instructions]` | An operator-directed summary, optionally focused on specific information. |
+| `self_compact({"note_to_self":"…"})` | An assistant-directed handoff followed by continuation of the same task. |
+| `/context recover <handoffId> <reduce\|deliver>` | Explicit recovery of an interrupted handoff. |
+
+`self_compact` is available to the native orchestrator. Dispatched workers do not receive its host callback, and external agents that own their own loop do not receive its schema through the native session tool surface. Skill restrictions and normal tool permission checks still apply.
+
+The assistant must call `self_compact` alone. A batch containing it and another tool, or two self-compaction calls, is rejected before any valid sibling executes. The note should preserve the objective, decisions, useful evidence, relevant paths, unresolved questions, and next steps. It must be nonblank and no larger than 8,192 UTF-8 bytes. Clio preserves the accepted text exactly and labels it as assistant-authored recall, rather than presenting it as an operator instruction.
+
+## What the receipt means
+
+The tool's first receipt means that the note was prepared and flushed to the session ledger. Reduction happens after that receipt has been persisted. Clio records the reduction attempt before invoking the summarizer, checkpoints the outcome, and records delivery intent before allowing another foreground request.
+
+A final, nonempty, successful assistant response acknowledges that delivery. Intermediate tool calls, empty responses, errors, cancellation, and a generic end-of-run event do not acknowledge it. Continuation does not append another operator turn or create a fresh durable-memory selection attempt.
+
+Each handoff allows at most two reduction attempts, with at most two summary stream invocations per attempt. The automatic window is bounded to 15 minutes. A new operator recovery request may renew that window, but does not refund spent attempts or mint a replacement handoff identity. Summarizer calls, including failed calls with known usage, remain attributable to their originating session.
+
+## Recovering an interrupted handoff
+
+The `/context` overlay shows the pending handoff ID and its phase. Use the exact ID:
+
+```text
+/context recover <handoffId> reduce
+/context recover <handoffId> deliver
+```
+
+`reduce` is available when the handoff has not committed and an attempt remains. `deliver` is available when a validated commit exists. A restarted process first records the interrupted state as paused; it does not automatically repeat an uncertain delivery. Recovery authority comes from the operator command and its durable control record, never from a tool argument or text found in a note.
+
+If the continuation still cannot fit, use `/context compact` to reduce more history before trying delivery again. Missing or conflicting storage evidence can prevent recovery. Clio retains uncertainty instead of silently creating a new transaction. A missing commit can be reconstructed only from a validated summary carry, using its original reserved identity and an exact storage check.
+
+Session forks inherit notes as recall only. They do not inherit permission to resume the parent's handoff. Ordinary summaries persist in the session ledger and replay after `/resume`; a separate handoff file remains useful when moving work to another session or another agent.
+
+## Request budgets and memory
+
+Submission and native continuation require estimated input plus the resolved output reservation to fit the effective window. Pending user-message framing and images count. A final check inspects the actual request after steering has been drained. Ordinary automatic-compaction preferences remain separate from this hard admission check: disabling automatic compaction cannot authorize an oversized request.
+
+Successful durable reductions invalidate older private-memory content jobs and queued memory reminders. Their known usage still counts. Restoration retains the private bank, selects a bounded set of remembered facts and procedures, and suppresses stale private status when an authoritative summary or handoff is available. The full reminder wrapper must fit, and restoration is consumed only after installation in an admitted context. This does not make remembered claims independently verified.
+
+Approved durable-memory selection is frozen for a prepared turn and its continuations. Changes in session, repository, runtime, model, or memory configuration invalidate that authority. A subsequent turn reads the current bounded store contents; a same-size rewrite cannot hide behind a file-size cache key. Default selection limits remain five records and 400 tokens. Experimental lexical ranking is not enabled by default.
+
+Token counts remain estimates unless a provider has attested the relevant prefix. Flush and checkpoint success establish the filesystem durability available to the running process; they do not guarantee survival of every hardware or power failure, or exactly-once execution by a remote provider.

package/docs/guide/proactive-memory.md

@@ -1,5 +1,8 @@
 # Proactive task memory
 
+
+After a durable context reduction, restoration uses a commit-scoped offer: stale content jobs and buffered reminders lose authority, known usage remains attributed, and restoration is consumed only after an admitted installation. See [Context continuity and recovery](context-continuity.md) for the lifecycle and its limits.
+
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
 exist in the transcript while no longer influencing the next action. The design

package/library/registry.yaml

@@ -148,53 +148,50 @@ entries:
           worktree-create. Not for integrating branches; use worktre
   - kind: skill
     name: clio-coder-dev
-    description: "Governs changes to Clio Coder's own source and harness (TUI,
-      skills, agents, tools, prompts, domains): what may change freely, what
-      needs explicit user intent, and how to change it without breaking the
-      architecture. Not for verifying a change against the harness; use
-      clio-coder-test."
+    description: "Develop Clio Coder inside its own repository: trace source
+      contracts, implement bounded changes, coordinate sprint work, and preserve
+      running-agent and session correctness. Use before changing Clio source,
+      prompts, tools, or library; pair with clio-coder-test for validation."
     category: meta
     audit: pass
     triggers:
-      - modify Clio Coder
-      - change the Clio harness
-      - edit Clio skills or agents
-      - evolve Clio tools or prompts
-      - Clio contribution boundary
-    version: 0.4.0
+      - develop Clio in its own repository
+      - implement a Clio sprint packet
+      - change Clio context or session lifecycle
+      - edit Clio skills tools or prompts
+    version: 0.5.0
     sourceUrl: skills/meta/clio-coder-dev
-    sha256: d72e2dcd441600f927738d352766a7472e2340bb60b1a23b6894f921079e4243
+    sha256: a2a9558348234ef5fb5fe821651ef57b8f6430473bd48818a1d468b405c1f61a
     provides:
       - kind: skill
         name: clio-coder-dev
-        description: "Governs changes to Clio Coder's own source and harness (TUI,
-          skills, agents, tools, prompts, domains): what may change freely, what
-          needs explicit user intent, and how to change it without breaking the
-          architecture. Not for verifying a change against the h"
+        description: "Develop Clio Coder inside its own repository: trace source
+          contracts, implement bounded changes, coordinate sprint work, and
+          preserve running-agent and session correctness. Use before changing
+          Clio source, prompts, tools, or library; pair with clio-coder-t"
   - kind: skill
     name: clio-coder-test
-    description: Verifies a Clio Coder source change against the current contract,
-      smoke, boundary, and application test lanes, including temporary-state and
-      local-provider harnesses. Not for deciding what may change; use
-      clio-coder-dev.
+    description: Validate Clio Coder changes using focused source regressions, built
+      CLI and ACP fixtures, skill/library checks, and isolated package or GUI
+      gates. Use when developing or diagnosing Clio itself; select checks from
+      the changed behavior and report evidence without claiming unrun coverage.
     category: meta
     audit: pass
     triggers:
-      - test Clio Coder
-      - verify a Clio source change
-      - run Clio contract tests
-      - test ACP over stdio
-      - Clio mock provider harness
-    version: 0.3.1
+      - validate a Clio change
+      - test Clio context compaction or memory
+      - verify Clio skill activation
+      - choose Clio test gates
+    version: 0.4.0
     sourceUrl: skills/meta/clio-coder-test
-    sha256: c5a1fa81a19d671560d98a5f4e78f56a0515294611bc9ae796aac37165719a92
+    sha256: 6a4748d77d27be81da75ae8359cde2c44f76db83f025920b102a8aa309e17208
     provides:
       - kind: skill
         name: clio-coder-test
-        description: Verifies a Clio Coder source change against the current contract,
-          smoke, boundary, and application test lanes, including temporary-state
-          and local-provider harnesses. Not for deciding what may change; use
-          clio-coder-dev.
+        description: Validate Clio Coder changes using focused source regressions, built
+          CLI and ACP fixtures, skill/library checks, and isolated package or
+          GUI gates. Use when developing or diagnosing Clio itself; select
+          checks from the changed behavior and report evidence wi
   - kind: skill
     name: coding-standards
     description: Correct-by-construction TypeScript rules (errors as values, parse
@@ -235,7 +232,7 @@ entries:
       - write a continuation brief
     version: 0.5.1
     sourceUrl: skills/context/context-handoff
-    sha256: f5d32418c95dcc9766b5564b00e9d27de6c86662b742666792f1ef984921ad24
+    sha256: 64fc4593679735a9e827d8753183595c48fc38ce031902af2d17da7f747a68b1
     provides:
       - kind: skill
         name: context-handoff
@@ -944,3 +941,266 @@ entries:
           integration branch, testing after each merge and running the full
           suite before the main line moves, with exact rollback on failure. Not
           for creating worktrees; use worktree-create. Not for closeou
+  - kind: plugin
+    name: wtfp
+    description: Portable, evidence-grounded academic research and writing workflows.
+    version: 0.7.3
+    sourceUrl: https://github.com/akougkas/wtf-p/tree/v0.7.3/vendors/plugin
+    sha256: 5a4209bed7c4926dc884c5b04bb66ce5ed61083e1b718045cf720f295cc2f3b5
+    provides:
+      - kind: agent
+        name: wtfp-argument-verifier
+        description: Verify that completed section text actually delivers the claims,
+          evidence, constraints, and connections promised by its plan. Execution
+          summaries are navigation aids, not proof; verdicts must be grounded in
+          the manuscript itself.
+      - kind: agent
+        name: wtfp-citation-expert
+        description: "Find a precise, defensible set of sources for explicit manuscript
+          claims and analyze whether the existing bibliography covers the
+          approved argument. Every recommendation must be grounded in resolvable
+          scholarly metadata and its relevance must be explained "
+      - kind: agent
+        name: wtfp-citation-formatter
+        description: Audit bibliography integrity and produce deterministic corrections
+          without touching the primary bibliography. The role cross-references
+          manuscript citation keys, detects missing and unused entries,
+          identifies likely duplicates, and normalizes records while
+      - kind: agent
+        name: wtfp-coherence-checker
+        description: Evaluate the manuscript as a connected argument rather than a set
+          of individually acceptable sections. Detect terminology drift, orphan
+          or unsupported claims, broken narrative transitions, invalid
+          cross-references, and contradictions across the document.
+      - kind: agent
+        name: wtfp-outliner
+        description: Turn the approved project brief into the structural foundation for
+          an academic document. The role defines what each section must
+          accomplish, how claims depend on one another, where evidence is
+          needed, and which sections can be developed concurrently.
+      - kind: agent
+        name: wtfp-plan-checker
+        description: "Determine whether proposed section plans are likely to produce the
+          intended academic outcome. Verification is goal-backward: a
+          syntactically complete plan still fails if it omits a claim, lacks
+          usable evidence, contradicts an author decision, or cannot fit"
+      - kind: agent
+        name: wtfp-prose-polisher
+        description: Improve clarity, rhythm, concision, and authorial voice without
+          changing technical meaning, evidence, citation placement, or
+          argumentative direction. Polishing is a constrained transformation,
+          not a substantive rewrite.
+      - kind: agent
+        name: wtfp-research-synthesizer
+        description: Investigate the literature needed to plan and write a specific
+          section well. The output is an evidence-traceable synthesis of
+          foundational and recent work, standard approaches, genuine gaps,
+          positioning options, and concrete writing guidance—not a search-r
+      - kind: agent
+        name: wtfp-section-planner
+        description: "Convert one approved section goal into small, executable writing
+          plans. A plan is a precise writing contract: it connects claims,
+          evidence, word budgets, sequencing, author decisions, and measurable
+          completion criteria without pre-writing the section."
+      - kind: agent
+        name: wtfp-section-reviewer
+        description: Review a section as an academic evaluator and produce prioritized,
+          actionable feedback. The invocation may select a review
+          lens—adversarial peer, significance-focused chair, production editor,
+          or constructive mentor—without changing the underlying evidence
+      - kind: agent
+        name: wtfp-section-writer
+        description: Execute an approved section plan into evidence-grounded academic
+          prose or the explicitly requested scaffold. Preserve the author’s
+          epistemic authority, make only supported claims, and leave an
+          auditable account of what was produced and what remains unresol
+      - kind: fleet
+        name: wtfp-draft-review
+        description: Draft one approved section and independently review its argument
+          and evidence.
+      - kind: fleet
+        name: wtfp-plan-section
+        description: Create and independently check one evidence-grounded section plan.
+      - kind: prompt
+        name: wtfp:add-todo
+        description: Capture a bounded note or task without disrupting the active
+          research flow.
+      - kind: prompt
+        name: wtfp:analyze-bib
+        description: Analyze a bibliography and map its evidence to the paper's sections
+          and claims.
+      - kind: prompt
+        name: wtfp:audit-milestone
+        description: Run readiness checks across section completion, arguments, length,
+          citations, and reviews.
+      - kind: prompt
+        name: wtfp:check-refs
+        description: Audit citation integrity and emit a validated
+          corrected-bibliography candidate without mutating source records or
+          manuscript inputs.
+      - kind: prompt
+        name: wtfp:check-todos
+        description: Review pending tasks and explicitly act on, defer, complete, or
+          dismiss each one.
+      - kind: prompt
+        name: wtfp:checkpoint
+        description: Save, list, or restore an exact portable paper-state checkpoint.
+      - kind: prompt
+        name: wtfp:contribute
+        description: Guide a bounded WTF-P contribution from branch creation through a
+          reviewable change request.
+      - kind: prompt
+        name: wtfp:create-outline
+        description: Build the section structure, argument map, dependencies, and word
+          budgets.
+      - kind: prompt
+        name: wtfp:create-poster
+        description: Transform the paper's argument, methods, and findings into a
+          concise academic poster.
+      - kind: prompt
+        name: wtfp:create-slides
+        description: Transform the paper's argument, evidence, and findings into an
+          audience-appropriate presentation.
+      - kind: prompt
+        name: wtfp:discuss-section
+        description: Capture the researcher's intended purpose, essential content,
+          voice, and boundaries before planning.
+      - kind: prompt
+        name: wtfp:execute-outline
+        description: Draft independent section waves in parallel and verify
+          cross-section coherence.
+      - kind: prompt
+        name: wtfp:export-latex
+        description: Export the manuscript and bibliography to portable LaTeX source
+          with declared formatting.
+      - kind: prompt
+        name: wtfp:help
+        description: Render the stable WTF-P action reference from the canonical catalog.
+      - kind: prompt
+        name: wtfp:insert-section
+        description: Insert a newly discovered section while preserving established
+          numbering and dependencies.
+      - kind: prompt
+        name: wtfp:list-assumptions
+        description: Preview the intended approach and assumptions for a section without
+          changing project files.
+      - kind: prompt
+        name: wtfp:map-project
+        description: Index existing drafts, data, figures, and references into portable
+          project state.
+      - kind: prompt
+        name: wtfp:new-paper
+        description: Interview the researcher and initialize a portable WTF-P project.
+      - kind: prompt
+        name: wtfp:pause-writing
+        description: Record an exact context handoff so another session can resume
+          without reconstructing intent.
+      - kind: prompt
+        name: wtfp:plan-milestone-gaps
+        description: Convert milestone audit failures into targeted, verifiable fix plans.
+      - kind: prompt
+        name: wtfp:plan-revision
+        description: Turn prioritized review findings into a bounded, testable revision
+          plan.
+      - kind: prompt
+        name: wtfp:plan-section
+        description: Create and independently check a detailed writing plan for one section.
+      - kind: prompt
+        name: wtfp:polish-prose
+        description: Improve clarity, flow, precision, and academic voice without
+          changing supported claims.
+      - kind: prompt
+        name: wtfp:progress
+        description: Summarize writing progress, surface blockers, and recommend the
+          next compatible action.
+      - kind: prompt
+        name: wtfp:quick
+        description: Apply a small, bounded writing fix with minimal planning overhead
+          and state tracking.
+      - kind: prompt
+        name: wtfp:remove-section
+        description: Remove an unwritten future section and repair numbering and
+          dependencies.
+      - kind: prompt
+        name: wtfp:report-bug
+        description: Collect a reproducible bug report and publish it only after
+          explicit user approval.
+      - kind: prompt
+        name: wtfp:request-feature
+        description: Shape a concrete feature request and publish it only after explicit
+          user approval.
+      - kind: prompt
+        name: wtfp:research-gap
+        description: Synthesize literature, domain conventions, open gaps, and
+          defensible positioning for a section.
+      - kind: prompt
+        name: wtfp:resume-writing
+        description: Restore the latest portable handoff and route the researcher to the
+          next safe action.
+      - kind: prompt
+        name: wtfp:review-section
+        description: Review a drafted section for evidence, citations, coherence,
+          requirements, and reader expectations.
+      - kind: prompt
+        name: wtfp:settings
+        description: View and update portable project settings after presenting the
+          exact proposed diff.
+      - kind: prompt
+        name: wtfp:submit-milestone
+        description: Archive a completed draft or submission round with its reproducible
+          project state and statistics.
+      - kind: prompt
+        name: wtfp:update
+        description: Check for a newer compatible package or plugin release and install
+          it only after approval.
+      - kind: prompt
+        name: wtfp:verify-work
+        description: Test a drafted section against each plan requirement and record
+          evidence one check at a time.
+      - kind: prompt
+        name: wtfp:write-section
+        description: Execute an approved section plan, update state, and optionally
+          verify argument coverage.
+      - kind: skill
+        name: wtfp-deliver-research
+        description: This skill packages completed research for publication and
+          presentation. It activates when an agent needs to export a manuscript
+          to LaTeX, archive a draft or submission milestone, create research
+          slides, design an academic poster, or perform the WTF-P expo
+      - kind: skill
+        name: wtfp-manage-project
+        description: This skill coordinates the durable state of a research-writing
+          project. It activates when an agent needs to report progress, pause or
+          resume work, save or restore a checkpoint, edit project settings,
+          capture or review todos, choose the next workflow, or pe
+      - kind: skill
+        name: wtfp-plan-section
+        description: This skill plans and safely reshapes manuscript sections. It
+          activates when an agent needs to discuss a section, expose
+          assumptions, make a writing or revision plan, insert a newly
+          discovered section, remove an unstarted section, or perform the WTF-P
+          discu
+      - kind: skill
+        name: wtfp-research-literature
+        description: This skill researches, organizes, and audits scholarly literature
+          for an academic manuscript. It activates when an agent needs to
+          investigate a research gap, analyze a bibliography, map references to
+          sections, validate citation coverage, repair reference m
+      - kind: skill
+        name: wtfp-review-manuscript
+        description: This skill reviews, verifies, audits, and polishes academic
+          manuscripts. It activates when an agent needs to review a section,
+          test work against a plan, refine academic voice, audit submission
+          readiness, create milestone gap plans, or perform the WTF-P rev
+      - kind: skill
+        name: wtfp-start-project
+        description: This skill initializes and structures academic writing projects. It
+          activates when an agent needs to start a paper, map existing drafts,
+          data, or references, create an outline, build an argument map,
+          allocate word budgets, or perform the WTF-P new-paper, m
+      - kind: skill
+        name: wtfp-write-section
+        description: This skill drafts and revises manuscript sections from approved
+          plans and evidence. It activates when an agent needs to write one
+          section, execute an outline in dependency waves, make a small targeted
+          prose or citation change, or perform the WTF-P write-se

package/library/skills/README.md

@@ -2,8 +2,9 @@
 
 This tree contains reviewed skill instructions and authoring evidence. Complete
 packages participate in the same [library](../../docs/guide/resource-library.md) as
-plugins, agents, prompts and fleets. Nothing in this source tree loads merely
-because it ships with Clio.
+plugins, agents, prompts and fleets. Bundling a package does not activate it.
+Inside a detected Clio source checkout, the two self-development skills described
+below are also available directly from their authoring directories.
 
 `library/skills/` is the canonical source for Clio Coder's curated skills. The npm
 package includes this tree, `library/plugins/`, and the `library/registry.yaml` index.
@@ -42,6 +43,30 @@ grant authority the host disallows.
 
 ## Source organization
 
+### Developing Clio itself
+
+When Clio detects its own Git checkout (including worktrees and subdirectory
+launches), it discovers `clio-coder-dev` and `clio-coder-test` from
+`library/skills/meta/` as native local skills. This does not install packages or
+discover the rest of the catalog. Source roots must remain inside the checkout;
+an unrelated nested Git repository does not inherit them.
+
+The session prompt recommends `clio-coder-dev` for source changes and
+`clio-coder-test` for validation. At `auto-edit` and `full-auto`, the model can
+load ready skills through `context(scope="skills", name="...")`. At `read-only`
+and `suggest`, operator activation is still required. This is automatic discovery
+and task-aware guidance, not automatic body injection or a guarantee of a model's
+tool choice. `--no-skills`, hidden skills, and task/tool restrictions still apply.
+
+An installed package owns its name even when disabled, damaged, or pending
+reload; source discovery does not bypass it. Native local overrides keep their
+precedence. Worker recipes retain their declared skill bindings; parent-session
+activation is not inherited. A running process needs a new candidate build and
+restart for runtime changes, while editing these source skills remains ordinary
+repository work. Follow `CONTRIBUTING.md` and the skills' focused references.
+
+## Catalog layout
+
 | Directory | Subject |
 | --- | --- |
 | `coding/` | Implementation, structural search, prototyping and tests |

package/library/skills/context/context-handoff/SKILL.md

@@ -34,10 +34,16 @@ Write a durable brief so a fresh session continues the work without re-reading
 the whole transcript. This is the write-side bookend of `context-prime`, which
 reads what this produces.
 
-Distinct from two things it is often confused with:
-
-- `/context compact` summarizes *within* the current session; it is ephemeral and lost
-  when the process exits. A handoff is a file that outlives the session.
+Choose the artifact that matches the continuation:
+
+- `/context compact` writes a durable summary in the session ledger. `/resume`
+  replays that checkpoint after a restart. A handoff file gives a different
+  session or agent an explicit brief without requiring access to that ledger.
+- On native runtimes, `self_compact({note_to_self})` preserves an exact assistant
+  note while reducing context and continuing the same task. Call it alone, after
+  outstanding tools settle. Its pending receipt does not prove completion; inspect
+  `context(scope="budget")` and leave `/context recover <id> <reduce|deliver>` to
+  the operator if the handoff is paused.
 - `/handoff <goal>` is the built-in that writes a quick handoff file from the
   live session; this skill is the fuller authored version with redaction and
   reference-not-copy discipline.