@ghostpaw/questlog 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ghostpaw/questlog",
-	"version": "0.5.1",
+	"version": "0.6.1",
 	"description": "Unified task and calendar model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
 	"type": "module",
 	"exports": {
@@ -13,13 +13,26 @@
 				"types": "./dist/index.d.cts",
 				"default": "./dist/index.cjs"
 			}
-		}
+		},
+		"./mcp": {
+			"import": {
+				"types": "./dist/mcp.d.ts",
+				"default": "./dist/mcp.js"
+			},
+			"require": {
+				"types": "./dist/mcp.d.cts",
+				"default": "./dist/mcp.cjs"
+			}
+		},
+		"./package.json": "./package.json"
 	},
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"files": [
-		"dist"
+		"dist",
+		"skills",
+		"SKILL.md"
 	],
 	"sideEffects": false,
 	"scripts": {
@@ -30,15 +43,29 @@
 		"lint:fix": "biome check --fix",
 		"format": "biome format --write",
 		"typecheck": "tsc --noEmit",
-		"check": "biome check && tsc --noEmit",
+		"check": "npm run check:types && npm run check:lint && npm test && npm run build && npm run check:deps && npm run check:surfaces && npm run check:size && npm run check:api && npm run check:consumer && npm run check:startup && npm run check:ratchet",
+		"check:deps": "node scripts/check-zero-deps.mjs",
 		"clean": "rm -rf dist",
 		"demo:build": "node scripts/build_demo.mjs",
 		"demo:watch": "node scripts/build_demo.mjs --watch",
 		"demo:serve": "npm run demo:build && node scripts/serve_demo.mjs",
-		"prepublishOnly": "npm run check && npm run build",
+		"prepublishOnly": "npm run check",
 		"release:patch": "npm version patch && git push && git push --tags",
 		"release:minor": "npm version minor && git push && git push --tags",
-		"release:major": "npm version major && git push && git push --tags"
+		"release:major": "npm version major && git push && git push --tags",
+		"version": "node scripts/sync_version.mjs && npm run surfaces && git add src/version.ts SKILL.md skills plugin.json mcp.json server.json .claude-plugin mcpb && biome format --write package.json package-lock.json && git add package.json package-lock.json",
+		"surfaces": "node --experimental-strip-types scripts/surfaces/generate.mjs",
+		"check:surfaces": "node --experimental-strip-types scripts/surfaces/generate.mjs --check",
+		"check:types": "tsc --noEmit",
+		"check:lint": "biome check",
+		"check:ratchet": "node --test scripts/guard/*.test.mjs && node scripts/guard/ratchet.mjs",
+		"budgets:update": "npm run build && node scripts/guard/size.mjs --update && node scripts/guard/api.mjs --update && node scripts/guard/startup.mjs --update",
+		"bench": "npm run build && node scripts/bench/bench.mjs",
+		"check:size": "node scripts/guard/size.mjs",
+		"check:api": "node scripts/guard/api.mjs",
+		"check:consumer": "node scripts/guard/consumer.mjs",
+		"check:startup": "node scripts/guard/startup.mjs",
+		"mcpb": "node scripts/mcpb/build.mjs"
 	},
 	"engines": {
 		"node": ">=24"
@@ -61,7 +88,12 @@
 		"rrule",
 		"recurrence",
 		"typescript",
-		"zero-dependencies"
+		"zero-dependencies",
+		"mcp",
+		"mcp-server",
+		"model-context-protocol",
+		"agent-skills",
+		"cli"
 	],
 	"license": "MIT",
 	"repository": {
@@ -73,7 +105,7 @@
 		"email": "max@anonyfox.com",
 		"url": "https://anonyfox.com"
 	},
-	"homepage": "https://github.com/GhostPawJS/questlog",
+	"homepage": "https://ghostpaw.anonyfox.com/agent-tasks/",
 	"bugs": {
 		"url": "https://github.com/GhostPawJS/questlog/issues"
 	},
@@ -88,9 +120,14 @@
 		"@biomejs/biome": "2.4.4",
 		"@types/node": "^25.3.0",
 		"esbuild": "^0.27.4",
+		"fflate": "0.8.3",
 		"preact": "^10.29.0",
 		"sql.js-fts5": "^1.4.0",
 		"tsup": "^8.0.0",
 		"typescript": "^5.9.3"
-	}
+	},
+	"bin": {
+		"ghostpaw-questlog": "./dist/cli.js"
+	},
+	"mcpName": "io.github.GhostPawJS/questlog"
 }

package/skills/questlog/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: questlog
+description: "Manage local tasks, calendar commitments, and recurring work. Use when planning, executing, reviewing, or organizing work."
+license: "MIT"
+compatibility: "Node.js 24 or newer. MCP stdio or ghostpaw-questlog CLI."
+---
+
+# questlog
+
+Questlog manages local tasks, calendar commitments, and recurring work. Search before creating work, inspect before changing it, and keep uncertain work as rumors. Use unlock prerequisites to sequence work. run_quest refuses blocked starts unless force is true. Review commitments and resolve work with an honest outcome.
+
+## Calling tools
+
+MCP: connect to ghostpaw-questlog, then call a tool by name with its JSON arguments.
+
+CLI: `ghostpaw-questlog call <tool> '<JSON object>'` or `ghostpaw-questlog <tool> --parameter value` (without a global install: `npx -y @ghostpaw/questlog <tool> ...`).
+
+Inspect schemas with `ghostpaw-questlog describe <tool>`. Use `--db <path>` to select a database.
+
+## search_questlog
+
+Search quests and rumors by text when you need to find an existing item before inspecting or changing it.
+
+Use when: Use this first when the exact quest, rumor, or id is not already known.
+
+Not for: Do not use this when you already know the exact item id and want its full detail.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| query | string | yes | Text to search for in rumor and quest titles and body text. |
+| limit | integer | no | Maximum number of matches to return. |
+| kinds | array | no | Optional entity kinds to search. |
+| mode | string | no | browse, identify_one. Whether to browse results normally or ask for clarification when several matches are found. |
+
+## review_questlog
+
+Review one operational questlog surface such as available quests, open rumors, blocked work, or due repeatable anchors.
+
+Use when: Use this when you want a dashboard-style list view instead of inspecting one specific item.
+
+Not for: Do not use this when you already know the exact item you want to inspect in depth.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| view | string | yes | questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors. Which operational review surface to return. |
+| filters | object | no | Optional filters for supported review surfaces. |
+| now | integer | no | Optional evaluation timestamp for time-sensitive views. |
+
+## inspect_questlog_item
+
+Inspect one specific questlog item in depth and return its richer structured detail and important related refs.
+
+Use when: Use this when you already know the target item id and want either compact or full detail for one rumor, quest, questline, or repeatable quest.
+
+Not for: Do not use this to discover items when the exact target is not known yet.
+
+Read-only.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| target | object | yes | The specific item to inspect. |
+| detailLevel | string | no | compact, full. How much detail to return. |
+| now | integer | no | Optional evaluation timestamp for time-sensitive detail. |
+
+## capture_rumor
+
+Capture uncertain incoming work as a rumor so it can be triaged later without prematurely turning it into committed execution.
+
+Use when: Use this when something matters enough to record but is not yet ready to become a quest or questline.
+
+Not for: Do not use this for already-committed work that should be created directly as a quest or questline.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| title | string | yes | Short rumor title describing the incoming signal or possible work. |
+| details | string | no | Optional supporting context that explains why the rumor might matter. |
+| now | integer | no | Optional creation timestamp for the rumor. |
+
+## shape_work
+
+Create a quest (with timing, tags, and objective in one call), create a questline, settle a rumor into concrete work, or manage quest-questline membership. Use create_quest for clear commitments — include tags and timing directly to avoid follow-up calls.
+
+Use when: Use this when deciding what real work exists and how it should be grouped before or around execution. Prefer a single create_quest call with all fields over separate create + plan_quest + tag_work calls.
+
+Not for: Do not use this for quest execution steps like starting, finishing, abandoning, or logging effort.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | attach_quest_to_questline, create_quest, create_questline, detach_quest_from_questline, dismiss_rumor, reopen_rumor, settle_rumor, update_rumor. Action to perform. |
+| questId | integer | no | Quest to attach or detach. |
+| questlineId | integer | no | Questline that should receive the quest. |
+| quest | object | no |  |
+| questline | object | no |  |
+| rumorId | integer | no | Rumor to settle, dismiss, or reopen. |
+| dismissedAt | integer | no | Optional dismissal timestamp. |
+| settledAt | integer | no | Optional settlement timestamp. |
+| quests | array | no | Quests to create during rumor settlement. Include timing and tags directly. |
+| now | integer | no | Optional timestamp for membership, reopen, or rumor update. |
+| title | string | no | New title for the update_rumor action. |
+| details | string | no | New or enriched context text for the update_rumor action. |
+
+## plan_quest
+
+Refine a quest by revising its objective before actual start or by changing its temporal planning fields.
+
+Use when: Use this when you need to sharpen what the quest means or how it is timed without starting or resolving it.
+
+Not for: Do not use this for lifecycle execution such as start, finish, abandon, or effort logging.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | revise_objective, set_time. Action to perform. |
+| questId | integer | yes | The quest to refine. |
+| objective | string | no | The new quest objective text. Required for revise_objective. |
+| notBeforeAt | integer | no | Optional earliest actionable timestamp. |
+| dueAt | integer | no | Optional latest acceptable completion timestamp. |
+| scheduledStartAt | integer | no | Optional planned schedule window start. |
+| scheduledEndAt | integer | no | Optional planned schedule window end. |
+| allDay | boolean | no | Whether the planned schedule window is all-day. |
+| estimateSeconds | integer | no | Optional active-effort estimate in seconds. |
+| now | integer | no | Optional update timestamp. |
+
+## run_quest
+
+Run quest lifecycle actions such as starting, logging effort, finishing, abandoning, or abandoning and spawning follow-up quests atomically.
+
+Use when: Use this for actual execution lifecycle steps after the quest already exists.
+
+Not for: Do not use this for work shaping, planning-only edits, tagging, or rewards.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | start, log_effort, finish, abandon, abandon_and_spawn_followups. Action to perform. |
+| questId | integer | yes | Quest whose execution state should change. |
+| startedAt | integer | no | Optional start timestamp for the start action. |
+| force | boolean | no | Start despite unmet unlock prerequisites. Defaults to false. |
+| effortSeconds | integer | no | Positive active-effort increment in seconds. Required for log_effort. |
+| now | integer | no | Optional effort-log timestamp. |
+| outcome | string | no | Terminal outcome text. Required for finish, abandon, and abandon_and_spawn_followups. |
+| resolvedAt | integer | no | Optional resolved timestamp for finish or abandon actions. |
+| followups | array | no | Follow-up quests to create atomically. Required for abandon_and_spawn_followups. |
+
+## organize_work
+
+Organize grouping and dependency structure by updating questlines or changing hard unlock prerequisites between concrete quests.
+
+Use when: Use this when work structure or gating logic should change without changing quest execution state.
+
+Not for: Do not use this for quest execution, planning-only edits, intake capture, or tag-like classification.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | add_unlock, archive_questline, remove_unlock, replace_unlocks, set_questline_fields. Action to perform. |
+| questlineId | integer | no | Questline to update or archive. |
+| title | string | no | Optional new questline title. |
+| description | string | no | Optional new questline description. |
+| startsAt | integer | no | Optional questline start timestamp. |
+| dueAt | integer | no | Optional questline due timestamp. |
+| archivedAt | integer | no | Optional archive timestamp. |
+| toQuestId | integer | no | Quest whose blockers should change. |
+| fromQuestId | integer | no | Prerequisite quest id. |
+| fromQuestIds | array | no | Full prerequisite quest id set. |
+| now | integer | no | Optional timestamp. |
+
+## manage_repeatable
+
+Manage recurring work definitions by creating, updating, previewing, spawning, or archiving repeatable quests.
+
+Use when: Use this when the work is a repeatable template or when due recurring anchors need to be previewed or materialized.
+
+Not for: Do not use this for one-off concrete quest execution, for inspecting an existing concrete quest, or for hiding a repeatable quest. Use `retire_work` for hiding.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | archive, create, preview_due, spawn_due, update. Action to perform. |
+| repeatableQuestId | integer | no | Repeatable quest to archive or update. |
+| repeatableQuest | object | no |  |
+| title | string | no | Optional new title for the update action. |
+| objective | string | no | Optional new objective for the update action. |
+| questlineId | integer | no | Optional new questline id. |
+| rrule | string | no | Optional new RRULE. |
+| anchorAt | integer | no | Optional new recurrence anchor timestamp. |
+| notBeforeOffsetSeconds | integer | no | Optional new not-before offset in seconds. |
+| dueOffsetSeconds | integer | no | Optional new due offset in seconds. |
+| scheduledStartOffsetSeconds | integer | no | Optional new scheduled-start offset in seconds. |
+| scheduledEndOffsetSeconds | integer | no | Optional new scheduled-end offset in seconds. |
+| allDay | boolean | no | Whether future schedules are all-day. |
+| estimateSeconds | integer | no | Optional new effort estimate. |
+| archivedAt | integer | no | Optional archive timestamp. |
+| now | integer | no | Evaluation or update timestamp. |
+
+## tag_work
+
+Classify work by adding, removing, or replacing tags on quests and by replacing the future tag template set on repeatable quests.
+
+Use when: Use this when you want classification, reporting, or saved-filter semantics rather than lifecycle or dependency semantics.
+
+Not for: Do not use tags to model status, time planning, or hard prerequisites.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | add, remove, replace. Action to perform. |
+| target | object | yes |  |
+| tagNames | array | yes | Tag names to add, remove, or replace. |
+| now | integer | no | Optional timestamp for the tag mutation. |
+
+## reward_work
+
+Manage rewards by adding, updating, removing, or claiming quest rewards, or by replacing future reward templates on repeatable quests.
+
+Use when: Use this when a completed or recurring piece of work should grant or update reward information.
+
+Not for: Do not use this to finish quests themselves or to model dependencies, classification, or scheduling.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | add, claim, remove, replace_repeatable_template, update. Action to perform. |
+| target | object | yes |  |
+| reward | object | no |  |
+| rewards | array | no | Full future reward template set. Required for replace_repeatable_template. |
+| claimedAt | integer | no | Optional claim timestamp. |
+| now | integer | no | Optional timestamp for removal or template replacement. |
+
+## retire_work
+
+Hide an item from normal active operation without rewriting history by soft-deleting a rumor, quest, questline, or repeatable quest.
+
+Use when: Use this when work should disappear from active reads while preserving historical truth.
+
+Not for: Do not use this when you mean to archive a questline or repeatable quest while keeping it visible as retired structure.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | hide. The retirement action to perform. |
+| target | object | yes | The target to hide. |
+| deletedAt | integer | no | Optional timestamp to record when the item became hidden. |
+
+## Workflow guides
+
+- [archive-delete-and-prune](references/archive-delete-and-prune.md): Choose the right retirement action for each kind of work so history stays honest and hiding does not get confused with archival or terminal execution truth.
+- [choose-work-shape](references/choose-work-shape.md): Choose the right structure for new work by separating uncertainty, one-shot execution, multi-step arcs, and recurring patterns.
+- [clarify-ambiguous-requests](references/clarify-ambiguous-requests.md): Treat ambiguity as a real state, capture uncertainty honestly, and only commit work structure once the next executable shape is clear.
+- [close-work-and-claim-outcomes](references/close-work-and-claim-outcomes.md): Close work with the correct terminal lifecycle action, then handle any concrete reward claim as a separate explicit step.
+- [create-concrete-quest](references/create-concrete-quest.md): Create real, bounded executable quests only when the objective is concrete enough to execute without interpretive guesswork.
+- [detect-slips-and-staleness](references/detect-slips-and-staleness.md): Detect work that is slipping or going stale by reading overdue, deferred, in-progress, and related operational views before choosing one recovery move.
+- [escalate-and-unblock](references/escalate-and-unblock.md): Diagnose blockers honestly, then remove or realign hard gates when the model is wrong instead of treating every delay as generic escalation theater.
+- [frame-initiative-questline](references/frame-initiative-questline.md): Use questlines for shared initiative context, then attach concrete quests and maintain the structure without confusing one quest with one arc.
+- [handle-exceptions-and-weird-cases](references/handle-exceptions-and-weird-cases.md): Handle weird cases by diagnosing the actual tool outcome, routing into clarification or recovery when needed, and refusing to fake a clean normal-state story.
+- [intake-triage](references/intake-triage.md): Triage new asks, ideas, and vague incoming work into the right next step without prematurely committing execution structure.
+- [maintain-clear-ownership](references/maintain-clear-ownership.md): Keep ownership explicit through quest content and classification because Questlog does not provide a separate assignee field or ownership tool.
+- [manage-approvals-and-promises](references/manage-approvals-and-promises.md): Treat approvals and commitments as modeled work with timing and dependencies instead of burying them as vague narrative promises.
+- [plan-successor-work](references/plan-successor-work.md): Create explicit successor work after closure by spawning follow-ups or shaping new work, while keeping uncertain next steps in intake instead of faking certainty.
+- [plan-time-correctly](references/plan-time-correctly.md): Use quest planning fields honestly so availability, due pressure, and schedule intent stay meaningful instead of getting collapsed into one generic date.
+- [prioritize-across-streams](references/prioritize-across-streams.md): Prioritize across competing work streams by reading real candidate sets, distinguishing available from blocked work, and then reflecting the choice in planning.
+- [protect-capacity-and-focus](references/protect-capacity-and-focus.md): Protect capacity and focus by reading the real in-progress and scheduled-now load, then using planning to rebalance instead of silently overcommitting.
+- [recover-from-modeling-mistakes](references/recover-from-modeling-mistakes.md): Recover from modeling mistakes by diagnosing the exact current state first, then applying the smallest honest corrective tool instead of rewriting history blindly.
+- [report-status-and-manage-expectations](references/report-status-and-manage-expectations.md): Build status reporting from the real questlog state, separating available, blocked, in-progress, slipping, and resolved work without relying on memory.
+- [revise-or-reshape-commitment](references/revise-or-reshape-commitment.md): Revise a quest objective before execution starts, but reshape commitments honestly with lifecycle tools once real execution history exists.
+- [run-operational-review](references/run-operational-review.md): Drive daily or weekly operational review from structured list views, then move from diagnosis into actual planning or execution changes.
+- [run-recurring-rhythms](references/run-recurring-rhythms.md): Model recurring work as repeatable definitions that spawn fresh concrete quests over time instead of living forever as one immortal task.
+- [search-and-retrieve-context](references/search-and-retrieve-context.md): Find relevant questlog context quickly, then switch from discovery to exact inspection without confusing free-text search with structured review surfaces.
+- [sequence-with-unlocks](references/sequence-with-unlocks.md): Model hard sequencing with unlocks between concrete quests so blocked and available work stay truthful and reviewable.
+- [settle-rumor-into-structure](references/settle-rumor-into-structure.md): Turn a ready rumor into committed quest or questline structure without losing provenance or pretending vague intake is settled.
+- [tag-and-filter-portfolios](references/tag-and-filter-portfolios.md): Use tags for cross-cutting classification and portfolio filtering without confusing tags for status, timing, or dependency modeling.
+
+## Principles
+
+- Store the least committed truth first.
+- Read before you prescribe.
+- Protect history when reality changes.
+- Close the last mile, not just the main work.

package/skills/questlog/references/archive-delete-and-prune.md

@@ -0,0 +1,25 @@
+# Archive Delete And Prune
+
+Primary tools:
+- `shape_work`
+- `organize_work`
+- `manage_repeatable`
+- `retire_work`
+- `run_quest`
+
+Steps:
+1. Use `shape_work` to dismiss rumors when intake should be retired without becoming committed work.
+2. Use `organize_work` to archive questlines when the arc is complete but should remain visible as retired structure.
+3. Use `manage_repeatable` to archive repeatable definitions when they should stop spawning future work.
+4. Use `retire_work` to hide items when they should disappear from active operation while preserving history.
+5. Use `run_quest` to abandon real committed work instead of hiding it when the truthful record is that the work ended unsuccessfully.
+
+Outcome handling:
+- Treat `success` as confirmation that the right retirement path happened.
+- Treat `no_op` from repeated hide as confirmation that the item is already retired that way.
+- Treat `error` as a sign that the target or retirement mode is wrong.
+
+Failure handling:
+- Do not soft-hide committed execution work just to make dashboards look tidy.
+- Do not confuse archive with hide.
+- Do not use `manage_repeatable` for hiding repeatables now that `retire_work` is the canonical hide path.

package/skills/questlog/references/choose-work-shape.md

@@ -0,0 +1,25 @@
+# Choose Work Shape
+
+Primary tools:
+- `capture_rumor`
+- `shape_work`
+- `manage_repeatable`
+- `inspect_questlog_item`
+
+Steps:
+1. Use `capture_rumor` when the work is still uncertain, interpretive, or politically fuzzy.
+2. Use `shape_work` with `create_quest` when there is one concrete executable step with one honest objective.
+3. Use `shape_work` with `create_questline` when several related quests need shared initiative context.
+4. Use `manage_repeatable` with `create` when the work is a cadence that should spawn fresh quests over time.
+5. Use `shape_work` with `settle_rumor` when a rumor is ready to graduate into committed quest or questline structure.
+6. Use `inspect_questlog_item` after creation when you need to confirm the chosen shape before planning or execution.
+
+Outcome handling:
+- Treat `success` as confirmation that the chosen shape now exists in the system.
+- Treat `needs_clarification` as a sign that the shape choice is still incomplete and should not be guessed.
+- Treat `error` as a sign that the requested shape or inputs are invalid as entered.
+
+Failure handling:
+- If the work feels both vague and actionable, keep it as a rumor until one executable step is truly obvious.
+- Do not create a repeatable just because something happened twice.
+- Do not force a questline when one real quest would be enough.

package/skills/questlog/references/clarify-ambiguous-requests.md

@@ -0,0 +1,24 @@
+# Clarify Ambiguous Requests
+
+Primary tools:
+- `capture_rumor`
+- `search_questlog`
+- `inspect_questlog_item`
+- `shape_work`
+
+Steps:
+1. If the request is still ambiguous, use `capture_rumor` instead of forcing it into a quest too early.
+2. Use `search_questlog` when the ambiguity might really be duplicate or overlapping work instead of net-new intake.
+3. Use `inspect_questlog_item` when you need the exact current state of the intake item before deciding how to commit it.
+4. Once the missing outcome or structure is clear, use `shape_work` with the smallest honest action: `create_quest`, `create_questline`, or `settle_rumor`.
+5. If `shape_work` returns `needs_clarification`, answer the missing branch choice before retrying. Do not guess between quests and questlines.
+
+Outcome handling:
+- Treat `success` as a valid clarification milestone or committed structure change.
+- Treat `needs_clarification` as expected when the system can see that the request is valid in spirit but still underdetermined.
+- Treat `error` as a real contract or state problem that must be repaired before continuing.
+
+Failure handling:
+- If someone wants speed without clarity, record the uncertainty as intake and move forward honestly.
+- If several plausible existing items match, stop at clarification instead of choosing one silently.
+- Do not fabricate a crisp quest objective just to make the system look tidy.

package/skills/questlog/references/close-work-and-claim-outcomes.md

@@ -0,0 +1,23 @@
+# Close Work And Claim Outcomes
+
+Primary tools:
+- `run_quest`
+- `reward_work`
+- `review_questlog`
+- `inspect_questlog_item`
+
+Steps:
+1. Use `run_quest` with the correct terminal action: `finish` for successful completion or `abandon` when the work did not land.
+2. Use `inspect_questlog_item` or `review_questlog` when you need to confirm the exact post-resolution state.
+3. If rewards exist, use `reward_work` with `action: "claim"` as a separate follow-up step.
+4. Accept `no_op` on repeated reward claim as confirmation that the outcome was already claimed.
+
+Outcome handling:
+- Treat `success` as a real terminal lifecycle step or reward claim.
+- Treat `no_op` on claim as valid confirmation, not as a failure.
+- Treat `error` as a real invalid-state problem that needs diagnosis before retrying.
+
+Failure handling:
+- Do not treat quest finish and reward claim as one hidden operation.
+- Do not leave reward claim ambiguous after successful closure when the reward matters.
+- Do not close work with a fake success outcome when it should be abandoned instead.

package/skills/questlog/references/create-concrete-quest.md

@@ -0,0 +1,21 @@
+# Create Concrete Quest
+
+Primary tools:
+- `shape_work`
+- `inspect_questlog_item`
+- `plan_quest`
+
+Steps:
+1. Use `shape_work` with `action: "create_quest"` only when there is one clear executable objective.
+2. Put shared arc context in a questline, not inside a bloated quest objective.
+3. Use `inspect_questlog_item` after creation when you need to confirm the exact quest detail that was created.
+4. Use `plan_quest` later for timing or estimate refinement instead of overloading creation with every downstream decision.
+
+Outcome handling:
+- Treat `success` as confirmation that a concrete quest now exists.
+- Treat `error` as a sign that the requested quest input is invalid and should be repaired before retrying.
+
+Failure handling:
+- If the objective still needs interpretation, go back to intake or clarification instead of creating the quest.
+- If the work is really multi-step, use questline structure instead of one overloaded quest.
+- Do not create a quest whose title and objective hide uncertainty.

package/skills/questlog/references/detect-slips-and-staleness.md

@@ -0,0 +1,22 @@
+# Detect Slips And Staleness
+
+Primary tools:
+- `review_questlog`
+- `inspect_questlog_item`
+- `plan_quest`
+- `run_quest`
+
+Steps:
+1. Use `review_questlog` to look at overdue, due-soon, deferred, in-progress, or missed-scheduled views.
+2. Use `inspect_questlog_item` when one slipping item needs exact diagnosis before action.
+3. If the problem is timing drift, use `plan_quest` to repair the planning state.
+4. If the problem is execution drift, use `run_quest` for the next real lifecycle move.
+
+Outcome handling:
+- Treat empty stale-work views as valid `success`.
+- Treat `error` as a bad view or filter choice, not as evidence that the work is healthy.
+
+Failure handling:
+- Do not call work healthy just because it is still open.
+- Do not change timing blindly before you inspect the exact item.
+- Do not assume a stale item is blocked; diagnose it first.

package/skills/questlog/references/escalate-and-unblock.md

@@ -0,0 +1,22 @@
+# Escalate And Unblock
+
+Primary tools:
+- `review_questlog`
+- `inspect_questlog_item`
+- `organize_work`
+- `plan_quest`
+
+Steps:
+1. Use `review_questlog` to confirm whether work is actually blocked.
+2. Use `inspect_questlog_item` to diagnose the exact blocker on the affected quest.
+3. If the unlock graph is wrong, use `organize_work` to remove or replace the blocker set.
+4. If the work is not truly blocked, use planning changes instead of fake escalation language.
+
+Outcome handling:
+- Treat `success` as a real unblock step.
+- Treat `error` as a structural issue that still needs diagnosis.
+
+Failure handling:
+- Do not call work blocked when it is only unclear or underspecified.
+- Do not leave a quest in the blocked state after the model has changed.
+- Do not remove prerequisites casually; inspect before unblocking.

package/skills/questlog/references/frame-initiative-questline.md

@@ -0,0 +1,23 @@
+# Frame Initiative Questline
+
+Primary tools:
+- `shape_work`
+- `organize_work`
+- `review_questlog`
+- `inspect_questlog_item`
+
+Steps:
+1. Use `shape_work` with `create_questline` when several related quests need one umbrella initiative.
+2. Use `shape_work` with `attach_quest_to_questline` or `detach_quest_from_questline` to place concrete quests correctly inside the initiative.
+3. Use `organize_work` to update questline fields or archive the questline once the arc is truly retired.
+4. Use `review_questlog` and `inspect_questlog_item` to verify the initiative health and exact structure.
+
+Outcome handling:
+- Treat `success` as a real questline or membership change.
+- Treat `no_op` as confirmation that the quest was already attached or detached as requested.
+- Treat `error` as a sign that the target ids or structural state are invalid.
+
+Failure handling:
+- Do not create a questline for one isolated executable task.
+- Do not leave membership implied; attach or detach quests explicitly.
+- Do not archive a questline just to hide active work that still matters.

package/skills/questlog/references/handle-exceptions-and-weird-cases.md

@@ -0,0 +1,24 @@
+# Handle Exceptions And Weird Cases
+
+Primary tools:
+- `inspect_questlog_item`
+- `search_questlog`
+- `review_questlog`
+- then the nearest corrective tool such as `shape_work`, `organize_work`, `plan_quest`, or `run_quest`
+
+Steps:
+1. Start with diagnosis, not mutation. Use `inspect_questlog_item`, `search_questlog`, or `review_questlog` depending on what is actually unknown.
+2. If the tool returns `needs_clarification`, stop and answer the missing branch instead of guessing.
+3. If the tool returns `error`, read the recovery guidance and choose the next corrective tool deliberately.
+4. Only mutate state after the weird case has been made specific enough to model honestly.
+
+Outcome handling:
+- Treat `success` as a real answer, even if that answer is an empty review view.
+- Treat `no_op` as signal that the requested change was already true.
+- Treat `needs_clarification` as expected when the system can enumerate the ambiguity safely.
+- Treat `error` as a structured boundary, not as a cue to improvise around the rules.
+
+Failure handling:
+- Do not force a weird case into a fake normal flow just to keep moving.
+- Do not guess among multiple plausible targets.
+- Do not mutate first and inspect later.

package/skills/questlog/references/intake-triage.md

@@ -0,0 +1,25 @@
+# Intake Triage
+
+Primary tools:
+- `search_questlog`
+- `capture_rumor`
+- `inspect_questlog_item`
+- `shape_work`
+
+Steps:
+1. Start with `search_questlog` when the ask might duplicate existing work. Use `mode: "identify_one"` when you need one exact target instead of a browse list.
+2. If the work is still vague, risky, or under-specified, use `capture_rumor` with only the minimum facts that explain what arrived and why it matters.
+3. Use `inspect_questlog_item` on the returned rumor id when you need to confirm the intake record before deciding what to do next.
+4. Use `shape_work` for the next honest transition: `dismiss_rumor`, `reopen_rumor`, or later `settle_rumor`.
+5. If the ask is already clearly executable, hand off to `shape_work` with `create_quest` or `create_questline` instead of letting it rot in intake.
+
+Outcome handling:
+- Treat `success` as a usable search or intake result.
+- Treat `no_op` as confirmation that the rumor is already in the requested state.
+- Treat `needs_clarification` from `search_questlog` as a stop signal: choose among the returned candidates instead of guessing.
+- Treat `error` as a cue to repair the query or target before continuing.
+
+Failure handling:
+- If the ask is urgent but unclear, still capture it first instead of inventing execution detail.
+- If similar work already exists, reuse or update that thread instead of creating parallel intake.
+- Do not create a quest just because someone asked for something.