@canhta/dsh-autopilot 0.1.0-alpha.1

package/docs/specs/execution.md

@@ -0,0 +1,65 @@
+# DSH execution
+
+## Ownership and composition
+
+Use a normal external Cordis plugin/bundle and supported DSH profile launch. Keep Autopilot scheduling and durable run state on the Host. Load its browser contribution only for Web presentation. Compose DSH Agent/Session, preset/skill, tool and model services through their public APIs. Same-process execution does not require an SDK subprocess, and optional process isolation must satisfy the same pause/continuation requirements.
+
+Packaging and effect lifecycle are owned by [plugin engineering](plugin.md).
+
+## Unattended execution safeguards
+
+Compose the selected DSH permission/sandbox and tool-guard facilities as part of the execution preset. Verify the effective composition rather than mounting duplicate guards already supplied by a bundle. Deployment policy selects allowed capabilities and limits; target-repository instructions still select coding and verification work.
+
+Exercise denied writes to unauthorized paths and publication attempts outside the designated executor through every enabled tool path, including MCP and child agents. Declare the actual writable roots, including any provider temporary-directory allowances. Permission presets select policy; enforcing providers apply it, and MCP servers do not automatically inherit a local filesystem sandbox. A permission label, hidden tool or prompt instruction is not proof of enforcement. If a tool needs human authorization that unattended operation cannot obtain, report the condition through the existing tracker-blocker flow; never grant itself broader permissions to finish.
+
+Preserve native repeated-call guidance where appropriate and configure supported per-tool deadlines. Advisory loop reminders do not enforce credit caps; cooperative timeouts do not prove an unresponsive process stopped. Reuse the capability's termination path, keep the run's pause pending until quiescent, and test tools that ignore cancellation. These strengthen the existing budget/pause requirements rather than introduce a separate watchdog framework.
+
+## Execution requirements
+
+The selected DSH composition plus Autopilot's domain integration must support isolated worktrees, durable Session reconstruction after a real Host restart, quiescent pause, continuation with side-effect reconciliation, structured outcomes, supported usage interception, and headless operation. Implementation and test progress belongs to the corresponding GitHub issue.
+
+A checkpoint preserves continuation information, not OS process memory. Account for every enabled child/tool lifetime before releasing capacity, flush durable Session data, and reconcile interrupted effects before repetition. Verify cwd routing and the selected sandbox separately; a worktree is not an access-control boundary.
+
+## Conceptual execution interface
+
+These are required data exchanges, not proposed public DSH method names. Keep actual integration code private until the selected DSH API is verified.
+
+**Proposed implementation:** a run-scoped report tool composed through DSH's typed tool registry and native outcome facilities. Treat its validated payload as evidence input, not permission to publish. A failed enclosing tool/PTC call cannot seal successful completion; settle execution, confirm durable evidence and revalidate Git state through the existing publication gate. Preserve root ownership and use public APIs rather than a private subagent output helper.
+
+| Input | Required facts |
+| --- | --- |
+| Run identity | Run/attempt identifiers and immutable configuration revision |
+| Issue snapshot | tracker identity, title, approved scope, designated Brief comment identity/version, relevant context and dependencies |
+| Workspace | Exact registered worktree, target repository and branch/base identity |
+| Execution context | Configured DSH preset/skills and a reference to applicable repository instructions |
+| Continuation | Existing Session identity, checkpoint and any newly authorized tracker answers |
+| Resource policy | Enforced spending authorization and supported limits; credential values stay outside prompts |
+
+| Outcome | Required facts |
+| --- | --- |
+| verified | Change summary, acceptance-criteria evidence, verification commands/results, skips and reasons, exact Git state evaluated, suggested PR description |
+| blocked | Blocker category, evidence, questions, suggested human action, continuation context |
+| failed | Error category, relevant evidence, recoverability information, last known completed action |
+| paused | DSH continuation reference, interrupted/pending operations, quiescence evidence |
+
+A turn ending normally is insufficient proof of verified work. Missing or malformed outcome data requires explicit handling; never turn arbitrary final prose into a success flag. Revalidate that the published code matches the verified state, including untracked files and final commit state.
+
+## Target repository and Autopilot context
+
+Compose the existing repository-instruction loader and configured skill catalog/loading tools in the run's DSH preset. The run agent reads the target repository's instructions and selects appropriate checks. Autopilot does not store a project-wide substitute list of lint/test commands or implement another skill parser, catalog, discovery system or installation manager. An explicit repository skip or exception can be reported with its evidence; an unexplained failed required check cannot become verified success.
+
+Supply the approved Agent Brief as the execution scope. Supporting comments are context and human answers, not unrestricted instructions to change scheduling, credentials or publication policy. Keep all model-visible injected material reconstructable in the DSH Session through supported logging.
+
+Use the Autopilot handoff pattern: approved brief, bounded execution, evidence-based verification, structured blocker questions, and human readiness after clarification. Avoid depending on a developer's private skill path; any packaged skills must be redistributable and their inputs documented.
+
+The `ask-matt` flow informs this handoff: self-contained implementation work, explicit blocking dependencies, and review against both repository standards and the approved scope. Adapt tracker interactions to the selected provider’s comments and dependency links. It is a process reference, not a runtime dependency or permission to impose its TDD/skill stack on every target repository. Autopilot does not generate a parallel code-host issue backlog.
+
+## Delegation
+
+Start with one root execution per tracker run. Autopilot owns run concurrency; DSH owns how enabled agent tools perform the task. Agent delegation is optional and controlled through supported preset/tool configuration. Use existing workflow/subagent services for enabled in-task scripting and delegation; they do not replace the durable ticket-admission queue. Do not build a second team planner, workflow interpreter or DAG scheduler.
+
+If child agents are enabled, their usage, worktree access, pause and shutdown must belong to the parent run. If the integration cannot observe or stop descendants or account for their usage, disable that delegation configuration rather than claiming its limits apply. Subagent tooling present in a repo does not override deployment enforcement.
+
+## Acceptance
+
+Demonstrate two isolated roots, actual Host restart during execution, same-Session continuation, active-tool/descendant quiescence, persistence failure, validated outcomes tied to Git state, and pre-request usage authorization for each enabled request category. Retain reusable tests in the implementation; record execution results on GitHub.

package/docs/specs/integrations.md

@@ -0,0 +1,89 @@
+# Integrations
+
+## Tracker input and human decisions
+
+Read only the configured project's candidates and their required context: stable issue identity, display key, summary, priority, labels, status, comments, dependency links and revision/change history needed for admission. Outbound tracker access goes through the configured official MCP deployment; that deployment owns its OAuth, app, PAT or API-token authentication and transport. Autopilot settings name the MCP namespace and domain mappings, never a second outbound credential.
+
+Receive authenticated tracker webhooks and run scheduled/startup reconciliation. Verify authenticity using the supported mechanism for the configured webhook type. Persist enough ingress information before acknowledging acceptance; fetch current tracker state instead of trusting an old event snapshot. Filter project/label locally as needed when webhook subscription filters cannot express the rule.
+
+Use existing DSH Host routing and suitable ingress adapters. Provider-specific verification and Autopilot admission durability remain required; do not create an independent HTTP server merely to receive events.
+
+Treat provider-qualified tracker delivery IDs as ingress retry identifiers, not complete run uniqueness keys. Use the shared [admission policy](lifecycle.md) for all sources. Invoke only the exact tools declared by the selected provider, bound to one live DSH tool generation; never ask a model or discovery tool to choose admission operations. Paginate candidates and nested evidence under byte/page/item bounds. A tracker update timestamp alone cannot prove a human readiness transition. Normalize vendor-specific facts through the selected provider; never call MCP tools or vendor clients from core admission.
+
+GitHub and Jira must satisfy the exact same-namespace toolsets owned by [provider architecture](providers.md). A missing readiness, dependency or changelog capability makes the provider unavailable; there is no REST/PAT fallback. A schema change or DSH `tools/change` withdraws the current provider generation before later reconciliation may remount it.
+
+The DSH ToolRuntime must expose Host root calls in global `native` or `both` mode. PTC-only accepts only `run_code` at the root and is therefore not a supported tracker deployment until DSH provides a trusted Host-programmatic call path.
+
+## Agent Brief convention
+
+**Proposed implementation:** identify the executable comment with a visible `Agent Brief` heading and a versioned marker such as `dsh-autopilot:brief:v1`. Select one designated comment deterministically and preserve its id, update time and content digest for the run. If multiple comments make the current brief ambiguous, report the ambiguity rather than guessing.
+
+Required semantic fields: objective, in-scope work, acceptance criteria, constraints, and relevant context. A checklist must be testable by the executing agent. The brief may reference target-repo rules; it need not copy build/test commands. Target routing follows explicit configuration.
+
+A material brief edit while work is active requires re-evaluation; approval of one scope is not approval of arbitrary subsequent edits. On blocker resume, provide the new human answers alongside the original run history.
+
+## Tracker output
+
+Update only configured agent labels and authorized status transitions. Preserve unrelated labels and fields. The configuration interface is owned by [operations](operations.md); projection semantics are below.
+
+| Event | Tracker output |
+| --- | --- |
+| Start | Brief acknowledgement linking the run and describing work started |
+| Blocked | Evidence, numbered questions, exact human action needed to resume, run link |
+| Operational pause | Pause reason and continuation condition; deduplicate repeated unchanged reports |
+| Failed | Failure summary, evidence and available next action |
+| Completed | PR link, change summary, verification evidence, cost/usage qualification; transition to configured In Review |
+
+Agent-authored comments clearly identify their origin, for example `Generated by dsh-autopilot (AI-assisted execution).` Include a stable run/event marker so uncertain writes can be reconciled. Keep reports bounded and link to details; never paste raw logs or secrets by default.
+
+Apply the [lifecycle authorization policy](lifecycle.md#human-readiness-authorization) to tracker inputs. Configure dependency-completed states and the review-state mapping for the actual tracker workflow. A missing transition is a visible integration problem; do not invent a tracker workflow or mark Done.
+
+## Tracker projections
+
+Default semantic label names (resolve to provider-specific IDs where required): `ready-for-agent`, `agent-queued`, `agent-implementing`, `agent-paused`, `agent-blocked`, `agent-failed`, `agent-completed`. Keep internal pausing/publishing/cancelled details in the run record unless an operator configures additional mappings. Operational pause reasons share `agent-paused`; they do not require a new label per reason. Label mutations preserve unrelated tracker labels.
+
+**Proposed readiness projection:** retain the ready label during queue/execution/operational pause, alongside one current agent-state label. Remove it on human blocker and terminal outcomes. A new human ready transition authorizes blocker continuation or a new execution after a terminal run; repeating the current state does not. Persist the consumed readiness generation so failed tracker label delivery cannot cause re-admission.
+
+Append-only reports and mutable label/status projections are distinct intents. Serialize mutable projections per provider-qualified issue and attach run revision, readiness generation and desired-state identity. Before dispatch or retry, re-read the current run and required tracker evidence; supersede older intents instead of replaying historical states. Never resend an obsolete readiness-label removal after a newer human transition. Report comments retain their original event identity/time and must not masquerade as current-state commands.
+
+Use remote conditional writes where supported. A local queue alone cannot fence independent remote actors: if a provider cannot establish safe ordering after an uncertain in-flight write, stop that projection and expose a conflict requiring reconciliation and, when authorization is ambiguous, a fresh human transition. Do not silently restore readiness on the human’s behalf. Recheck unrelated fields and preserve them. Correct missing label/status mappings through the audited [delivery repair](operations.md#repairing-a-broken-delivery-mapping) operation.
+
+## Code-host publication
+
+Only the plugin-authorized publication path may create a PR for a run. Select one executor in the publication issue before implementation. Respect target-repo commit conventions and code host PR templates without moving those conventions into Autopilot policy.
+
+Persist the intended repository, base, head branch and run identifier before pushing or creating the PR. Confirm verification applies to that exact code. Create one ready-for-review PR with tracker linkage, change summary and verification evidence. Do not create an early Draft PR.
+
+After ambiguous responses or a crash, query the configured repository and head branch/run marker before retrying creation. A found PR must match the intended repository/base/head association. Persist its identity and URL, then invoke the [completion transition](lifecycle.md). An existing unrelated or closed PR is a conflict to resolve, not permission to silently reuse it or open duplicates.
+
+Prefer official MCP-backed code-host adapters where their live contracts pass conformance. The official MCP deployment owns its credentials with only the required repository permissions. GitHub and Bitbucket remain independent implementations of the shared code-host interface even when Bitbucket uses the same Atlassian MCP identity as Jira; issue links do not determine the code-host provider. Missing repository access or branch protection rejection is a publication error, not an invitation to weaken code-host settings.
+
+Code-host CI repair/review/merge are outside v1 execution. Maintenance may read current PR disposition solely for [cleanup eligibility](operations.md).
+
+## Notification delivery
+
+Support tracker comments, generic webhook and ntfy through the provider services in [provider architecture](providers.md). Tracker blocker reporting is part of the human feedback protocol; supplemental notification channels are configurable. Define event/channel subscriptions for started, blocked, paused, failed and completed outcomes. Avoid polling heartbeats as user notifications by default.
+
+Version outbound payloads. Include event id, run id, timestamp, event type, provider-qualified issue identity and display key/link, user-readable summary, action needed, run URL, and PR URL when available. Usage fields distinguish estimates from provider values. Summary disclosure and destination are explicit channel configuration; browser presentation receives redacted destination information.
+
+Persist outbound intents with the corresponding run transition. Track destination, status, attempts, next retry, redacted last error and delivery receipt. Bound timeouts/retries; honor provider retry guidance and distinguish retryable failures from permanent rejection. Exhausted delivery remains visible and can be retried by an operator.
+
+Delivery is at least once across uncertain external acknowledgements. Reuse stable event IDs; use recipient deduplication when supported. Do not claim exactly-once notifications across arbitrary webhook/ntfy receivers. Failure in one channel does not prevent others from receiving the event.
+
+## Provider evidence
+
+Jira Cloud currently informs the Jira provider; resolve other Jira editions through the provider connection issue. Shared conformance and extension requirements for Jira, GitHub Issues, future Linear and future Bitbucket integrations belong to [provider architecture](providers.md). A provider must preserve all shared behavior, not merely expose a vendor tool with a similar name.
+
+## Acceptance scenarios and references
+
+- Delayed blocked/start/completed projections are superseded rather than overwriting current labels or newer human readiness.
+- Duplicate webhook and search results converge on one admitted run.
+- A human reply without readiness transition cannot resume a blocker.
+- Tracker status mapping failure leaves a visible pending/failed delivery after PR completion.
+- A lost code host response reconciles the created PR before retry.
+- Restart with pending notifications preserves deliveries and stable event IDs.
+- Tests inspect redacted payloads; credentials and full webhook tokens never appear in logs or browser responses.
+
+Primary sources: [Atlassian MCP supported tools](https://support.atlassian.com/atlassian-ai-gateway/docs/supported-tools/), [GitHub MCP server](https://github.com/github/github-mcp-server), [Jira webhooks](https://developer.atlassian.com/cloud/jira/platform/webhooks/), [GitHub webhook validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), [ntfy publishing](https://docs.ntfy.sh/publish/).
+
+Community reference: [dsh-notify-center](https://github.com/SingleOne/dsh-notify-center) for event filters and redacted settings. Its documented memory-only queue does not meet Autopilot's persistence requirement.

package/docs/specs/lifecycle.md

@@ -0,0 +1,81 @@
+# Run lifecycle
+
+## Admission
+
+Webhook events, periodic reconciliation, startup reconciliation, and an operator reconciliation request enter the same admission path. A manual reconciliation does not bypass policy.
+
+An issue is eligible only when it belongs to the configured project, carries the configured ready label, has a valid designated Agent Brief, and all provider-resolved blocking dependencies are completed under the configured status mapping. Snapshot these facts and recheck them before dispatch.
+
+Persist admission and claim together so a ticket has at most one unfinished run. The configured queue capacity limits admitted waiting work. **Proposed implementation:** leave eligible overflow issues in tracker ready state, expose the capacity reason, and reconsider them during reconciliation.
+
+Event delivery identifiers deduplicate ingress retries. Run uniqueness additionally uses provider-qualified issue identity and a persisted readiness generation; unrelated issue edits must not create fresh runs. Authorization for each generation follows the human-readiness rules below.
+
+## Human readiness authorization
+
+Require an attributable human ready transition after a blocker and for any new readiness generation. A comment, current label snapshot or bot-authored update alone cannot establish it. Reject known automation and unknown attribution. Where a tracker cannot distinguish human activity from user-token automation, require a documented trusted-actor deployment assumption; do not claim technical proof of a person. Quiesce or reconcile older readiness-mutating intents before accepting a new generation; unresolved ordering remains an explicit integration conflict. Provider evidence fields are defined in [providers](providers.md), and mutation ordering in [integrations](integrations.md).
+
+## State transitions
+
+| State | Meaning | Permitted next states |
+| --- | --- | --- |
+| queued | Admitted continuation or new work waiting for dispatch | implementing, publishing for a verified publication continuation, paused, blocked, cancelled |
+| implementing | DSH executing; its reported phase is metadata | pausing, blocked, publishing, failed |
+| pausing | Pause requested; execution not yet proven quiescent | paused, blocked, failed |
+| paused | Durable continuation state retained; no execution active | queued, blocked, cancelled |
+| blocked | Requires a human tracker change | queued after authorization, cancelled |
+| publishing | Verified local outcome accepted; PR handoff in progress | completed, paused at a recoverable boundary, failed |
+| completed | PR identity confirmed and persisted | Terminal |
+| failed | Execution or publication cannot progress under its bounded policy | Terminal; later explicit retry requires a linked attempt/run policy |
+| cancelled | Operator ended the run | Terminal |
+
+Planning, implementation, and verification can be displayed as DSH-reported phases. They are not separate model loops owned by Autopilot. A failed run is not automatically restarted indefinitely.
+
+## Queue and dispatch
+
+Ordering: eligible resumptions before new work; within each group, configured normalized tracker priority then oldest queue entry, followed by a stable identity tie-breaker. This means a resumption takes precedence over a higher-priority new issue; do not claim the reverse in UI copy.
+
+Dispatch requires scheduler admission to be enabled and inside its configured window, current tracker eligibility, available concurrency, and any required model-spending authorization in [operations](operations.md). Claiming a slot and recording dispatch must be serialized. Paused and blocked runs consume no execution slot after their execution has stopped.
+
+If eligibility changes while queued, do not start it. Record the reason and retain its history. Already-running work receives material tracker changes at a safe execution boundary; a human scope change cannot silently rewrite the snapshotted brief.
+
+## Pause and continuation
+
+Persist a continuation target (`implementing` or `publishing`) when pausing. A queued publication continuation reconciles the existing intent and verified Git state, then returns to publishing without starting another coding turn. If a matching PR is already confirmed, record its receipt before considering new side effects. A changed verified state requires explicit re-verification, not blind publication.
+
+Disabling the scheduler stops admission/dequeue and requests pause for active execution. Drain is a separate command: it stops new admission/dequeue while allowing current work to finish. Scheduler resume reconsiders paused runs through the ordinary gates; it cannot clear a tracker blocker or an unmet budget limit.
+
+A per-run Stop at checkpoint sets a durable operator hold. Global scheduler resume, budget reset and Host restart cannot clear that hold; only Resume paused run clears it and re-enters ordinary eligibility checks. Scheduler/budget pauses without an operator hold can resume automatically when their conditions permit.
+
+A pause is acknowledged only after execution and its owned child/tool processes have stopped or settled, DSH persistence is flushed, and the plugin checkpoint is saved. Keep the Session association and worktree. Record pause reason, last completed phase, pending actions, and any interrupted operation. Pausing a publishing run must first reconcile any in-flight external request.
+
+For work that already entered execution, verify the retained Session is readable, worktree ownership matches, Git state is usable, and tracker/PR state has not invalidated the work. Continue the same logical run and supported DSH Session. A missing previously allocated worktree or incompatible Session is an explicit recovery problem, not permission to start over silently. A new queued run paused before allocation has no Session/worktree to restore; persist its admission and hold instead.
+
+The DSH capability and interruption limitations are owned by [DSH execution](execution.md).
+
+## Blocker and failure
+
+A blocker outcome includes summary, evidence, concrete questions, and the human action needed. Stop execution, persist the blocker, schedule the tracker report and configured notifications, and release the slot after quiescence. Responses belong in tracker comments; only a human readiness change allows continuation.
+
+Separate transient integration delivery failure from execution failure. Retrying a tracker comment must not rerun coding. Notification failure must not remove a successfully published PR or change a completed execution to failed.
+
+The operator may cancel a queued, paused or blocked run once execution is quiescent. Retain its worktree, Session, consumed readiness generation and unresolved delivery/publication receipts. Cancellation is not tracker authorization and does not bypass reconciliation or cleanup policy. To cancel active work, first stop it at a checkpoint; never describe an unconfirmed stop as cancelled.
+
+## Completion and recovery
+
+Accept publication only after DSH returns a successful verified outcome tied to the work being published. Persist publication intent before external side effects. Confirm and store the PR before marking the run completed. Enqueue the final tracker transition/report and notifications durably; show pending or failed deliveries independently.
+
+Creating the PR finishes v1 execution. The tracker moves to its configured review state; people own completion of the ticket. Cleanup conditions are in [operations](operations.md).
+
+After a restart, reconcile unfinished runs before dispatch: compare the journal with DSH Session data, live-process ownership, Git worktrees/branches, and any pending PR publication. A host crash is not a clean pause. Persist the observed recovery result and resume only from a verified usable state. A second process must refuse to operate the same runtime store.
+
+## Acceptance scenarios
+
+- Duplicate webhook plus concurrent reconciliation admits one run.
+- An unrelated comment on a completed issue does not create another run.
+- A newly blocked queued issue never starts.
+- Disable scheduler during tool execution: state remains pausing until execution settles; no new run starts.
+- Enable scheduler: eligible paused work precedes new tickets and obeys remaining budget/capacity.
+- A reply comment without human readiness change leaves the run blocked.
+- Crash after PR creation but before receipt persistence: recovery locates that PR and does not create another.
+- Pause after Git push and before PR creation: resume reconciles publication without another coding turn.
+- Final tracker delivery fails: PR remains completed, delivery remains retryable, coding is not repeated.

package/docs/specs/operations.md

@@ -0,0 +1,89 @@
+# Operations
+
+## Scheduling and configuration
+
+Run one orchestrator in a supported DSH profile on one VPS. Persist schedule enabled state and operator changes on the Host. Admission has an explicit timezone, reconciliation cadence and optional allowed time windows. Window closure prevents new dispatch; the scheduler disable command has the pause semantics in [lifecycle](lifecycle.md). Show the next reconciliation and next allowed dispatch separately.
+
+Use startup reconciliation of current tracker state rather than replaying every missed polling tick as fresh work. Manual reconcile respects the same gates. Configure maximum running and queued workflows; these are separate limits. Reuse DSH timing facilities only where their scope fits global admission.
+
+Register one authoritative Autopilot configuration with DSH Settings and use its validation, precedence and revision-checked writes; preserve immutable per-run snapshots in run storage. Web edits and file-based deployment settings must show effective values. Operator edits affect future admission immediately; reductions to capacity do not kill existing work, while scheduler disable requests pause. Budget reductions stop additional spending authorization under the budget policy below. Record changes affecting active runs.
+
+Run snapshots preserve execution scope and integration interpretation, not permission to ignore current scheduler/budget restrictions. Reject ordinary changes to labels, Brief selection, dependency/review-state mappings or priority mappings while unfinished runs or unresolved intents use those mappings; explain the dependents in Settings. The delivery-repair operation below is the narrow exception. Credential rotation and safe operational limit edits remain available. Future-only execution settings do not silently replace the retained Session's preset/model configuration.
+
+| Configuration group | Required choices |
+| --- | --- |
+| Tracker | Provider binding, project scope, official MCP namespace, inbound-webhook credential reference, ready/state label mapping, Brief selection, completed/review status mapping |
+| Target | Code-host provider binding, one repository and base branch for the initial Jira Cloud + GitHub deployment; routing remains configuration-owned |
+| Scheduler | Enabled, cadence, timezone, allowed windows, running/queue limits |
+| Execution | Supported DSH version, preset, model route where needed, timeouts and delegation policy |
+| Budget | Enforcement mode, scope limits, warning threshold, accounting currency/units, pricing source/version, unknown-usage policy |
+| Notifications | Channels, event subscriptions, secret references, disclosure, retries/timeouts |
+| Storage | Runtime data/worktree roots, cleanup retention, history retention and backup location |
+
+Provider bindings and extension rules are owned by [provider architecture](providers.md). Provider-specific fields use their registered schemas. Official MCP configurations own outbound authentication; Autopilot credential references are only for capabilities it still owns, such as inbound webhook verification. Resolve priority ordering explicitly rather than comparing provider-native numbers.
+
+These are semantic configuration groups, not a final YAML schema. Validate references as soon as resolvable and reject invalid writes without replacing valid configuration. Store credentials through supported Host credential facilities, not in model-visible run snapshots.
+
+Tracker label defaults and projection behavior are owned by [integrations](integrations.md#tracker-projections).
+
+## Repairing a broken delivery mapping
+
+An operator may repair a failed mutable tracker projection when its remote label/status mapping is missing or invalid. Fence that issue’s projection worker and settle/reconcile any in-flight request first. Validate a replacement for the same semantic output in the same provider/project/issue; this operation cannot change approved execution scope, readiness authorization or target routing. Preserve the original mapping/revision and receipt history, retire the obsolete intent, and atomically persist a revisioned replacement intent using current lifecycle state. Preview the affected destination/state before confirmation. Re-run projection validation after any intervening issue/run change; never revive a superseded blocked/completed projection merely to make delivery succeed. This permits correcting a deleted review state after PR completion without rerunning code or rewriting prior run snapshots.
+
+## Credit and spending
+
+Autopilot enforces its own execution budget. Display provider account balance separately when a supported API exists. Account balance can change due to work outside Autopilot; it is not a per-run accounting ledger.
+
+Support deployment and per-run caps, with daily/monthly windows where configured. One tracker project does not require another project-budget hierarchy. Values and currency are operator configuration; no monetary defaults are approved.
+
+Reserve budget atomically before concurrent work can spend it. Count settled usage plus outstanding reservations against a cap. Charge all observable request usage for the run, including retries and enabled child agents; avoid double-counting reservation and settlement. Reset windows in the configured timezone without releasing obligations for requests still in flight.
+
+Enforcement must happen before model requests, not solely after expensive responses. A monetary hard-cap claim requires a conservative pre-request cost bound, including output limit and pricing, plus complete metering coverage. Otherwise expose the supported token/request cap or explicitly label the money limit as approximate. An unknown response cost is not zero; retain an appropriate reservation and stop new authorization until reconciled under policy.
+
+When budget becomes unavailable, request an operational pause, retain continuation state, and report the limiting scope. Automatic resumption requires restored budget and all normal dispatch gates. Raising a local limit does not top up the provider account. Warnings and pauses produce durable events, with unchanged notifications deduplicated.
+
+Use provider-reported token usage and a recorded pricing version for estimates. Preserve input/cache/output categories supported by the provider. Credential, provider and model changes cannot silently mix currencies or invent conversions.
+
+Reuse DSH request hooks, usage records and token categories for metering and authorization integration instead of replacing the LLM client. Cover conversation requests, retries, compaction, title generation and enabled children; map each to a run before authorization. Unowned model requests need an explicit deployment policy. Use those category definitions without double-counting; an estimate is not proof of a monetary upper bound.
+
+## Durable state
+
+Autopilot owns run metadata, admission/queue state, budget entries, operation intents, notification outbox, worktree ownership and audit. DSH continues owning Session persistence and configuration; Git owns repository state. Reuse DSH storage domains and a supported backend where their atomicity meets these requirements. Do not infer multi-record transactions merely because the backend uses SQLite.
+
+**Proposed implementation selection:** prove an atomic record model for state-plus-intent and concurrent budget reservation through the existing domain facility first. Evaluate bounded record size, query cost, recovery and retention, not just a happy-path write. If a requirement cannot fit, document the failing case before choosing a narrow transactional extension or Autopilot-owned store. Select one authoritative store for each datum; do not mirror writes into native and custom implementations. Enforce a single Host owner of the runtime store; no distributed coordinator.
+
+Persist enough information to reconcile external actions after a crash: issue identity/readiness generation, Brief snapshot, run/attempt ids, state/revision, queue ordering facts, configuration revision, DSH Session reference, worktree/base/head, pause/checkpoint, publication intent/receipt, usage/reservations, delivery records and operator actions. Avoid mirroring complete DSH logs into another database.
+
+Version durable records and schema. Never advance runtime state on a failed durable write. Backup the database together with the associated Session store and retained worktrees; recovery evidence must account for their consistency. Retention of execution history is independent from worktree deletion.
+
+## Worktrees and cleanup
+
+Allocate and register a worktree per run beneath the configured managed root. Use native Git operations through the supported DSH subprocess facility; reuse Workspace/Session association when the selected composition needs it, not as a replacement for Git ownership checks. Persist run ownership before dispatch. Preserve local changes across pause/restart, and distinguish managed, missing and orphaned worktrees. An orphan requires reconciliation before it is treated as disposable. Git paths and branch names must be derived from validated inputs, never executed as ticket-supplied shell text.
+
+Provide cleanup preview showing the exact managed worktree, associated run, branch, dirty/untracked files, unpushed commits, current PR disposition, removable disk usage and retained data. Refuse ordinary cleanup for active/queued/paused/blocked work, an open or unknown PR, dirty/untracked data, or commits not safely accounted for remotely. Do not turn a default cleanup button into force deletion.
+
+Auto-cleanup is enabled with configurable retention, initially seven days. **Proposed conservative implementation:** only merged PRs qualify automatically; calculate retention from a provider-proven merge time or the later durable first-observed-merged time when no authoritative timestamp is available. A generic last-updated timestamp is insufficient. Closed-unmerged PRs require manual evaluation of retained work. This narrows automatic deletion until a closed-PR policy is explicitly selected.
+
+Query code host disposition during maintenance to evaluate eligibility, without extending execution until merge. Recheck preview conditions immediately before removal to avoid deleting a worktree that resumed or changed. Use Git worktree operations; retain Session/run/audit data. Branch or remote-branch deletion is a separate policy, not implied by removing a worktree. Record cleanup outcome and notify when cleanup needs attention.
+
+## VPS and access
+
+Provide one tested Linux deployment recipe using a supported DSH profile with process supervision and durable storage. Select a single initial supervisor/container approach during implementation. Restart performs recovery before dispatch. The browser is not a scheduler host.
+
+Expose the Web UI through authenticated access and TLS using the supported DSH deployment model. One operator role has all application capabilities. Authentication can be provided by the deployment; identify the operator in audit when available, without introducing an account-management/RBAC subsystem. Protect state-changing requests through supported origin/authentication controls. Treat webhook ingress authentication independently of browser login.
+
+Use the verified access composition required by [plugin design](plugin.md). A deployment recipe requires end-to-end evidence against the pinned DSH version.
+
+Health reports distinguish process alive, store usable, recovery complete, integrations available and admission permitted. A healthy paused scheduler is not a failure. Logs carry run/event identifiers and sanitized errors; avoid ticket transcripts and credential values.
+
+## Acceptance scenarios
+
+- A deleted review state can be repaired after PR completion without blocking on its own failed delivery or restarting execution.
+- Competing dispatches cannot reserve the same remaining budget twice.
+- Missing usage stays unknown and cannot be shown as zero spending.
+- Budget reset during an in-flight request preserves its accounting obligation.
+- Closing the Web browser does not interrupt scheduled work.
+- A second Host using the same store refuses to dispatch.
+- Cleanup preview becomes stale after resume; deletion is rejected.
+- Completed run with open PR remains retained beyond seven days.
+- Merged, clean, remotely accounted work passes retention cleanup while its Session/report remains available.

package/docs/specs/plugin.md

@@ -0,0 +1,49 @@
+# Plugin engineering
+
+This page owns the proposed DSH plugin integration design. Verify upstream interface names against the selected DSH version and current public source. Required provider extensibility is owned by [provider architecture](providers.md).
+
+Implementation and verification follow [engineering standards](../engineering.md); this page owns Autopilot's DSH composition choices.
+
+## Reuse before implementation
+
+For each capability being implemented, identify the public DSH service or export, compose its provider and consumers, and verify the required behavior through the installed artifact. Autopilot owns ticket-to-PR policy and domain records, not the infrastructure used to execute that policy. A component or service name in these specs denotes a responsibility, not a mandate to write a new framework.
+
+Before introducing replacement infrastructure, record the exact missing behavior and source evidence on the implementation issue. First try supported configuration/composition or a narrow consumer adapter. If an upstream extension is needed, track it as a dependency; use one selected implementation, not parallel native/custom paths. Loading every DSH capability is not a requirement: select only what this deployment needs.
+
+## Cordis lifecycle
+
+- Export a plugin `apply(ctx)` and add a runtime `Config` schema when the plugin first accepts configuration. Use service injection for activation dependencies; YAML row order does not determine plugin startup order.
+- A missing required service leaves a consumer PENDING. Service withdrawal unloads dependent consumers; replacement remounts them. Startup readiness must detect missing required contributions instead of reporting a functioning scheduler merely because the process is alive.
+- Use stable patch row ids and distinctive Autopilot service/event names. The official `@deepseek-ai` npm scope belongs to upstream; this project uses the collision-safe owner scope `@canhta/dsh-autopilot`.
+- Cordis already owns listeners registered with `ctx.on` and child plugins registered with `ctx.plugin`. Acquire external timers, database handles, watchers and subscriptions through effect-owned lifetimes and return their disposers. Check a registry's registration contract before adding redundant cleanup.
+- Async disposers can overlap even though they start in reverse order. Put dependent shutdown operations in one awaited sequence: fence new work, settle/cancel owned execution, persist recovery state, then close the store. Unloading the plugin does not mean deleting its durable data.
+- Configuration edits can remount a plugin. Distinguish a scheduler pause command from disabling/unloading its Cordis row; lifecycle recovery must handle either without leaving duplicate pollers or dispatchers.
+- Type events through declaration merging and document their dispatch mode. `emit` does not await async persistence. Observer middleware must delegate with `next()`; deliberate budget vetoes must respect the intercepted interface's error/result contract.
+- Durable `turn/end` and `tool/result` records are Session event types, not same-named Cordis events. Observe them through `session/event` and inspect the record type.
+
+## Packaging and configuration
+
+Distribute a bundle declaring `dsh.bundle.patch` and exporting its Host code. A user profile owns the ordered bundle list and launch; create profiles through the DSH CLI. The standalone Cordis tutorial launcher teaches framework behavior and is not Autopilot's application entry point.
+
+Patch layers replace an entire row's `config`; they do not deep-merge keys. Schema defaults and Settings overrides are different mechanisms. Document effective configuration using those actual semantics. `!!js` applies only under config/disabled and is trusted deployment code, not a syntax for ticket-controlled input.
+
+The initial deployment follows the npm `latest` tag for DSH. Keep the runtime invocation tag-based; the plugin lockfile records its own build/test dependencies, while every artifact acceptance run records the exact DSH version resolved from `latest`. Do not add the complete DSH application as a plugin development dependency merely to lock that external runtime. Use explicit compatible dependency ranges, avoid `workspace:` dependencies or paths into a developer's upstream checkout, and follow package exports and declared Host/Client faces rather than unexported source paths.
+
+A Web package declares `dsh.client.platform: web`, exports `./client`, and builds the runtime's lazy factory registration format. Ordinary browser ESM output is insufficient at this baseline. Share the runtime's React/Cordis baseline; declare exact non-baseline externals. `dsh.client.inject` metadata is not runtime service injection.
+
+Git-source installs require self-contained built entry points, typically a `prepare` build subject to the installing profile's pnpm build policy. Packed npm/tarball distribution can supply prebuilt outputs. Test the packed artifact in an isolated profile outside the source checkout, including Host and Client entry resolution. Creating this GitHub repository does not publish an npm package.
+
+## Web and Host interface
+
+Register a root-scoped `main` panel keyed by the same id as its `sidebar.panellist` entry. Contribute one Settings editor through `settings.section` or the existing Plugins namespace-card slot; reuse the existing DSH shell and public components. An optional Session shortcut uses `conversation.session.header.actions`. Use `ctx.slots.inject` to wait for the slot declaration, not merely for the slots service. Effects must remove and restore contributions across unload/reload.
+
+Keep Host/Client type and build programs separated. A typed Remote requires generated Host descriptors, Client contribution output, and explicit Client mounting. Do not copy an upstream cookbook step that edits the monorepo's central Remote assembly into this external repository. A decorator alone does not expose the plugin's interface remotely.
+
+DSH supports typed unary and explicitly declared stream Remotes. Reuse Gateway transport, cancellation and reconnect handling; use its snapshot/journal helpers where the domain's event protocol fits. Autopilot supplies authorized queries/commands, revisions and domain-specific recovery semantics, not another RPC/WebSocket stack. An iterable alone does not declare a Remote stream. Select and test one update mechanism; bounded polling is acceptable when sufficient, not a required substitute for existing streaming.
+
+Use the Host Settings and credential facilities when the selected access mode supports them. Register Autopilot's schema and policy validation with Settings rather than implementing another configuration store. Keep credentials in the existing credential service and resolve them per operation; secrets are not durable run inputs.
+
+
+## Installation and access acceptance
+
+Validate packed installation outside the source checkout, effect cleanup/remount without duplicate registrations, headless hosting and actual DSH Web slot mounting. The selected VPS access path must authenticate reads/mutations, retain settings across restart, recover live state and reject unauthorized access. Tracker ingress authentication is independent. Test direct API exposure, credential/pairing revocation and transport unload/reload for the selected deployment. Validation progress belongs on GitHub.

package/docs/specs/providers.md

@@ -0,0 +1,62 @@
+# Provider architecture
+
+This page owns replaceable integration interfaces, tracker transport policy and live-validation limits. [Scope](scope.md) owns product responsibilities; [integrations](integrations.md) owns external behavior. Verify exact vendor MCP schemas against the installed official server before claiming conformance.
+
+## Composition
+
+Use ordinary Cordis Service Definition / Provider / Consumer roles. The scheduler consumes normalized provider services; admission, execution and Web never call vendor tools or branch on Jira versus GitHub. One deployment selects one tracker binding/project and one independent code-host binding.
+
+Tracker and code-host operations are MCP-first. The official GitHub or Atlassian MCP deployment owns vendor authentication and remote request transport; DSH's MCP client owns the MCP connection/reconnect lifecycle and publishes tools on `ctx.tools`. Autopilot invokes a closed set of exact semantic operations through `ctx.tools.execute()`, validates bounded machine-readable results and normalizes them into provider facts. It does not contain a second GitHub or Jira REST client, outbound PAT, email/API-token flow or generic vendor-request escape hatch.
+
+Raw webhook verification is the intentional exception. Autopilot receives the exact HTTP bytes and headers, resolves only the inbound webhook secret, verifies the provider signature and returns a provider-qualified delivery identity. MCP then reads current tracker state; webhook payloads are never admission truth.
+
+## Provider interface
+
+The current tracker interface is versioned; its write capabilities are an optional all-or-nothing pair:
+
+| Operation | Obligation |
+| --- | --- |
+| `readCandidates` | Enumerate one bounded page and fully hydrate each issue's comments, blocking dependencies and attributable readiness history. Continuation cursors are generation-local, authenticated and opaque. |
+| `verifyIngress` | Authenticate a bounded raw request without external writes and return a retry-stable provider-qualified delivery ID. |
+| `reconcileDelivery` | Read a stable report marker or current mutable projection before retry and return missing, delivered with receipt, or conflict. |
+| `deliver` | Append one bounded report or apply one current projection while preserving unrelated tracker fields. |
+
+Providers declare candidates, comments, dependencies, readiness and ingress capabilities. The registry rejects missing capabilities, duplicate IDs and incompatible interface versions. It combines caller cancellation with provider-generation withdrawal, drains active operations before disposal and validates normalized results at the seam.
+
+Keep provider entry points independently loadable. Shared MCP code may own exact-name construction, result bounds, tool-failure mapping, generation fencing and cursor protection; vendor modules own only their closed tool contracts, schemas, traversal and normalization. Do not expose a public `invoke(name, args)` module: arbitrary MCP names and vendor JSON must not become core knowledge.
+
+Code-host and notification services are separate normalized interfaces. A code host validates repository identity/access, resolves the approved remote/base, reconciles deterministic branch/tree/PR identity, creates one marked ready PR and returns an explicit receipt state. A notification provider reconciles and delivers a versioned event to one configured destination. Tracker comments still go through the selected tracker provider; they are not a second notification-side tracker client. Core selects provider identities stored in intents and contains no vendor-name switches.
+
+## Exact MCP contracts
+
+A tracker provider becomes available only when every required tool exists under its configured `mcp__<serverName>__...` namespace and its live input definition satisfies the pinned contract.
+
+- GitHub requires official `get_me`, `list_issues`, `issue_read` (`get` and `get_comments`), and feature-gated `issue_dependency_read` (`get_blocked_by`), plus `autopilot_read_issue_timeline` in the same MCP namespace. Each traversal compares `get_me` with the configured integration actor. The timeline extension must use the same MCP deployment and identity; there is no direct REST or second-token fallback.
+- Jira requires primary `atlassianUserInfo` plus the flat Atlassian `?tools=all` operations `searchJiraIssuesUsingJql`, `listJiraIssueComments`, `listJiraIssueChangelogs`, `getJiraIssue`, `addOrEditJiraIssueComment`, `editJiraIssue`, and `transitionJiraIssue`. Each traversal compares the authenticated account with configuration and verifies stable project/issue identity. Autopilot calls those exact tools; it does not use natural-language discovery or deferred execute-tier selection during reconciliation.
+- GitHub code-host publication requires official `get_me`, `get_commit`, `get_repository_tree`, `list_branches`, `list_pull_requests`, `pull_request_read`, `create_branch`, `push_files`, and `create_pull_request`. The provider compares the authenticated actor and configured repository identity and reconciles before each mutation/retry.
+
+All calls use fixed arguments and unique internal call IDs. Prefer `structuredContent`; otherwise accept only the contract's single JSON text block. Enforce per-result byte limits, schema limits, page/item ceilings, repeated/non-advancing cursor rejection and cancellation. Recheck the bound tool definition after execution so a result from a replaced MCP generation cannot cross the seam. Tool errors are sanitized and conservatively classified; unsupported or malformed evidence fails closed.
+
+## Availability and deployment
+
+The MCP mount watches Settings and DSH `tools/change`. It snapshots Settings, binds exact live tool definitions and registers one tracker generation only while they remain current. Any missing tool, schema drift, invalid configuration or definition replacement withdraws the provider; active reads are cancelled and drained. A later conforming generation remounts normally. Do not keep an old REST provider or parallel compatibility mode available during this interval.
+
+Programmatic root calls are incompatible with a DSH ToolRuntime configured globally as PTC-only: that mode admits only `run_code` at the root. Tracker deployments therefore require global `native` or `both` presentation until DSH supplies a distinct trusted Host-programmatic execution path. Never forge a PTC parent token to bypass this rule.
+
+Configure the official MCP deployment itself with least-privilege access and only required repositories/projects: tracker-read bindings remain read-only, while Jira delivery and GitHub publication bindings receive only their required writes. All required operations for one binding, including the GitHub timeline extension, must share one MCP namespace so outbound authentication has one owner. The namespace is snapshotted with the provider binding; secret values never enter run state.
+
+## Normalized facts and policy
+
+Use provider-qualified stable identities for bindings, issues, comments and readiness generations. Display keys, URLs, names and slugs are not global identities. An issue snapshot carries scope, summary, mapped priority, current labels, designated Brief comments, dependency completion evidence and readiness evidence.
+
+Map priorities and completion states explicitly. Dependency results are `completed`, `not-completed` or `unknown`; missing access or an unrecognized terminal reason is never completion. Providers return immutable actor identity and ordered transition evidence sufficient for [human-readiness authorization](lifecycle.md#human-readiness-authorization). A current label, webhook sender or user-shaped MCP record cannot substitute for a trusted human transition. Missing, partial, contradictory or ambiguous evidence rejects admission.
+
+Operation errors distinguish invalid configuration/response, unavailable capability or generation, timeout, transient failure and conflicts wherever DSH preserves evidence. Never expose raw MCP output, tool errors, credentials or live ticket content in diagnostics.
+
+Snapshot provider binding identity and interpretation with every run and external intent. Reject an ordinary tracker/project/repository switch while unfinished runs or unresolved writes depend on it; rotation inside the same official MCP identity does not reassign the binding. After a provider or tool generation disappears, retain historical receipts and reconcile them through the original binding when it returns. Never reinterpret old receipts through a newly selected provider.
+
+## Future providers and acceptance
+
+Linear follows the same normalized tracker interface only after its official MCP deployment proves exact candidate, comment, dependency and immutable readiness-actor contracts. Do not add a GraphQL/token fallback. Bitbucket Cloud code-host support should use official Atlassian MCP under its Atlassian identity and a separate normalized code-host adapter; Atlassian's Bitbucket tools do not make Bitbucket Issues a supported tracker.
+
+Shared conformance fixtures cover authenticated ingress, duplicate deliveries, complete pagination, stable identities, actor attribution, dependency direction and unknown access, malformed/oversized results, cancellation, tool replacement, Settings remount, redaction, disposal and restart recovery. Mock-tool tests prove the local seam; production support additionally requires an authorized live conformance run against the exact official server/tool generation. Record live evidence on the relevant GitHub issue, not in this specification.

package/docs/specs/scope.md

@@ -0,0 +1,35 @@
+# Scope and ownership
+
+## Product
+
+Autopilot coordinates tracker-approved development work through DSH and hands it off as a code host pull request. Ticket requirements and execution instructions come from the Agent Brief, configured DSH skills/preset, and target repository. Autopilot coordinates their execution and human feedback.
+
+V1 selects one tracker provider and one code-host provider for one project scope on one VPS with one active orchestrator. Multiple runs may execute concurrently within configured limits. One authenticated operator role can view, operate, and configure the system. The Web panel is part of DSH Web; unattended work continues when browsers are closed.
+
+## Ownership
+
+| System | Authoritative information and behavior | Autopilot relationship |
+| --- | --- | --- |
+| Issue tracker (Jira, GitHub Issues or Linear) | Requirements, Agent Brief comments, priority, dependency links, human readiness/unblock decisions, issue status | Read selected issues; apply configured labels/status transitions and append execution reports |
+| Target repository | Source, AGENTS.md and applicable instructions, skills, build/test commands, contribution conventions | Supply its workspace to DSH; preserve its rules |
+| Git local | Worktree registration, branches, commits, working changes, tracking state | Manage only worktrees allocated to Autopilot runs; query Git before maintenance |
+| Code host (GitHub or Bitbucket) | Remote branches, PR identity, review, CI, merge/closure state | Publish completed work; hand review to humans; inspect PR disposition when evaluating cleanup |
+| DSH | Execution/Session services and platform infrastructure: presets/skills, MCP, delegation, API/SDK, Web, Settings, credentials and storage | Compose suitable public capabilities from the pinned DSH version; implement only missing domain behavior |
+| Autopilot plugin | Admission policy, durable queue/run records, worktree ownership, pause intent, spending policy, integration receipts, notification delivery, UI commands | Coordinates the above systems; does not replace their records |
+| VPS deployment | Process supervision, persistent volumes, access authentication/TLS, backups, host credentials | Keeps the DSH profile available and its data recoverable |
+
+An optional remote-access plugin belongs to deployment composition: it owns pairing/transport/device sessions. Autopilot integrates through that access mode after verification; it does not incorporate a tunnel or device-management product.
+
+The DSH agent determines code changes and verification using target-repo rules. Autopilot does not prescribe a universal lint/test checklist or judge code quality independently. It checks that execution supplied the required outcome and evidence before authorizing publication.
+
+Publication and tracker lifecycle writes have one designated execution path controlled by Autopilot. Select the concrete publication executor through the implementation issue on GitHub. Avoid duplicate publication by both an unconstrained agent and a Host publisher.
+
+Provider interfaces, selection and extension are owned by [provider architecture](providers.md). Supported tracker and code-host providers compose independently; provider selection does not add multi-project administration.
+
+Tracker intent, plugin run state, DSH execution state, and code host PR state are distinct. For example, a completed Autopilot run may have a tracker ticket still In Review and a PR still open.
+
+## Scope exclusions
+
+V1 excludes multi-project administration, multi-VPS coordination, leader election, role hierarchies, a replacement issue tracker, an agent-team/DAG editor, automated code host CI repair, PR review, merge automation, and automatic tracker Done transitions. PRs are created ready for review after local work succeeds; no early Draft PRs.
+
+Raw-ticket triage and authoring Agent Briefs may happen through existing human/skill workflows. Automatic triage is not a second product to implement here. Autopilot consumes the approved brief and routes execution blockers back to tracker.