pi-anchor 0.3.0 → 0.5.0

package/README.md

@@ -1,14 +1,12 @@
 # ⌖ Anchor
 
-> **Compact, Autonomous, Persistent Task Memory for Pi Coding Agent**  
-> Pin tasks across sessions (`/pin`), wake them automatically when entering the project or touching files, and settle them in real time on `git commit` — with **0 `TODO.md` repo clutter** and **0 idle tokens**.
+> **A digital sticky note docked below your Pi editor — with four clever touches.**  
+> Stick a note in 0ms (`pin: ...`), see it persistently below your editor (`belowEditor`, zero collision with `aboveEditor` extensions), track long tasks with micro progress bars `[■■□□ 2/4]`, jump straight back to the original conversation session (`↪`), and auto-tear off on `git commit`.
 
 [![CI Status](https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml/badge.svg)](https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml)
 [![Node v20+](https://img.shields.io/badge/Node-v20+-22c55e.svg)](package.json)
 [![TypeScript Strict](https://img.shields.io/badge/TypeScript-Strict-3b82f6.svg)](tsconfig.json)
-[![Tests: 34 Passed](https://img.shields.io/badge/Tests-34%20Passed-22c55e.svg)](tests/store.test.ts)
-[![Startup: < 90ms](https://img.shields.io/badge/Startup-%3C%2090ms-success.svg)](package.json)
-[![Zero Repo Pollution](https://img.shields.io/badge/Storage-Zero%20Repo%20Pollution-success.svg)](#1-zero-repository-contamination--storage-topology)
+[![Tests: 10 Passed](https://img.shields.io/badge/Tests-10%20Passed-22c55e.svg)](tests/store.test.ts)
 [![License: MIT](https://img.shields.io/badge/License-MIT-f97316.svg)](LICENSE)
 
 **English** | [简体中文](./README_zh.md)
@@ -18,192 +16,58 @@ pi install npm:pi-anchor
 ```
 
 <p align="center">
-  <img src="assets/hero-en.svg" alt="Anchor Terminal Dashboard" width="820">
+  <img src="assets/hero-en.svg" alt="Anchor Sticky Notes" width="820">
 </p>
 
 ```text
-⌖ Anchors (3 active, 1 quiet):
-
-  01  [P0]      Migrate auth module to HttpOnly cookies [src/auth.ts]   anchor        Today           Today 10:02
-  02  [P1]      Add concurrent file lock unit tests                     anchor        Tomorrow        Yesterday 21:34
-  03  [P1]      Polish CLI interactive dashboard & TUI                  Desktop       In 2d           Today 10:02
-  04  [Quiet]   Read external architecture notes before refactor        College/优化  Quiet (0 tok)   09-28 14:20
-
-  Use `anchor done <id>` to complete, or `anchor undo` to restore.
+╭─ Pi Editor ──────────────────────────────────────────────────────────────────────╮
+│ ❯ pin: Refactor auth flow: 1. Extract interface 2. HttpOnly cookie 3. Unit tests │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+  ⌖ #1 [■■□□ 2/4] Refactor auth flow ▸ Unit tests (app · auth.ts ↪)
 ```
 
-### The Three Pillars: Compact · Autonomous · Persistent
-
-1. **Compact (小巧 · Zero Bloat & 0 Idle Tokens)**:
-   - Pure TypeScript (~20KB bundle, zero external runtime dependencies, zero background daemons, zero SQL databases in your repo).
-   - Flat, priority-sorted engineering list (`/anchor`, `/pin`, `/done 1`). Briefs the AI on Turn 1 of a session, then drops to **0 tokens** from Turn 2+ while you code.
-2. **Autonomous (自主 · Smart Path Inference & Real-Time Commit Settlement)**:
-   - Automatically extracts file/folder paths mentioned in your task description and binds them to the target workspace even if you pinned the task from another directory.
-   - Settles tasks **in real time during the session** the moment `git commit` or a verification test command (`verifyCommand`) succeeds — works for both file-bound and plain-text tasks (`files: []`).
-3. **Persistent (持久 · Never Loses Unfinished Work)**:
-   - Stored safely in `~/.anchor/state.json` outside your git working tree.
-   - Unfinished tasks are **never silently deleted**. Tasks untouched for 7+ days enter `[Quiet]` mode (saving Turn 1 prompt tokens), stay 100% visible in `/anchor`, and automatically wake up the moment you open their target project or touch matching files.
-
 ---
 
 ## Why Anchor?
 
-When building software with terminal-based AI coding agents (Claude Code, Pi, Aider), developers encounter three recurring points of friction:
-
-### 1. Terminal Exit = Instant Amnesia
-Pressing `Ctrl+C` terminates the agent process, clearing working memory. Unfinished refactoring plans, temporary milestones, and cross-session agreements vanish instantly.
-
-### 2. TODO.md Pollutes Git & Suffocates Token Windows
-Writing tasks into `TODO.md` or `AGENTS.md` inside your repository creates unwanted git noise (`update todo`, `fix checklist`). Worse, **every single turn injects dozens of stagnant lines into the system prompt**, burning token budgets and diluting LLM attention on active code.
-
-### 3. Checkbox Rot & Heavy Over-Engineering
-Once code is written, developers rarely reopen markdown files to check boxes manually. Incomplete task lists rot inside the repository indefinitely. Existing alternatives introduce heavy trade-offs: `beads` forces a 200MB Dolt SQL database directly into your repository, while `engram` runs a persistent background Go daemon with SQLite and continuous vector retrieval.
-
-**Anchor takes a lean, pragmatic approach**:
-- **Zero Repo Contamination**: State is stored outside the workspace in `~/.anchor/state.json`, keeping your git tree 100% clean.
-- **0 Idle Tokens**: Injects active commitments on Turn 1 cold-start; Turn 2+ working turns consume **0 tokens**. Stored tasks don't cost a dime while writing code.
-- **Syntax-Safe JIT Wakeup**: When the agent touches relevant files, Anchor surfaces a single-line language-accurate comment (`//`, `#`, `<!-- -->`, `/* */`), while strictly skipping JSON, ENV, and lockfiles.
-- **Auto-Settlement & Accidental Settle Guard**: Tasks automatically settle on git commits matching task descriptions or on session exit. In interactive dashboard mode, a two-stage dialog prevents accidental completion.
-
----
-
-## Core Architecture & State Machine
+When you're deep in a coding session and think *"Wait — I need to check the rate-limit fallback in `src/gateway.ts` after this"*, or when you pause a multi-day task for the night:
+- Writing a `TODO.md` inside your repo pollutes `git status` and burns prompt tokens on every turn.
+- Normal startup banners vanish the second you send a message, so you forget what you wrote.
 
-```text
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                        Anchor Lifecycle State Machine                        │
-└──────────────────────────────────────┬───────────────────────────────────────┘
-                                       │ Pin task: anchor "Migrate auth to HTTP-only cookies"
-                                       ▼
-               ┌───────────────────────────────────────────────┐
-               │         [ACTIVE Tier] (Turn 1 Injected)       │
-               │ - Status indicator: ⌖ 4                       │
-               │ - Turn 2+ : Excluded from prompt (0 Tokens)   │
-               └───────┬───────────────────────────────┬───────┘
-                       │                               │
-      Git Commit /     │                               │ Inactivity Decay
-      Code Touch       ▼                               ▼
-  ┌──────────────────────────────┐            ┌────────────────────────────────┐
-  │   [Syntax-Safe JIT Wakeup]   │            │   [SLEEPING Tier] (0 Tokens)   │
-  │ Language-accurate comments   │            │ Preserved safely in global     │
-  │ JSON/ENV strictly skipped    │            │ state; wakes upon code touch   │
-  └──────────────┬───────────────┘            └────────────────┬───────────────┘
-                 │                                             │
-      Exit Prompt / Commit Match                               │ Silent Sweep
-                 ▼                                             ▼
-  ┌──────────────────────────────┐            ┌────────────────────────────────┐
-  │     [SETTLED / Archived]     │            │      [GRAVEYARD / Evicted]     │
-  │ Appended to archive.jsonl    │            │ Swept to graveyard.jsonl       │
-  │ Evicted from active context  │            │ (Auto-pruned after decay)      │
-  └──────────────────────────────┘            └────────────────────────────────┘
-```
-
-| Action / Scenario | What You Do | What Anchor Does | What the AI Gets | When to Use |
-| :--- | :--- | :--- | :--- | :--- |
-| **Pin Commitment** | Run `anchor "Refactor auth"` | Atomically writes to `~/.anchor/state.json` | Turn 1: Injected into prompt; Turn 2+: 0 tokens | Retaining multi-step plans across terminal restarts |
-| **File Touch** | Edit or read code normally | Matches touched files against anchor paths | Injects syntax-safe 1-line comment (skips JSON/ENV) | Working on relevant project modules |
-| **Git Commit** | `git commit -m "feat: ..."` | Matches commit message using `Intl.Segmenter` | Auto-settles and archives matching task | Finishing code milestones |
-| **Session Exit** | Type `exit` / `quit` | Intersects git-modified files with active anchors | Single-keypress prompt: `[Enter Settle] / [Esc Keep]` | Wrapping up terminal session |
+**Anchor is a real sticky note stuck right under your Pi input box (`belowEditor`)** — stored outside your repo in `~/.anchor/state.json` (4 source files, 0 dependencies), designed for **human hands first**:
 
----
+### 1. Docked Below Your Editor & 0ms Instant Stick (`pin: ...`)
+- **Zero Widget Collision**: Anchor docks its 1-line strip **below** your editor (`placement: "belowEditor"`), leaving the space above your editor (`aboveEditor`) 100% free for tools like `pi-lingual`.
+- **0ms Human Input**: Type `pin: Check token expiry` (or `note: ...`, `便签: ...`, `/pin ...`) directly in the editor. Anchor intercepts it in **0.00ms** without triggering an LLM call or burning tokens, and automatically links the file you were just editing.
 
-## Engineering Highlights & v0.2.1 Hardening
+### 2. Micro Progress Bar for Long Tasks (`[■■□□ 2/4]`)
+- Write a ratio (`[2/4]` or `5/30`) or numbered steps (`1. Extract interface 2. HttpOnly cookie 3. Unit tests`) in your note:
+  ```text
+  /pin Refactor auth flow: 1. Extract interface 2. HttpOnly cookie 3. Unit tests
+  ```
+- Anchor renders a crisp micro progress bar (`[■■□□ 2/3] ▸ Unit tests`) right on the sticky strip. Run `/step 1` (or select `▶ Advance step` in `/anchor`) to tick it forward. Simple one-off notes stay 100% bar-free.
 
-### 1. Zero Repository Contamination & Storage Topology
-Anchor never creates local `.anchor` folders or touches your project git tree. All state lives safely in user-global storage:
-```text
-~/.anchor/
-├── state.json           # Active and sleeping task state (< 10KB, atomic write)
-├── state.lock           # Cross-process sync atomic lock (Zero dependencies)
-├── archive.jsonl        # Append-only log of settled tasks
-└── graveyard.jsonl      # Append-only log of decayed and evicted items
-```
-* **Zero-Dependency Exclusive Lock**: Uses Node's native `fs.openSync(lockPath, 'wx')` to ensure atomic serialization across concurrent tabs or agents.
-* **Dead PID Reclamation**: Automatically reclaims stale locks if the owning process terminated (`process.kill(pid, 0)` fails) or exceeded the 5000ms timeout.
-* **Resilient Atomic Writes**: State writes use a temporary file followed by atomic `fs.renameSync` with spin-retries for Windows NTFS locks.
+### 3. Conversation Session Bookmark (`↪ Jump to session`)
+- Every sticky note automatically bookmarks the Pi conversation session (`sessionFile`) where it was created or last worked on.
+- Days later, open `/anchor` and pick **`↪ Jump to session`** (or run `/anchor jump 1`) to teleport Pi straight back into that exact conversation history.
 
-### 2. Accidental Settle Guard & Details Inspector (v0.2.1)
-Pressing Enter in `/anchor` presents a two-stage action menu:
-* `✓ Settle`: Completes and archives the task with an undo notice (`/anchor undo to revert`).
-* `ℹ View details & associated files`: Inspects full description, target date, files, and physical verification command without completing the task.
-* `↩ Cancel`: Returns safely without mutating state.
-
-### 3. Invariant 11 Token Clamping (v0.2.1)
-Visual string truncation in dashboard headers automatically strips trailing open brackets (`(`, `[`, `{`, `（`, `【`) right before ellipsis markers (`...`), eliminating dangling punctuation artifacts.
-
-### 4. 0-Token Idle Economy & Multi-Language Syntax-Safe JIT
-* **Turn 1 (Cold Start)**: Injects active commitments for the current workspace alongside natural conversational guidelines.
-* **Turn 2+ (Working Turns)**: Anchor strips task lists from subsequent turns. Stored tasks consume **0 tokens** while coding.
-* **Syntax-Safe Guard (Strict Null)**: For **JSON, ENV, Lockfiles, and binary assets**, Anchor explicitly returns `null`, preventing corrupted parsers or invalid syntax.
-
-### 5. Pre-Flight Physical Verification
-When an anchor declares a `verifyCommand`, the runner executes it on session start. Tasks that pass auto-settle immediately, freeing cognitive space.
+### 4. File Whisper & Auto-Tear on `git commit`
+- **1-Line File Whisper (0 Idle Tokens)**: Briefs the AI once on Turn 1, then consumes **0 tokens** on Turn 2+. When the AI reads or edits a matching file, Anchor slips a 1-line comment (`// ⌖ Note #1: ...`) onto that file result (strictly skipping `.json` and `.env`).
+- **Auto-Tear on Commit**: When `git commit -m "..."` matches your note, Anchor tears the note off automatically (`⌖ Auto-torn off #1`). Run `/anchor undo` anytime to put it back.
 
 ---
 
-## Commands & Usage
-
-### Standalone CLI
-```bash
-anchor                                  # List active tasks (Neovim-style dashboard)
-anchor "Migrate auth to cookies"        # Pin new commitment
-anchor "Submit report" --due friday     # Pin with explicit deadline
-anchor done 1                           # Complete row 1 (ordered index support)
-anchor done anc-5                       # Complete by explicit ID
-anchor undo                             # Restore last archived task
-```
-
-### Pi Coding Agent Commands
-| Command | Description |
-| :--- | :--- |
-| `/pin <task> [--due tomorrow]` | Pin a task across sessions with optional due date |
-| `/anchor` | Open interactive terminal task dashboard |
-| `/done <id>` or `/anchor done <id>` | Complete task by row number (`1`) or ID (`anc-1`) |
-| `/anchor undo` | Restore the last settled task |
-| Status bar `⌖ N` | Displays active task count in status row; 100% hidden when 0 tasks exist |
-
----
-
-## Technical Comparison
-
-| Feature | `gastownhall/beads` | `Gentleman-Programming/engram` | `AGENTS.md` / `TODO.md` | **Anchor ⚓** |
-| :--- | :--- | :--- | :--- | :--- |
-| **Architecture** | Distributed SQL Graph | Vector/SQLite Memory | Static Markdown | **Decoupled Universal Protocol + Atomic State** |
-| **Workspace Hygiene** | Pollutes repo with 200MB Dolt | System daemon | **Pollutes git commit history** | **100% Zero repo pollution (`~/.anchor/`)** |
-| **Token Cost** | Medium/High per turn | High (full prompt injection) | Severe (stale text accumulates) | **0 Tokens idle (JIT file touch only)** |
-| **Syntax Safety** | N/A | Raw text injection | Static unformatted | **Language-aware comments, strictly skips JSON** |
-| **Closure Mechanism** | Manual CLI close | Passive storage | Manual file edit | **Git Commit auto-match + One-tap exit settlement** |
-| **Concurrency Safety** | SQL Transaction locks | Daemon single-point | Git merge conflicts | **Zero-dep cross-process atomic file lock** |
-| **Startup Overhead** | Heavy CLI init | Go daemon | None | **< 90ms pre-bundled production artifact** |
-| **Dependencies** | External Dolt binary | External Go binary | None | **Zero native binary dependencies (Pure TS)** |
-
----
-
-## Author's Note
-
-The motivation behind Anchor came from a recurring headache during pair-programming with AI coding agents: watching `TODO.md` and `AGENTS.md` rot inside my git trees.
-
-Every time a task remained unfinished across sessions, writing it to a project markdown file felt harmless at first. Over weeks of work, two frictions became unbearable:
-1. In multi-turn sessions, the AI dragged dozens of stagnant task lines into the prompt on every single turn, burning hundreds of tokens while diluting the model's focus on the actual code being edited.
-2. Merge conflicts on task checklists in Git commits polluted the repository's history with irrelevant bookkeeping noise.
-
-When I looked at existing solutions, the trade-offs felt disproportionate. Stuffing a 200MB Dolt SQL relational database into the repository root (`beads`), or running a background Go daemon with SQLite and continuous vector retrieval (`engram`), inverted the relationship between tool and developer. A task tracker should not demand more system resources than the application being built.
-
-Anchor takes the opposite approach: store state outside the project tree in a lean global ledger (`~/.anchor/state.json`), inject tasks only on Turn 1 of a cold start, keep Turn 2+ at exactly 0 tokens, and auto-settle upon git commits or session exit.
-
-In v0.2.1, we added the two-stage settle menu to eliminate accidental completions and enhanced visual truncation to prevent dangling punctuation. I hope Anchor keeps your project trees clean and your focus where it belongs: on the code.
-
----
-
-## Verification & Quality Assurance
-
-Engineered with strict TypeScript and 100% standard library test coverage using Node's native test runner:
-
-```bash
-npm run typecheck  # Strict tsc --noEmit check (0 errors)
-npm test           # Native Node test runner (34/34 passing)
-npm run build      # Dual ESM/CJS compilation via tsup + declaration emit
-```
+## Commands
+
+| Where | Input / Command | What It Does |
+| :--- | :--- | :--- |
+| **Pi Editor** | `pin: <note>` or `便签: <note>` | Stick a note in **0ms** without calling the LLM |
+| **Pi Slash** | `/pin <note>` | Stick a note (supports `[1/4]` or `1. A 2. B` steps) |
+| **Pi Slash** | `/anchor` | Open interactive board (tear off, `+1` step, or `↪` jump to session) |
+| **Pi Slash** | `/step 1` | Advance progress bar on note `#1` by `+1` |
+| **Pi Slash** | `/anchor jump 1` | Switch Pi back to the conversation session linked to note `#1` |
+| **Pi Slash** | `/done 1` / `/anchor undo` | Tear off note `#1`, or put back the last torn-off note |
+| **Terminal CLI** | `anchor` / `anchor step 1` / `anchor done 1` | View, step, or tear off notes outside Pi |
 
 ---
 

package/README_zh.md

@@ -1,14 +1,12 @@
 # ⌖ Anchor
 
-> **面向 Pi Coding Agent 的「小巧 · 自主 · 持久」跨会话任务记忆**  
-> 一句话钉住待办（`/pin`），进入目标工程或触碰关联文件自动唤醒，会话内执行 `git commit` 当场实时自动销账 —— **0 `TODO.md` 仓库污染，0 闲置 Token 损耗**。
+> **贴在 Pi 输入框正下方的电子便签 —— 专为顺手盲打与跨会话续传设计。**  
+> 敲 `便签: ...` 0ms 瞬贴上屏，在输入框**正下方 (`belowEditor`)** 常驻 1 行极简便签条（与上方 `pi-lingual` 零冲突），支持长线任务**迷你进度条 `[■■□□ 2/4]`**、**一键穿越回当时的对话上下文 (`↪`)**，以及 **`git commit` 自动撕便签**。
 
 [![CI 状态](https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml/badge.svg)](https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml)
 [![Node v20+](https://img.shields.io/badge/Node-v20+-22c55e.svg)](package.json)
 [![TypeScript Strict](https://img.shields.io/badge/TypeScript-Strict-3b82f6.svg)](tsconfig.json)
-[![Tests: 34 Passed](https://img.shields.io/badge/Tests-34%20通过-22c55e.svg)](tests/store.test.ts)
-[![启动耗时: < 90ms](https://img.shields.io/badge/启动耗时-%3C%2090ms-success.svg)](package.json)
-[![零仓库污染](https://img.shields.io/badge/存储-零仓库污染-success.svg)](#1-绝对零仓库污染与跨进程文件锁)
+[![Tests: 10 Passed](https://img.shields.io/badge/Tests-10%20通过-22c55e.svg)](tests/store.test.ts)
 [![开源协议: MIT](https://img.shields.io/badge/开源协议-MIT-f97316.svg)](LICENSE)
 
 [English](./README.md) | **简体中文**
@@ -18,199 +16,53 @@ pi install npm:pi-anchor
 ```
 
 <p align="center">
-  <img src="assets/hero-zh.svg" alt="Anchor 终端仪表盘实录" width="820">
+  <img src="assets/hero-zh.svg" alt="Anchor 电子便签预览" width="820">
 </p>
 
 ```text
-⌖ Anchors (3 active, 1 quiet):
-
-  01  [P0]      重构鉴权模块为 HttpOnly Cookie [src/auth.ts]            anchor        Today           Today 10:02
-  02  [P1]      补充并发文件锁单元测试                                  anchor        Tomorrow        Yesterday 21:34
-  03  [P1]      打磨 CLI 交互式极简工程列表                             Desktop       In 2d           Today 10:02
-  04  [Quiet]   College 重构前置查阅外部架构参考库                      College/优化  Quiet (0 tok)   09-28 14:20
-
-  Use `anchor done <id>` to complete, or `anchor undo` to restore.
-```
-
-### 三大核心设计：小巧 · 自主 · 持久
-
-1. **小巧 (Compact · 极简顺手 & 0 闲置 Token)**：
-   - 纯 TypeScript 实现（~20KB 产物，0 外部二进制依赖，不在仓库塞数据库，不开后台常驻进程）。
-   - 砍掉繁琐的四象限与打卡分类，回归一屏看清的优先级工程列表（`/anchor`、`/pin`、`/done 1`）。第 1 轮冷启动简要提醒 AI，第 2 轮起 **0 Token 损耗**。
-2. **自主 (Autonomous · 智能路径识别 & 会话内实时核销)**：
-   - 即使你在别的目录随口记下一句任务，也会自动提取标题/描述里的文件与目录路径并绑定目标工程，下次切换到该目录时自动唤醒。
-   - **不等关闭终端**：会话内一旦执行 `git commit` 或通过测试命令（`verifyCommand`），哪怕没填 `files` 也能根据提交信息当场实时自动核销，状态栏 `⌖` 即刻更新。
-3. **持久 (Persistent · 永不莫名丢任务)**：
-   - 独立托管于全局 `~/.anchor/state.json`，项目 Git 树 100% 纯净。
-   - **绝不因过期而静默删任务**：超过 7 天未触碰的任务自动转为 `[Quiet]` 静默省流态（不在无关会话塞 Prompt），但在 `/anchor` 面板中始终可见，可随时一键唤醒或在进入对应工程时自动激活。
-
----
-
-## 核心价值：为什么需要 Anchor？
-
-使用终端编程智能体（Claude Code、Pi、Aider 等）结对开发时，开发者普遍面临三个具体痛点：
-
-### 1. 终端一关即失忆（Session Amnesia）
-按下 `Ctrl+C` 退出终端，Agent 内存中的上下文被清空。未完成的代码重构计划、临时交代的排期与多步约定随之丢失。
-
-### 2. TODO.md 污染 Git 且拖垮上下文
-在工程根目录下维护 `TODO.md` 或 `AGENTS.md`：
-- 会产生大量 `update todo`、`fix checklist` 之类的 Git 杂质提交；
-- **每一轮对话都要把几十行陈旧清单塞入 System Prompt**，白白消耗大量 Token 预算，还会分散模型对当前核心代码的注意力。
-
-### 3. 告别手动打勾与清单发霉
-写完代码后，工程师极少会专程打开 Markdown 逐个打勾。未勾选的旧任务烂在仓库里，越积越多。
-现存的第三方方案走向了重型极端（例如 `beads` 往代码仓库塞入 200MB 的 Dolt SQL 数据库，`engram` 启动常驻后台的 Go 守护进程与向量检索库）。
-
-**Anchor 采取了克制而轻量的工程解法**：
-- **零仓库污染**：任务状态保存在全局主目录 `~/.anchor/state.json`，项目 Git 历史 100% 纯净；
-- **0 闲置 Token 损耗**：第 1 轮冷启动注入任务，第 2 轮起保持 0 Token 稳态，绝不浪费推理预算；
-- **语法安全 JIT 唤醒**：Agent 触碰相关代码文件时，以对应语言的单行安全注释精准唤醒，严格跳过 JSON、ENV 与锁文件；
-- **自动核销与防误触抽屉**：代码提交命中任务描述或退出终端时自动核销；交互式面板提供防误触二级菜单。
-
----
-
-## 工作机制：行为-结果矩阵
-
-```text
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                        Anchor 核心生命周期状态机                             │
-└──────────────────────────────────────┬───────────────────────────────────────┘
-                                       │ 记录任务: anchor "重构鉴权为 HttpOnly Cookie"
-                                       ▼
-               ┌───────────────────────────────────────────────┐
-               │           [活跃期 ACTIVE] (首轮注入提示)        │
-               │ - 底部状态栏指示: ⌖ 4                          │
-               │ - 第 2 轮起完全脱离提示词 (0 Token 稳态)        │
-               └───────┬───────────────────────────────┬───────┘
-                       │                               │
-        Git 提交命中 /  │                               │ 闲置时间衰减
-        触碰关联代码文件  ▼                               ▼
-  ┌──────────────────────────────┐            ┌────────────────────────────────┐
-  │   [多语言语法安全 JIT 唤醒]   │            │    [休眠期 SLEEPING] (0 Token) │
-  │ 触碰代码时注入语言对应注释    │            │ 全局安全封存，不打扰当前心流，   │
-  │ JSON/ENV 等格式绝对跳过      │            │ 触碰关联文件时重新唤醒          │
-  └──────────────┬───────────────┘            └────────────────┬───────────────┘
-                 │                                             │
-        退出自动提议 / Commit 命中                             │ 静默定期清理
-                 ▼                                             ▼
-  ┌──────────────────────────────┐            ┌────────────────────────────────┐
-  │     [已完成归档 SETTLED]      │            │     [超期淘汰 GRAVEYARD]       │
-  │ 追加写入 archive.jsonl 归档   │            │ 超期自动清理，防止陈旧堆积       │
-  │ 从当前活跃上下文中物理移除    │            │                                │
-  └──────────────────────────────┘            └────────────────────────────────┘
+╭─ Pi 输入框 ──────────────────────────────────────────────────────────────────────╮
+│ ❯ 便签: 重构登录鉴权流: 1. 抽出接口 2. 替换Cookie 3. 补单测 4. 压测              │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+  ⌖ #1 [■■□□ 2/4] 重构登录鉴权流 ▸ 补单测 (app · auth.ts ↪)
 ```
 
-| 动作 / 场景 | 你做什么 | Anchor 幕后动作 | AI 得到什么 | 适用场景 |
-| :--- | :--- | :--- | :--- | :--- |
-| **立项锚定** | 终端输入 `/pin "重构鉴权"` | 原子写入 `~/.anchor/state.json` | 首轮注入任务指引，第 2 轮起脱敏隐形（0 Token） | 跨会话记录多步计划与长效目标 |
-| **代码触碰** | 正常阅读或修改代码 | 自动匹配关联文件后缀 | 注入对应语法的单行安全注释，绝不破坏代码 | Agent 触碰相关业务模块时 |
-| **代码提交** | `git commit -m "feat: ..."` | 借助 `Intl.Segmenter` 分词匹配 | 自动核销任务并归档至 `archive.jsonl` | 完成开发里程碑，自动打勾 |
-| **会话退出** | 输入 `exit` 或退出终端 | 扫描已改动文件与活跃任务的交集 | 弹出单键核销确认：`[Enter 归档] / [Esc 保留]` | 结束会话，零遗漏确认 |
-
 ---
 
-## 核心特性与 v0.2.1 加固机制
-
-### 1. 绝对零仓库污染与跨进程文件锁
-所有状态统一保存在用户主目录 `~/.anchor/`，项目内绝不创建任何 `.anchor` 目录：
-```text
-~/.anchor/
-├── state.json           # 活跃与休眠任务状态表 (< 10KB，原子写入)
-├── state.lock           # 跨进程纯同步原子排他锁 (零依赖)
-├── archive.jsonl        # 已完成归档的历史账本 (追加写入)
-└── graveyard.jsonl      # 超期脱落墓地账本 (追加写入)
-```
-* **零依赖排他锁**：使用 Node 原生 `fs.openSync` 保证多终端并发读写安全；
-* **死锁自动熔断回收**：若持有锁的进程已终止或超时（5000ms），系统自动安全回收重占；
-* **原子写入与崩溃自愈**：写入临时文件后执行原子重命名，带 Windows NTFS 自旋重试。损坏文件自动备份为 `state.corrupt.${timestamp}.json` 并安全回退。
+## 为什么这次真正顺手了？（四大巧思）
 
-### 2. 防误触结算抽屉与详情查看器 (v0.2.1)
-在 `/anchor` 仪表盘中选中任务后，弹出二级操作菜单：
-* `✓ Settle (完成归档)`：核销并归档任务，提示可通过 `/anchor undo` 撤销恢复；
-* `ℹ View details & associated files`：直接在终端查看完整任务描述、目标日期、关联文件列表与自动化物理验证命令；
-* `↩ Cancel`：安全取消退出，避免直接敲击回车意外核销未完成事项。
+### 1. 输入框正下方常驻 1 行便签条 (`belowEditor`) + 0ms 瞬贴
+* **绝不跟上方插件抢地盘**：便签条挂载在输入框**正下方 (`belowEditor`)**，把输入框上方 (`aboveEditor`) 完全留给 `pi-lingual` 等高频伴学卡片，上下分工井然有序。
+* **真·便签常驻视野**：有便签时在输入框下沿安静显示 1 行，不再像以前那样“刚发第一句话就神秘消失”；无便签时 0 行完全隐形。
+* **自己随手写，0ms 上屏**：直接在输入框敲 `便签: 明天检查网关重试`（或 `pin: ...`、`/pin ...`），**0.00ms 当场拦截贴上便签条**，不用苦等大模型转圈调工具，不花 1 个 Token，还会自动关联你当前正在改的代码文件。
 
-### 3. 截断开括号守卫 (v0.2.1 · Invariant 11)
-在仪表盘字符串视觉列宽截断算法中，自动清除省略号前紧邻的孤立未闭合开括号（`(`、`[`、`{`、`（`、`【`），消除标点破裂与视觉毛刺。
+### 2. 长线任务迷你进度条 (`[■■□□ 2/4]`)
+* 遇到跨天或分步任务，随手在便签里写上进度比（如 `[5/30]`）或分步序号（`1. 抽出接口 2. 替换Cookie 3. 补单测`）：
+  ```text
+  便签: 重构登录鉴权流: 1. 抽出接口 2. 替换Cookie 3. 补单测
+  ```
+* 便签条会自动渲染出 4 格迷你进度条与下一步提示：`[■■□□ 2/3] ▸ 补单测`。敲 `/step 1`（或在 `/anchor` 菜单里点 `▶ Advance step`）即可推进一格；普通单句备忘则保持纯粹文字，绝不画蛇添足。
 
-### 4. 0-Token 稳态经济与多语言语法安全 JIT
-* **第 1 轮冷启动**：注入当前工作区的活跃任务承诺与简要行动指南；
-* **第 2 轮起 0 损耗**：任务清单从 System Prompt 中彻底脱敏移除，普通写代码轮次消耗 **0 Token**；
-* **语法安全严格跳过**：根据文件扩展名动态生成合法单行注释（`//`, `#`, `<!-- -->`, `/* */`）。对 **JSON、ENV、Lockfile 与二进制文件坚决返回 null 严格跳过**，杜绝破坏代码解析器。
+### 3. 绑定原对话 Session，一键穿越回去 (`↪ Jump to session`)
+* 贴便签或修改关联代码时，Anchor 会自动记录当前对话的 `sessionFile` 书签（显示 `↪` 标记）。
+* 哪怕过了好几天、开了十几个新窗口，当你看到便签想接着干时，打开 `/anchor` 选中它点击 **`↪ Jump to session`**（或敲 `/anchor jump 1`），Pi 就会**直接切换回当时那场对话的完整上下文**！
 
-### 5. 冷启动前置物理执行验证
-任务声明 `verifyCommand` 时，系统在启动时自动执行该物理命令。验证通过的任务即刻就地核销，释放认知带宽。
+### 4. 碰文件顺手递纸条 & `git commit` 自动撕便签
+* **碰文件递纸条（平时 0 Token）**：首轮对话简要提醒，第 2 轮起 **0 Token**；当 AI 读取或修改关联文件时，在文件结果末尾顺手附带 1 行语法安全注释（`// ⌖ Note #1: ...`，严格跳过 `.json`/`.env`）。
+* **提交代码自动撕下**：执行 `git commit -m "..."` 命中便签内容时，当场自动撕下归档；撕错了敲 `/anchor undo` 一秒贴回。
 
 ---
 
-## 常用命令
-
-### 命令行速查
-```bash
-anchor                                  # 查看活跃任务列表（Neovim 极客排版）
-anchor "重构鉴权模块"                   # 快速立项新任务
-anchor "提交实证报告" --due friday      # 指定周五到期
-anchor done 1                           # 完成第 1 行任务（支持连续编号）
-anchor done anc-5                       # 按具体 ID 完成任务
-anchor undo                             # 撤销上一次完成归档
-```
-
-### Pi 扩展内交互命令
-| 命令 | 说明 |
-| :--- | :--- |
-| `/pin <任务描述> [--due tomorrow]` | 快速立项当前工程的跨会话任务（支持指定到期日） |
-| `/anchor` | 在终端内弹出全景交互式任务仪表盘 |
-| `/done <编号>` 或 `/anchor done <编号>` | 按列表行号（`1`）或 ID（`anc-1`）直接完成核销 |
-| `/anchor undo` | 撤销上一次归档的任务 |
-| 状态栏 `⌖ N` | 底部常驻微标签，有活跃任务时显示数量，无任务时 100% 静默隐形 |
-
----
-
-## 横向技术对比
-
-| 核心维度 | `gastownhall/beads` | `Gentleman-Programming/engram` | `TODO.md` / `AGENTS.md` | **Anchor ⚓** |
-| :--- | :--- | :--- | :--- | :--- |
-| **架构拓扑** | 分布式 SQL 图谱 | 向量检索与 SQLite 常驻进程 | 静态 Markdown 文件 | **轻量解耦协议 + 单文件原子状态机** |
-| **仓库整洁度** | 塞入 200MB Dolt 数据库 | 系统常驻守护进程 | 频繁制造 Git 提交杂质 | **100% 零仓库污染 (`~/.anchor/`)** |
-| **每轮 Token 开销** | 中高频次全量注入 | 高 (全量提示词召回) | 严重 (陈旧清单持续膨胀) | **0 Token 稳态 (仅在触碰文件时 JIT 唤醒)** |
-| **语法注入安全** | 无安全机制 | 原始文本直接拼接 | 静态未格式化文本 | **多语言语法安全注释，JSON/ENV 严格跳过** |
-| **任务结算与核销** | 手动命令 `close` | 无自动结算机制 | 人工修改文本打勾 | **Git Commit 自动识别 + 退出前一键核销** |
-| **并发读写安全** | SQL 事务排他锁 | 守护进程单点调度 | Git 合并冲突频繁 | **零外部依赖 Node 原生原子排他文件锁** |
-| **启动性能损耗** | 较重 CLI 引导 | Go 进程通信延迟 | 无损耗 | **< 90ms 轻量打包生产产物** |
-| **底层运行依赖** | 外部 Dolt 二进制 | 外部 Go 二进制 | 无依赖 | **零原生二进制外部依赖 (纯 TypeScript)** |
-
----
-
-## 作者手记 (Author's Note)
-
-写 Anchor 的最初冲动，来自于我用终端 AI 编程智能体结对开发时经历的一场持续阵痛：看着项目根目录下的 `TODO.md` 与 `AGENTS.md` 在 Git 历史里发霉。
-
-很多时候，写完一段代码已经是深夜，跨会话未完成的任务随手记在项目的 Markdown 里，看起来省事。然而几个月下来，两点物理摩擦让我极其痛苦：
-1. 每一轮对话交互，AI 都要把陈旧的任务清单整段塞进系统提示词，白白烧掉几十上百行 Token，还会分散模型对当前正在修改的代码的注意力；
-2. 团队多人协作或分支合并时，这类任务清单文件频发 Git 合并冲突，无端污染了核心代码的提交历史。
-
-调研现存工具时，我发现社区给出的方案走向了沉重的极端：为了管理几个简单的任务，有的方案直接在代码仓库根目录塞入一个超过 200MB 的 Dolt SQL 关系型数据库（`beads`），有的方案在后台常驻一个用 Go 编写的 SQLite 守护进程并做持续向量检索（`engram`）。一个任务追踪工具消耗的系统资源与认知负担，甚至超过了开发者正在编写的业务代码本身。
-
-这颠倒了工具与生产者的关系。
-
-Anchor 选择了一条极度克制的工程路径：把状态移出代码仓库，托管在用户主目录下的单文件轻量状态表（`~/.anchor/state.json`）；首轮对话注入冷启动上下文，第 2 轮起保持 0 Token 损耗；通过语言对应的语法安全注释在触碰代码时精准唤醒，并在代码提交或会话退出时自动核销。
-
-在 v0.2.1 中，我们还为 `/anchor` 增加了防误触详情面板，按回车可以从容查看关联文件与执行命令，并在排版算法中消除了开括号截断毛刺。
-
-希望 Anchor 能让你的代码仓库保持干净，把专注力还给代码本身。
-
----
-
-## 质量验证与构建
-
-基于严格 TypeScript 与 Node 原生测试运行器，保持 100% 标准库覆盖：
-
-```bash
-npm run typecheck  # TypeScript 严格类型检查 (0 错误)
-npm test           # 全套自动化单元测试 (34/34 全绿通过)
-npm run build      # tsup 双格式打包 (ESM/CJS) 与 .d.ts 类型生成
-```
+## 常用操作速查
+
+| 位置 | 输入 / 命令 | 作用 |
+| :--- | :--- | :--- |
+| **输入框直接敲** | `便签: <内容>` 或 `pin: <内容>` | **0ms 直接贴便签**（不触发大模型请求，自动绑定当前改过的文件与 Session） |
+| **斜杠命令** | `/pin <内容>` | 贴一张新便签（支持写 `[2/5]` 或 `1. A 2. B` 自动生成进度条） |
+| **斜杠命令** | `/anchor` | 打开交互面板（支持撕便签、推进度 `+1`、`↪` 穿越回原对话 Session） |
+| **斜杠命令** | `/step 1` | 将 `#1` 便签的进度条往前推进 `+1` 步 |
+| **斜杠命令** | `/anchor jump 1` | 直接切换回 `#1` 便签绑定的那次历史对话 (`switchSession`) |
+| **斜杠命令** | `/done 1` / `/anchor undo` | 撕掉 `#1` 便签，或把刚撕掉的便签重新贴回来 |
+| **终端 CLI** | `anchor` / `anchor step 1` / `anchor done 1` | 不进 Pi 也能在外部终端查看、推进度或撕便签 |
 
 ---