Merge dev → main (automated)

.pi/test-config.json

@@ -0,0 +1,6 @@
+{
+  "suiteCommands": [
+    "npm --silent test -- tests/cli",
+    "npm --silent test -- tests/unit"
+  ]
+}

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v1.0.11 (2026-08-16)
+### Features
+- Idle tracking now requires the same slots to stay free, not just any slots. (WL-0MSG7P9N8009PCKG)
+- Add, edit, or remove notes directly on any markdown document while reviewing it. (WL-0MSKV6SKK008MMXR)
+- Idle time now automatically implements small, low-risk planned tasks. (WL-0MSM9HEH8001A55I)
+- Agent now auto-resumes after mid-session compaction instead of waiting for you to say "continue". (WL-0MSMGGPWR000MZ0O)
+- Downtime audits now run one analysis at a time, so they fit in cheap mode's 2-slot capacity. (WL-0MSORQ1RG005DGUS)
+- Closing a pi agent session now frees up its model lease right away. (WL-0MSGI7UIH008USVB)
+- Stage-filtered and child lists now sort by priority first, matching your main worklist. (WL-0MSOPHLD1000EWNN)
+### Bug Fixes
+- Fixed downtime claiming so failed claims no longer log as successful dispatches. (WL-0MSLWJ310000ND0X)
+- Downtime dispatches now correctly report failures instead of falsely logging success. (WL-0MSLWJ3I70031Z8U)
+- Audits with a "Yes" verdict now properly advance items even when some checks used fallback evidence. (WL-0MSN7XAUS008WOPQ)
+- Audits now auto-recover from JSON errors instead of stopping. (WL-0MSNKWLER003EGE0)
+- Sync now blocks merges from unknown authors to protect your worklog data. (WL-0MSOYWWS4009HTCB)
+- Fixed an issue where items deeper than two levels couldn't be expanded in the work list. (WL-0MSQ3FH1K000MMJW)
+- Fixed downtime jobs being dispatched twice by ensuring only one worker claims each job. (WL-0MSRDEWES0059TZN)
+- Retrying a create command now returns the existing item instead of making a duplicate. (WL-0MSTNG2QF0049B97)
+- Audit tier failures now count as strikes instead of being silently ignored. (WL-0MSLWJ2KP0002SV0)
+- Fixed plugin link breaking after worktree cleanup, so prefix+l keeps working. (WL-0MSRG481O007QVEA)
+- Fixed the build so the herdr package compiles correctly again. (WL-0MSNSZ4R6009AU0N)
+### Other
+- Improved game stability and performance through code quality enhancements. (WL-0MS87KJZU006XM5M)
+- Fixed duplicate downtime work: audit and plan tasks can now be dispatched twice, wasting idle time on repeat panes. (WL-0MSRBFFLN005W3VT)
+- Clarified how agent setup files are installed and how local and global guidance relate. (WL-0MSKEJK4G008BMS0)
+
 ## v1.0.10 (2026-08-12)
 ### Features
 - Idle detection now only counts local activity, so remote-only traffic won't block downtime dispatch. (WL-0MSL2ZQIF006QB4Q)

CLI.md

@@ -121,8 +121,14 @@ Options:
 - `--audit-text <text>` — Set structured audit text when creating an item. The audit result is stored in the `audit_results` table (the sole source of truth for audit state). Prefer `--audit-file` for file-based input to avoid shell-escaping issues (see docs/AUDIT_STATUS.md).
 - `--audit-file <file>` — Read audit text from a file (recommended for large or shell-sensitive content).
 - `--prefix <prefix>` — Override default ID prefix (repo-local scope) (optional).
+- `--allow-duplicate` — Bypass the dedup guard: create a new item even when a recent non-terminal item with the same title exists (optional).
+- `--dedup-window <duration>` — Dedup match window, e.g. `30s`, `5m`, `1h` or raw milliseconds (optional; default: `5m`).
 - `--json` — Output JSON (optional).
 
+Dedup guard:
+
+- Retrying an identical `wl create` (common when agents lose the tool result to output trimming) returns the existing recent non-terminal item with a `duplicateOf` marker instead of creating a byte-identical twin. Only items created within the `--dedup-window` (default 5 minutes) whose title matches case- and whitespace-insensitively are reused; completed/deleted items are never matched. Pass `--allow-duplicate` when a genuinely new item is needed. In JSON mode the response carries a top-level `id` field first and a `duplicateOf` field on a dedup hit; human mode prints an `ID: <id>` line first.
+
 Examples:
 
 ```sh
@@ -1060,7 +1066,7 @@ Other commands cover repository bootstrap and local system status. Use these to
 
 ### `init`
 
-Initialize Worklog configuration in the repository (creates `.worklog` and default config). `wl init` also installs `AGENTS.md` in the project root with a pointer line to the global `AGENTS.md`. If `AGENTS.md` already exists, it prompts before inserting the pointer and preserves the existing content (unless you pass `--agents-template` for unattended runs). When workflow templates are available, `wl init` prompts you to choose between no formal workflow, a basic Worklog-aware workflow, or manual management (unless you pass `--workflow-inline` for unattended runs).
+Initialize Worklog configuration in the repository (creates `.worklog` and default config). `wl init` also installs `AGENTS.md` in the project root, prefixed with a pointer line to the global `AGENTS.md`. If `AGENTS.md` already contains the pointer line, installation is skipped (idempotent, no prompt). If `AGENTS.md` exists without the pointer, it prompts O/A/M — **O**verwrite (destructive), **A**dd pointer (keeps existing content), **M**anual (skip) — unless you pass `--agents-template` for unattended runs. When workflow templates are available, `wl init` prompts you to choose between no formal workflow, a basic Worklog-aware workflow, or manual management (unless you pass `--workflow-inline` for unattended runs). See [AGENTS.md Install Model](docs/AGENTS-INSTALL.md) for the full install flow.
 
 Options:
 

DATA_SYNCING.md

@@ -64,6 +64,43 @@ Set in `.worklog/config.yaml` (local) or `.worklog/config.defaults.yaml` (team d
   - Git remote used for sync
 - `syncBranch` (string, default `refs/worklog/data`)
   - Git ref used for the canonical JSONL file
+- `syncAllowForeignAuthor` (boolean, default false)
+  - Allow merging commits authored by a different identity than the store's
+    configured `user.email` (see [Author-Identity Gate](#author-identity-gate)).
+    The CLI flag `wl sync --allow-foreign-author` takes precedence over this
+    config value.
+
+### Author-Identity Gate
+
+Before importing anything, `wl sync` inspects the author emails of the commits
+on the remote worklog ref since the last-known sync point
+(`git log <remoteTrackingRef> --format=%h%x09%ae --not <lastSyncedRef>`). If any
+incoming commit fails the gate, the sync refuses with a non-zero exit code, a
+clear error naming the offending commit(s) and the remote ref, and leaves the
+local database untouched:
+
+- **Empty author email** → unconditional refusal. A commit with no author email
+  (e.g. a store whose git `user.email` is unset) is never merged, even with
+  `--allow-foreign-author`.
+- **Foreign author email** → refused by default when it differs from the repo's
+  configured `user.email`; allowed when `wl sync --allow-foreign-author` is
+  passed or `syncAllowForeignAuthor: true` is set in config.
+- **`user.email` unset** → the foreign-email comparison is skipped (only the
+  empty-email gate applies).
+
+Example refusal:
+
+```
+✗ Sync failed: Refusing to merge worklog data from refs/worklog/remotes/origin/worklog/data: 1 incoming commit(s) fail the author-identity gate.
+- 5fc880a: empty author email
+```
+
+The gate exists because a second worklog store with an empty/foreign git
+identity can silently overwrite work items and invalidate audits (see
+[Refused Sync / Polluted Ref Recovery](docs/SYNC_IDENTITY_GATE.md)). The
+last-known sync point is persisted in `.worklog/last-synced-ref` after each
+successful non-dry-run sync; when the file is absent, the whole remote ref
+history is scanned.
 
 ### Troubleshooting
 

README.md

@@ -114,6 +114,8 @@ You can get a lot of value from using Worklog as a memory for your agents. But y
 | [API.md](API.md) | REST API endpoints and usage |
 | [docs/FILE_PATH_CONVENTION.md](docs/FILE_PATH_CONVENTION.md) | File path convention for work item descriptions |
 | [docs/CROSS_PROJECT_POLLUTION_CLEANUP.md](docs/CROSS_PROJECT_POLLUTION_CLEANUP.md) | Detecting and removing cross-project worklog pollution (`wl doctor foreign-items`) |
+| [docs/SYNC_IDENTITY_GATE.md](docs/SYNC_IDENTITY_GATE.md) | Refusing foreign/empty-author commits on sync (`--allow-foreign-author`, polluted-ref recovery) |
+| [docs/AGENTS-INSTALL.md](docs/AGENTS-INSTALL.md) | How `wl init` installs AGENTS.md / workflow guidance and how local rules relate to the global agent file |
 
 ### Reference
 

docs/AGENTS-INSTALL.md

@@ -0,0 +1,210 @@
+# AGENTS.md Install Model
+
+How `wl init` installs agent guidance into a project, how that local guidance
+relates to the global agent file, and where duplication/conflict risk remains.
+
+> **Status:** documents the current behavior (verified against
+> `src/commands/init.ts` and `tests/cli/init.test.ts`).
+> A recommendation to change this model is tracked in
+> WL-0MSKEJK4G008BMS0 and the implementation vehicle is
+> WL-0MSIXMKOX0052514 (open).
+
+## Overview
+
+Running `wl init` in a fresh project performs two agent-guidance installs:
+
+1. **`templates/AGENTS.md` → `<projectRoot>/AGENTS.md`** — the project-local
+   agent instruction file (258 lines of work-item tracking rules, CRITICAL
+   RULES, a CLI cheat-sheet, and architecture notes).
+2. **Workflow guidance → inlined into `AGENTS.md`** — the optional workflow
+   template (`templates/WORKFLOW.md`) is *inlined* between
+   `<!-- WORKFLOW: start -->` / `<!-- WORKFLOW: end -->` markers inside the
+   project `AGENTS.md`; a standalone `WORKFLOW.md` file is **never** written
+   to the repository.
+
+Both installs are prefixed with a **pointer line** that defers to the global
+`~/.pi/agent/AGENTS.md` file when one is present:
+
+```
+Follow the global AGENTS.md in addition to the rules below. The local rules below take priority in the event of a conflict.
+```
+
+## Install flow
+
+```
+wl init
+  ├─ locateAgentTemplate()
+  │    templates/AGENTS.md (packaged) → fallback <projectRoot>/templates/AGENTS.md
+  │
+  ├─ ensureAgentTemplateInstalled()
+  │    │
+  │    ├─ AGENTS.md does NOT exist ──► write "{pointer}\n\n{template}"   (always installs)
+  │    │
+  │    └─ AGENTS.md EXISTS
+  │         │
+  │         ├─ pointer present ──────► no-op ("pointer already present")  ← idempotent
+  │         │
+  │         └─ pointer absent
+  │              ├─ action=overwrite ► replace with "{pointer}\n\n{template}"
+  │              ├─ action=append ───► prepend "{pointer}\n\n{existing}"
+  │              ├─ action=skip ─────► no-op ("user chose to manage manually")
+  │              └─ no action ───────► interactive O/A/M prompt → same actions
+  │
+  └─ ensureWorkflowTemplateInstalled()
+       └─ --workflow-inline yes (or prompt answer)
+            └─ insertWorkflowLoaderIntoAgents(AGENTS.md)
+                 │  repo WORKFLOW.md preferred, else packaged template
+                 └─ insert "<!-- WORKFLOW: start -->…<!-- WORKFLOW: end -->"
+                    if not already present                              ← idempotent
+```
+
+### Pointer line
+
+The pointer line is the constant `WORKLOG_AGENT_POINTER_LINE` in
+`src/commands/init.ts`:
+
+```ts
+const WORKLOG_AGENT_POINTER_LINE =
+  'Follow the global AGENTS.md in addition to the rules below. The local rules below take priority in the event of a conflict.';
+```
+
+It is always written as the first non-empty line of the installed `AGENTS.md`.
+Its semantics:
+
+- **Defer to the global file** — when `~/.pi/agent/AGENTS.md` exists (the
+  SorraAgents global install), agents should read it for core workflow
+  instructions.
+- **Local priority on conflict** — project-local rules take precedence over
+  global ones when they disagree.
+
+The pointer is also the idempotence key: `analyzeAgentContent()` detects it as
+`firstNonEmpty === WORKLOG_AGENT_POINTER_LINE`, and `ensureAgentTemplateInstalled()`
+returns `skipped: true, reason: 'pointer already present'` without touching the
+file — re-running `wl init` never duplicates the pointer or template.
+
+### O/A/M prompt
+
+When `AGENTS.md` exists without the pointer and no `--agents-template` flag is
+given, `promptAgentTemplateAction()` asks:
+
+| Choice | Meaning | Effect |
+|--------|---------|--------|
+| **O** – Overwrite | Replace the existing AGENTS.md entirely | Destructive; no chance of conflict with existing content |
+| **A** – Add pointer | Prepend the pointer line, keep existing content | Non-destructive; retains existing instructions |
+| **M** – Manual | Skip; user manages AGENTS.md themselves | No-op; Worklog agent guidance is not installed |
+
+### CLI flags
+
+| Flag | Values | Behavior |
+|------|--------|----------|
+| `--agents-template` | `overwrite` (or `o`), `append` (or `a`), `skip` (or `m`/`manual`/`manage`) | Non-interactive action when AGENTS.md exists without the pointer |
+| `--workflow-inline` | `yes`/`true`/`1`, `no`/`false`/`0` | Inline workflow template into AGENTS.md (`yes`) or not (`no`); omitted → interactive prompt |
+
+`--agents-template skip` is the common choice for unattended init
+(see [WL-0MKVRI3580RXZ54H], the `--agents-template` flag item).
+
+### Idempotence
+
+| Scenario | Result |
+|----------|--------|
+| No `AGENTS.md` | Installs `{pointer}\n\n{template}` |
+| `AGENTS.md` with pointer | No-op — pointer already present |
+| `AGENTS.md` without pointer, `--agents-template skip` | No-op |
+| `AGENTS.md` without pointer, `--agents-template overwrite` | Replaces file |
+| `AGENTS.md` without pointer, `--agents-template append` | Prepends pointer, keeps content |
+| `--workflow-inline yes` on re-run | No-op — markers already present |
+
+### WORKFLOW.md: inlining only
+
+`ensureWorkflowTemplateInstalled()` never writes a standalone `WORKFLOW.md`
+into the project. Instead it **inlines** the workflow content (repo
+`WORKFLOW.md` preferred, else packaged template) into `AGENTS.md` between
+`<!-- WORKFLOW: start -->` and `<!-- WORKFLOW: end -->` markers, at the top of
+the file. Insertion is skipped when the markers are already present.
+
+## Local vs global relationship
+
+Two sources of agent guidance exist:
+
+| | Local (`templates/AGENTS.md`) | Global (`AGENTS_GLOBAL.md`) |
+|---|---|---|
+| **Install target** | `<projectRoot>/AGENTS.md` via `wl init` | `~/.pi/agent/AGENTS.md` via SorraAgents `scripts/install_pi.sh` |
+| **Install mechanism** | Copied (with pointer prefix) | Symlinked |
+| **Scope** | One project | All projects on the machine |
+| **Content** | 258 lines: CRITICAL RULES, work-item types/priorities, CLI cheat-sheet, architecture notes | Full agent workflow: work-item lifecycle, workflow steps, push policy, types/priorities |
+| **Drift risk** | High — duplicated content must be edited twice | Low — single source |
+
+### Precedence
+
+The pointer line (installed by `wl init`) makes the relationship explicit:
+
+> *"Follow the global AGENTS.md **in addition to** the rules below. The local
+> rules below take priority **in the event of a conflict**."*
+
+So precedence is: **local project rules > global file**, with both being read.
+
+### Duplication and conflict risk
+
+The two files overlap substantially — both carry CRITICAL RULES, work-item
+Types, priorities, and workflow guidance. That duplication is a real drift
+risk: a change (e.g. adding an issue type) must be applied to both files.
+Confirmed example: the recent `docs` issue-type addition had to be applied to
+`templates/AGENTS.md` **and** `AGENTS_GLOBAL.md` (both carry
+`--issue-type: … docs …` today).
+
+## Interaction with the global install
+
+- `wl init` does **not** detect whether `~/.pi/agent/AGENTS.md` exists, and
+  does **not** delegate to it. It unconditionally installs its own template
+  content (258 lines), prefixed with the pointer line.
+- The pointer line is the *only* acknowledgement of the global file: it tells
+  agents to also read the global file, but the local template content is still
+  installed in full.
+- There is **no delegation today** — no code path that says "if the global
+  file exists, skip the template and just write a reference."
+
+### Environments
+
+| Environment | What agents see |
+|-------------|-----------------|
+| **Standalone** (no SorraAgents global install) | Only the project `AGENTS.md` (pointer line points at a file that does not exist — harmless, but no global workflow is loaded) |
+| **Global** (SorraAgents `install_pi.sh` run) | Both the global `~/.pi/agent/AGENTS.md` (symlinked from `AGENTS_GLOBAL.md`) and the project `AGENTS.md`, with local rules taking precedence |
+
+## Drift history
+
+- **`docs` issue-type change** — applied to both `templates/AGENTS.md` and
+  `AGENTS_GLOBAL.md` (drift risk confirmed in practice).
+- **SorraAgents dedup items** (SA-0MSITKHPW002XG4G, SA-0MSIUUYRD002GC8W,
+  SA-0MSITKOXI007XD4N — completed): SorraAgents adopted a
+  "reference global instead of duplicating" model. Its own project
+  `AGENTS.md` now starts with a short pointer to the global file instead of
+  duplicating the full content. ContextHub's template has **not** followed.
+
+## Recommendation
+
+**Adopt the single-source-of-truth model: delegate agent-guidance/workflow setup to the SorraAgents global install** (the reference-global pattern), with implementation tracked in WL-0MSIXMKOX0052514. The current duplicated model should be retired.
+
+### Evidence
+
+1. **Confirmed duplication.** `templates/AGENTS.md` (258 lines) and `AGENTS_GLOBAL.md` both carry CRITICAL RULES, work-item Types, priorities, and workflow guidance. The pointer line acknowledges the global file but the full template content is still installed — the pointer defers, the content duplicates.
+2. **Confirmed drift in practice.** The `docs` issue-type change had to be applied to both files. Any future guidance change carries the same two-file maintenance burden (or worse, is applied to only one, silently diverging behavior between projects and machines).
+3. **SorraAgents already adopted the model.** SA-0MSITKHPW002XG4G, SA-0MSIUUYRD002GC8W, SA-0MSITKOXI007XD4N (completed) moved SorraAgents to reference-global: its project `AGENTS.md` now starts with a short pointer to `~/.pi/agent/AGENTS.md` instead of duplicating content. ContextHub's template has not followed.
+4. **ContextHub's own project AGENTS.md already uses the pattern.** The installed `<projectRoot>/AGENTS.md` starts with a "Global agent guidance" section referencing `~/.pi/agent/AGENTS.md` — the template is out of step with the repo's own practice.
+5. **Delegation has no downsides for the global environment.** When the SorraAgents install is present, the global file carries the canonical workflow; the project file only needs project-specific rules plus a reference line. This matches what `wl init`'s pointer line already half-intends.
+
+### What the change looks like (scope boundary — NOT implemented here)
+
+- When the SorraAgents global install is detected (`~/.pi/agent/AGENTS.md` resolves to a SorraAgents symlink), `wl init` should emit the canonical reference structure (a `## Global agent guidance` section referencing `~/.pi/agent/AGENTS.md`, plus a `## Project-specific guidance` section), rather than installing the full 258-line template.
+- Standalone environments (no global install) keep a self-contained `AGENTS.md` so Worklog remains usable without SorraAgents.
+- **No behavioral change is made as part of this item (WL-0MSKEJK4G008BMS0)** — the investigation only documents and recommends. Implementation lands in WL-0MSIXMKOX0052514.
+
+## Related
+
+- `src/commands/init.ts` — `ensureAgentTemplateInstalled`,
+  `promptAgentTemplateAction`, `ensureWorkflowTemplateInstalled`,
+  `WORKLOG_AGENT_POINTER_LINE`, `WORKLOG_AGENT_TEMPLATE_RELATIVE_PATH`
+- `templates/AGENTS.md`, `templates/WORKFLOW.md` — the installed templates
+- `tests/cli/init.test.ts` — behavior tests (pointer insertion, idempotence,
+  `--agents-template`, `--workflow-inline`)
+- [docs/tutorials/01-your-first-work-item.md](tutorials/01-your-first-work-item.md) —
+  the init walkthrough that mentions the AGENTS.md prompt