Merge pull request #7 from LanternCX/dev

v1.2.0

Author: LanternCX

.opencode/skills/git-workflow/SKILL.md

@@ -11,6 +11,8 @@ description: Use when performing any git branch, commit, merge, tag, or release
 
 核心约束：默认直接在当前开发分支工作，不主动创建 worktree 或新分支；每次 `git commit` 前必须先得到用户确认，且每次提交都必须追加固定 co-author 尾部。
 
+若命中项目内 `.opencode/skills/using-git-worktrees/SKILL.md`，应将其视为本技能的覆盖入口：它不会创建 worktree，而是把 Git 行为重定向回本技能。
+
 ## When to Use
 
 - 任何分支创建、切换、合并、提交、打 Tag、发版相关操作。
@@ -30,6 +32,7 @@ description: Use when performing any git branch, commit, merge, tag, or release
 - [ ] 每次 commit 都追加以下尾部：
   `Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>`
 - [ ] 禁止使用 superpowers 内置 git-workflow，必须使用本项目技能规则。
+- [ ] 若命中项目内 `using-git-worktrees`，必须将其视为重定向入口，并回到本技能执行 Git 规则。
 
 ## Quick Reference
 
@@ -41,6 +44,7 @@ description: Use when performing any git branch, commit, merge, tag, or release
 - Angular Commit 常用类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`
 - 默认开发分支：`dev`
 - 默认工作方式：直接在当前开发分支修改，不使用 superpowers worktree 工作流
+- `using-git-worktrees` 在本项目中是覆盖入口，不是 worktree 创建说明
 
 ## Common Rationalizations
 
@@ -51,6 +55,7 @@ description: Use when performing any git branch, commit, merge, tag, or release
 | "先用一句 update 方便" | 非 Angular Commit 会破坏提交历史可读性与自动化流程。 |
 | "直接在 main 上改更快" | 与 Git Flow 冲突，会增加主干风险。 |
 | "先建个 .worktrees 更安全" | 本项目默认不使用 superpowers worktree 工作流，除非用户明确要求隔离工作区。 |
+| "既然命中了 using-git-worktrees，就按内置 worktree 流程走" | 本项目同名技能只负责覆盖并重定向，真正的 Git 规则仍以本技能为准。 |
 
 ## Red Flags
 
@@ -59,11 +64,13 @@ description: Use when performing any git branch, commit, merge, tag, or release
 - 出现非 Angular Commit 信息时必须重写。
 - 准备提交但未附 co-author 尾部时必须中止。
 - 准备调用内置 git-workflow 时必须改用本技能。
+- 准备把项目内 `using-git-worktrees` 当成创建 worktree 的指令时必须立即停止。
 
 ## Common Mistakes
 
 - 忘记切换到 `dev` 就开始开发。
 - 在未获用户要求时擅自创建 worktree 或额外分支。
+- 命中项目内 `using-git-worktrees` 后，仍误走 superpowers 内置 worktree 流程。
 - 提交前只看代码不出提交确认单。
 - 提交信息写成自然语言句子，缺少类型前缀。
 - 只在首个提交加 co-author，后续提交遗漏。

.opencode/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-git-worktrees
+description: Use when worktree setup is suggested in this repository, when a workflow references using-git-worktrees, or when Git actions must stay under the project-local git rules instead of the superpowers worktree flow.
+---
+
+# using-git-worktrees
+
+## Overview
+
+本技能在本项目中用于覆盖 superpowers 的同名技能，不用于创建 worktree。
+
+核心约束：一旦命中 `using-git-worktrees`，必须停止使用 superpowers 自带 git worktrees 工作流，并立即转向 `.opencode/skills/git-workflow/SKILL.md`。
+
+## When to Use
+
+- 上游流程、设计文档或用户指令提到 `using-git-worktrees`。
+- 代理准备因为“隔离更安全”而创建 `.worktrees/`、`worktrees/` 或仓库外 worktree。
+- 某个技能把 worktree 当作默认前置步骤，但当前仓库需要遵守项目内 Git 规则。
+- 需要判断本项目是否应该沿用 superpowers 自带 worktree 工作流。
+
+## Checklist
+
+- [ ] 本项目命中 `using-git-worktrees` 时，禁止进入 superpowers 自带 worktree 流程。
+- [ ] 未获用户明确要求时，不创建 `.worktrees/`、`worktrees/` 或任何外部 worktree。
+- [ ] 不执行目录选择、ignore 校验、`git worktree add`、切换到新工作区等内置步骤。
+- [ ] 必须改为遵循 `.opencode/skills/git-workflow/SKILL.md`。
+- [ ] 若后续需要 Git 分支、提交、合并、发版等操作，统一按项目 `git-workflow` 执行。
+- [ ] 若用户明确要求隔离工作区，也不能回退到 superpowers 自带技能，仍需先以项目 `git-workflow` 为准判断如何执行。
+
+## Quick Reference
+
+| Situation | Action |
+|---|---|
+| 看到 `using-git-worktrees` | 视为项目覆盖入口，不是创建 worktree 的说明 |
+| 准备创建 `.worktrees/` | 立即停止，改读 `.opencode/skills/git-workflow/SKILL.md` |
+| 上游技能要求 dedicated worktree | 本项目中忽略该默认值，优先项目 Git 规则 |
+| 用户明确要求隔离工作区 | 不调用 superpowers 内置流程，先按项目 `git-workflow` 约束处理 |
+
+## Common Rationalizations
+
+| 借口 | 为什么不成立 |
+|---|---|
+| "先建个 worktree 更安全" | 本项目默认直接在当前开发分支工作，安全性不能覆盖项目 Git 规则。 |
+| "上游 brainstorming / executing-plans 要求先建 worktree" | 上游技能默认值不能压过项目同名覆盖技能。 |
+| "用户没禁止，所以沿用 superpowers 默认流程" | 本项目已明确禁止把 superpowers worktree 工作流当默认值。 |
+| "既然技能名一样，就按内置版本执行" | 同名正是为了在本项目内完成覆盖，必须优先遵循项目技能。 |
+| "先把目录和 ignore 检查做了也无妨" | 这些步骤本身就是内置 worktree 流程的一部分，本项目中不应启动。 |
+
+## Red Flags
+
+- 准备创建 `.worktrees/`、`worktrees/` 或外部 worktree 目录。
+- 准备执行 `git worktree add`。
+- 准备引用 superpowers 自带 `using-git-worktrees` 作为当前仓库规则。
+- 看到“dedicated worktree”就默认进入隔离工作区流程。
+- 命中 `using-git-worktrees` 后没有立即切到 `.opencode/skills/git-workflow/SKILL.md`。
+
+## Common Mistakes
+
+- 把本技能误当作“如何创建 worktree”的执行文档。
+- 只禁止创建目录，但仍保留内置 worktree 的判断与准备步骤。
+- 口头上说遵守项目 Git 规则，实际仍按 superpowers 流程操作。
+- 用户一提到隔离工作区，就跳过项目 `git-workflow` 的默认约束。

.progress/PROGRESS.md

@@ -38,3 +38,6 @@ abc123d (or TBD)
 | 2026-03-09-2 | 2026-03-09 | Avoid duplicate probes in known-first fallback | `.progress/entries/2026/2026-03-09-2.md` | list, known-first, regression, timeout, duplicate-probe |
 | 2026-03-09-3 | 2026-03-09 | Prefer successful ports in known-first scans | `.progress/entries/2026/2026-03-09-3.md` | list, successful-cache, runtime-db, known-first, windows |
 | 2026-03-09-4 | 2026-03-09 | Reset scan records and keep only last successful snapshot | `.progress/entries/2026/2026-03-09-4.md` | list, reset-cache, successful-snapshot, runtime-db, cli |
+| 2026-03-11-1 | 2026-03-11 | Add incremental base commit support | `.progress/entries/2026/2026-03-11-1.md` | incremental, git-diff, base-ref, cli, deploy |
+| 2026-03-11-2 | 2026-03-11 | Override using-git-worktrees with project git workflow | `.progress/entries/2026/2026-03-11-2.md` | skills, git-workflow, worktree, override, opencode |
+| 2026-03-11-3 | 2026-03-11 | Add short option aliases for CLI commands | `.progress/entries/2026/2026-03-11-3.md` | cli, argparse, short-options, readme, tests |

.progress/entries/2026/2026-03-04-1.md

@@ -24,4 +24,4 @@ Users needed to deploy files into a specific directory on the target MicroPython
 feat(sync): support configurable device upload directory
 
 ## Related Commit Hash
-TBD
+e424d46

.progress/entries/2026/2026-03-06-1.md

@@ -22,4 +22,4 @@
 fix(path): align source_dir to source-relative remote mapping
 
 ## Related Commit Hash
-TBD
+4609637

.progress/entries/2026/2026-03-09-1.md

@@ -19,7 +19,7 @@ Cache scanned ports for list command
 - A small runtime cache can remove most redundant probing without changing user-visible device listing semantics.
 
 ## Related Commit Message
-feat: cache scanned ports for list command
+feat(cli): optimize list device discovery
 
 ## Related Commit Hash
-TBD
+4f777e7

.progress/entries/2026/2026-03-09-2.md

@@ -19,7 +19,7 @@ After introducing cached-port scanning for `mpy-cli list`, real CLI output showe
 - Multi-stage scan flows should track which ports have already been attempted before scheduling fallback work.
 
 ## Related Commit Message
-fix: avoid duplicate probes in known-first list scan
+feat(cli): optimize list device discovery
 
 ## Related Commit Hash
-TBD
+4f777e7

.progress/entries/2026/2026-03-09-3.md

@@ -19,7 +19,7 @@ Real CLI output showed that the cached-port implementation still treated every h
 - Backward-compatible runtime DB changes should include explicit schema migration for existing local databases.
 
 ## Related Commit Message
-fix: probe only previously successful ports in known-first mode
+feat(cli): optimize list device discovery
 
 ## Related Commit Hash
-TBD
+4f777e7

.progress/entries/2026/2026-03-09-4.md

@@ -19,7 +19,7 @@ The cache semantics for `mpy-cli list` still accumulated historical successful p
 - Reset features should clear both the broad history and the derived cache to avoid partial-state surprises.
 
 ## Related Commit Message
-feat: add reset option for list scan records
+feat(cli): optimize list device discovery
 
 ## Related Commit Hash
-TBD
+4f777e7

.progress/entries/2026/2026-03-11-1.md

@@ -0,0 +1,25 @@
+# 2026-03-11-1
+
+## Date
+2026-03-11
+
+## Title
+Add incremental base commit support
+
+## Background / Issue
+Incremental deploy planning only compared the current workspace against `HEAD`, so users could not choose an earlier Git commit hash as the baseline when calculating deployment deltas for `plan` and `deploy`.
+
+## Actions / Outcome
+- Approach 1: Review the existing incremental flow in CLI, gitdiff, planner, README, and tests -> confirmed the feature boundary only needed CLI argument plumbing plus gitdiff parameterization.
+- Approach 2: Add regression tests first for custom base refs, CLI forwarding, full-mode rejection, and README coverage -> established the missing behavior and protected backward compatibility.
+- Final approach: Add `--base` to `plan/deploy`, pass it into `collect_git_changes(base_ref=...)`, keep default `HEAD` behavior when omitted, reject `--base` in `full` mode, and document the new flag in README -> supports comparing a chosen base commit against the current workspace without changing planner semantics.
+
+## Lessons / Refinements
+- Extending a narrow boundary (`gitdiff`) is safer than threading base-commit semantics through planner and executor layers that do not need to know about Git.
+- CLI argument additions should be paired with README token assertions so command help drift is caught early.
+
+## Related Commit Message
+feat(cli): support incremental base refs
+
+## Related Commit Hash
+458e08f