Define nanodot product design and MVP scope

[hsliuustc0106]

Goal

Review the nanodot product design and agree on a small, testable MVP before implementation expands.

The README describes nanodot as a minimal, open-source AI assistant with persistent memory and proactive task execution. This issue turns that direction into a reviewable product scope.

The workflow and UX below are proposals for discussion. Creating this issue does not settle the MVP choice or approve every proposed feature.

Confirmed direction

• Build a minimal, open-source personal agent from scratch in Python to understand its architecture.
• Keep memory, task state, and execution local-first and inspectable.
• Start with a native runner. Consider an adapter later; DSH and openJiuwen are candidates, with neither selected.
• Support ongoing work while the host is awake and the runner is available. A sleeping or powered-off host cannot continue execution.
• Keep the inference decision open: API-backed, local, or a supported combination.

Proposed MVP: a task inbox with one bounded workflow

The suggested first workflow is a read-only watch on one explicitly selected GitHub pull request.

Example user intent: “Watch this PR and tell me when the required checks pass, or when something needs my attention.”

1. Capture the task and show its exact target, purpose, check cadence, allowed actions, notification conditions, and stopping conditions.
2. Take an initial snapshot and persist the task locally.
3. Check again while the runner is available.
4. Report meaningful changes with links and evidence. Distinguish pending checks, failures, unavailable data, and a confirmed terminal outcome.
5. Stop on the agreed success condition, PR merge/closure, user cancellation, or an explicitly configured end condition. Surface lost access as a blocker.

This proposal is read-only: commenting, code changes, reruns, merging, and other external writes would need separate scope and approval.

A bounded paper-research task is an alternative first workflow. Choose one for the first end-to-end build. Slack integration can follow after the local task loop is proven.

Proposed user experience

Keep the interface small. It should let the user answer four questions:

• Tasks: What is nanodot doing, what is it waiting for, and when will it stop? Show status, latest result, next check, blockers, and pause/resume/cancel controls.
• Memory: What has it retained and why? Make retained facts visible, show their source where available, and allow correction or deletion. Avoid treating tentative model inferences as confirmed facts.
• Activity: What actually ran? Show concise, timestamped checks, relevant evidence, failures, retries, and notifications without exposing secrets.
• Approvals: What action needs permission? Show the proposed action, target, data being shared, and expected effect. Approval must apply to that action and scope; silence is not approval.

Decide whether the first interface is CLI/TUI or a small local web UI. A full chat interface is not a prerequisite for validating the task loop.

Reliability and safety requirements to review

• Persist task configuration and progress so a restart does not lose the task.
• Define recovery after sleep, restart, and interrupted checks. On waking, reconcile current state instead of replaying every missed notification.
• Prevent overlapping runs of the same task and duplicate notifications for an unchanged event.
• Tie PR check results to the current commit; passing checks on an older commit must not count as success for a newer one.
• Define bounded retries/backoff for network failures, rate limits, and temporary errors. Make prolonged failures visible.
• Preserve explicit pause/cancel state across restarts and stop scheduling completed tasks.
• Keep external content as data, not authority to expand a task or grant permissions.
• Separate local-first storage/execution from inference privacy. If an API model is used, clearly identify what context leaves the host.
• Keep credentials out of task text, memory, activity logs, and generated summaries.

These are review requirements, not claims about existing implementation.

Open decisions

Status as of 2026-09-30 — resolutions recorded in the decision-record comment.

1. First workflow: PR watch or paper research? What concrete user outcome defines success? — Decided 2026-09-30: read-only GitHub PR watch.
2. First interface: CLI/TUI or local web UI? — Decided 2026-09-30: CLI/TUI first; local web UI deferred, core stays interface-agnostic.
3. Inference: API, local, or both? What is the minimum provider/model contract? — Decided 2026-09-30: API model first, behind a thin provider interface; the context-leaves-host boundary must be explicit.
4. Memory: what deserves durable retention, what needs explicit confirmation, and what is the retention/deletion policy? — Under dedicated design; confirmation-gated write path and provenance agreed, sub-decisions still open.
5. Task behavior: default cadence, retry policy, notification rules, and required stopping conditions? — Defaults proposed (poll ~5 min, backoff to 60 min), pending confirmation; notification channel still open.
6. Permissions: what is allowed by default, what needs approval, and how is approval recorded and invalidated when scope changes? — Decided 2026-09-30: ZCode-style — named modes with readonly default, scoped per-action approval grants, silence is never approval.
7. Adapter timing: what real limitation would justify adding DSH or openJiuwen after the native runner? — Decided 2026-09-30: native runner first, architecture reserves an adapter seam; trigger is execution beyond an awake host or multi-machine dispatch.

Review acceptance checklist

• Agree on the primary user need and choose exactly one MVP workflow
• Document the happy path, blocked path, and stopping conditions
• Agree on the minimal task, memory, activity, and approval controls
• Resolve the first interface and inference approach
• Define local storage, privacy boundaries, credential handling, and memory correction/deletion
• Define sleep/restart recovery, retry/backoff, concurrency, and notification deduplication
• Record deferred features and the trigger for considering an adapter
• Turn the approved scope into small implementation issues with testable acceptance criteria (Scaffold: Python package with core/ports layout, tests, and CI #2–End-to-end PR-watch validation suite (all fakes) #14; index in the implementation breakdown comment)

Suggested end-to-end validation if PR watch is selected

• Create a watch, inspect its saved scope, and observe an initial result.
• Simulate pending → failing → passing checks on the current commit.
• Push a new commit and verify old results cannot satisfy the new check state.
• Restart or suspend/resume the host and verify recovery without duplicate notifications.
• Exercise temporary network failure, rate limiting, and lost authorization.
• Verify pause/resume/cancel and terminal stop behavior.
• Verify no external write occurs and no secret appears in retained data or logs.

[hsliuustc0106]

Decision record — design review, 2026-09-30

This review resolves five of the seven open decisions above. Memory is under dedicated design, and two items carry proposed defaults pending confirmation.

Decided

1. First workflow: read-only GitHub PR watch. The MVP is a task inbox watching one explicitly selected PR: capture scope and stop conditions → snapshot → re-check → report changes with evidence → stop on defined conditions. Strictly read-only; no external writes of any kind. The paper-research workflow was not chosen; Slack integration stays deferred until the local task loop is proven.

2. Interface: CLI/TUI first. The four UX questions (Tasks / Memory / Activity / Approvals) become CLI commands; the native runner runs as a long-lived background process that the CLI queries and controls. Local web UI deferred, not excluded — the core stays interface-agnostic so a web UI can be layered on later without rework.

3. Inference: API model first, behind a thin provider interface — roughly summarize(state_change, evidence) -> text, plus intent parsing at task creation — so a local model can slot in later without touching the task loop. Privacy boundary (as this issue requires): PR metadata and summarization prompts leave the host; credentials, tokens, task state, snapshots, and logs never do. The model provider is the only egress point; the API key lives in the local secret store.

4. Permissions: ZCode-style. Named permission modes with readonly as the MVP default. Approvals are persisted, inspectable, revocable grants scoped to action type + target + scope + expiry; a different action or a different target does not match the grant. Silence is never approval — unanswered requests expire and the task waits in a visible blocked state. Denials are recorded and never re-asked verbatim. Grants are invalidated when task scope changes. Belt and suspenders: a read-only PAT caps capability independently of mode, so even a bug cannot produce a write. The MVP ships the mode config, the grant schema, the nanodot approvals surface (which will show nothing pending), and an invariant test that no code path constructs an external write.

5. Adapter timing: native first, adapter-aware. Only the native runner ships, but all policy (state machine, stop conditions, commit-pinning, notification dedup, memory, activity, persisted formats) lives in core, which talks to ports: scheduler/executor, GitHub access, notification sink, inference provider. An adapter (DSH/openJiuwen remain candidates) executes and never decides; swapping executors requires no data migration. The seam is verified by substitution — task-loop tests run entirely against fakes (fake clock/executor/GitHub). Trigger to actually add an adapter: a demonstrated native-runner limitation, realistically execution continuity beyond an awake host or dispatch beyond one machine.

Under dedicated design: memory

Per review, memory gets its own design track and its own implementation issue — it is not bundled with the other defaults. Direction agreed:

• Memory means durable cross-task knowledge only. Task state and the activity log are separate stores; history never silently graduates into memory.
• The write path is confirmation-gated: user-stated items enter as confirmed; evidenced terminal outcomes auto-record as observations with provenance; model inferences never auto-write — they may propose, and proposals require explicit confirmation via CLI.
• Every item carries provenance (source, evidence pointer, timestamps). No credentials, ever.
• Read path: memory is injected only at task creation and summarization. The loop must run correctly with an empty memory store — memory accelerates, never gates.
• Deletion removes content from the store and all future prompts; activity history keeps contentless tombstones.

Still-open memory sub-decisions: (a) auto-recorded evidenced outcomes in or out (proposed: in), (b) deletion depth — tombstone vs. hard scrub (proposed: tombstone default), (c) proposal expiry (proposed: 14 days), (d) storage engine (proposed: SQLite).

Still open — proposed defaults, unconfirmed

• Notification channel. Proposed: macOS notification for notable/terminal events, plus the deduplicated inbox visible in nanodot tasks.
• Cadence and retries. Proposed: poll ~every 5 minutes; exponential backoff (×2) up to 60 minutes on rate limits and temporary errors; prolonged failure surfaced after ~1 hour.

Next step

Turn this record into small implementation issues with testable acceptance criteria (memory and the adapter seam each get their own issue), using the end-to-end validation list above as the PR-watch acceptance suite.

[hsliuustc0106]

Implementation breakdown — 2026-09-30

The approved scope turned into small issues, numbered in build order. Each has testable acceptance criteria; the final issue is the end-to-end validation list from this issue, automated against fakes.

Foundation

• Scaffold: Python package with core/ports layout, tests, and CI #2 — Scaffold: Python package with core/ports layout, tests, and CI
• Document the adapter seam: port contracts #3 — Document the adapter seam: port contracts
• Local secret store with redaction guarantees #4 — Local secret store with redaction guarantees
• Task store and task model #5 — Task store and task model

Core loop

• GitHub snapshot port: commit-pinned check fetching #6 — GitHub snapshot port: commit-pinned check fetching (needs Local secret store with redaction guarantees #4, Task store and task model #5)
• Watch state machine: transitions, commit-pinning, dedup #7 — Watch state machine: transitions, commit-pinning, dedup (needs GitHub snapshot port: commit-pinned check fetching #6)
• Native runner: cadence, backoff, locking, restart recovery #8 — Native runner: cadence, backoff, locking, restart recovery (needs Task store and task model #5–Watch state machine: transitions, commit-pinning, dedup #7)

Surfaces

• Notification sink and deduplicated inbox #9 — Notification sink and deduplicated inbox (needs Watch state machine: transitions, commit-pinning, dedup #7; channel = proposed default, confirm in review)
• CLI: task inbox, watch lifecycle, and activity views #10 — CLI: task inbox, watch lifecycle, and activity views (needs Task store and task model #5, Watch state machine: transitions, commit-pinning, dedup #7–Notification sink and deduplicated inbox #9)
• Inference provider port and API adapter with egress boundary #11 — Inference provider port and API adapter with egress boundary (needs Scaffold: Python package with core/ports layout, tests, and CI #2, Local secret store with redaction guarantees #4)
• Memory subsystem: gated writes, provenance, tombstoned deletion #12 — Memory subsystem: gated writes, provenance, tombstoned deletion (needs Task store and task model #5, Watch state machine: transitions, commit-pinning, dedup #7, Inference provider port and API adapter with egress boundary #11; open sub-decisions listed in the issue)
• Permissions: modes, scoped grants, approvals surface #13 — Permissions: modes, scoped grants, approvals surface (needs Task store and task model #5)

Acceptance gate

• End-to-end PR-watch validation suite (all fakes) #14 — End-to-end PR-watch validation suite, all fakes (needs Scaffold: Python package with core/ports layout, tests, and CI #2–Permissions: modes, scoped grants, approvals surface #13; runs offline — the proof of the adapter seam)

Remaining open items carried into the issues: notification channel (#9) and cadence/retry numbers (#8) use the proposed defaults pending confirmation; the four memory sub-decisions are listed in #12.

[hsliuustc0106]

MVP decided and delivered. The decision record below settled the read-only PR-watch workflow with a CLI-first interface, and the full lifecycle landed through #17–#28: watch add with scope preview, native runner with a single lifetime lock, inbox dedup, activity replay, memory with proposal confirmation, and the whitelisted egress path.

Confirmed-direction items are reflected in the docs: native runner only, with adapters deliberately deferred (docs/design/adapter-seam.md keeps DSH and openJiuwen as candidates behind the rule 3 trigger), and inference optional with a local model slotted in behind the same port.

Follow-up work now lives in its own places: #14 (closed today as done) and #37 for the shutdown-disposer refactor. Closing this as the scope it tracked is defined and shipped.