[realtonyyoung]

Fixes AI-3854 (no GitHub issue: a new one would import into Linear as a duplicate of AI-3854)

What & why

declare_plan_document fixed its boundary at the harness's project directory, so a plan document in the worktree a session actually works in was refused by relative and by absolute path. A file in another working tree of the same repository (sharing its git common dir, nested or beside it) is now accepted and sent by absolute path with that worktree as workspace_root; a checkout of another repository is accepted when the agent names it as workspace_root. The tool also takes plan_id, so a session resuming a plan from a new checkout attaches the document to that plan instead of starting a second one.

Where to look

McpPlansServer.DocumentCheckout: the symlink and .. containment check is unchanged and runs against the chosen checkout. A named checkout is recorded so the edit-refresh hook replays it. The server half is kurrent-io/kcap-server#2435; against an older server a worktree path is still refused with a 400 and plan_id is ignored.

Verification

Unit tests: a document in a sibling and in a nested linked worktree is keyed off that worktree and replays identically; another repository is refused until named; a named root outside any git tree is refused; plan_id rides the body but not the replay; ResolveCommonDir agrees for a checkout and its worktree. dotnet publish -c Release reports no IL2026/IL3050 warnings.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Plan documents can be associated with the same plan across linked worktrees or clones. Use an absolute document path for another worktree in the same repository, or provide workspace_root for a document in another repository.
  • When resuming a plan, you can declare a document from another checkout by providing its plan_id.
  • Documents added after tasks are set can join the existing plan. Guidance also explains how to connect related documents.

[linear-code]

AI-3854

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 5aecefe3-044f-45fc-b8f3-f3102df7a587

📥 Commits

Reviewing files that changed from the base of the PR and between 507f14d and ec4ad5f.

📒 Files selected for processing: 2

• src/Capacitor.Cli/Commands/McpPlansServer.cs
• test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• kurrent-io/skills (auto-detected)

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

📝 Walkthrough

Plan document declarations now support documents in linked worktrees and other checkouts. The declaration flow accepts optional workspace_root and plan_id values and retains workspace metadata during serialization and replay.

Changes: Cross-checkout plan declarations

Layer / File(s)	Summary
Resolve shared Git checkout identity src/Capacitor.Cli.Core/GitRepository.cs, test/Capacitor.Cli.Core.Tests.Unit/GitRepositoryGitDirTests.cs	GitRepository resolves the common Git directory for a checkout. Tests cover a main checkout, a linked worktree, and an unrelated checkout.
Resolve and validate declaration paths src/Capacitor.Cli/Commands/McpPlansServer.cs, test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs	BuildDeclaration can use workspace_root as the path base and checkout boundary. Without it, an absolute path in another worktree of the same repository can select that worktree. Tests cover checkout selection, boundary validation, and replay consistency.
Carry declaration metadata through replay src/Capacitor.Cli/Plans/DeclaredDocument.cs, src/Capacitor.Cli/Commands/McpPlansServer.cs, test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs, README.md, kcap/skills/plans/SKILL.md	DeclaredDocument reads and writes workspace_root and adds it to replay arguments when present. plan_id is included in the declaration body but not replay arguments. The documentation describes these options and cross-checkout declarations.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Agent
  participant McpPlansServer
  participant GitRepository
  participant DeclaredDocument
  Agent->>McpPlansServer: Declare document with path, workspace_root, and optional plan_id
  McpPlansServer->>GitRepository: Resolve common directory for checkout comparison
  GitRepository-->>McpPlansServer: Return common directory
  McpPlansServer->>DeclaredDocument: Build declaration with selected checkout metadata
  DeclaredDocument-->>McpPlansServer: Return declaration data
  McpPlansServer-->>Agent: Return declaration body

Loading

Suggested reviewers: alexeyzimarev

Merge Risk: ⚪ Minimal · up to ec4ad

No identified issue blocks merging the cross-checkout declaration changes after normal checks.

Security architecture risk: 🟡 Moderate · up to ec4ad

The change intentionally allows document uploads from additional checkouts. Local path-containment checks remain in place, but authorization and preservation of plan ownership across refreshes depend on receiving-service behavior that could not be verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A caller controlling declaration arguments can now select process-readable files throughout an explicitly named enclosing checkout, including another repository. UTF-8 content at or below 256 KiB is uploaded to the configured service; larger or invalid-UTF-8 files are declared by hash only. Downstream tenant and plan scope cannot be established from the available client evidence.

Trust Boundaries and Controls

• observed — The primary document must pass lexical and symlink-resolved containment against the selected checkout before content is read. Unrelated external repositories require workspace_root; unnamed external worktrees require matching common Git directories. These checks constrain filesystem reach but do not prove authorization to the requested plan on the receiving service.

Resilience and Maintainability Implications

• observed — The pre-existing replay ledger binds entries to the server URL that accepted them and uses best-effort storage with 30-day session retention. Failed or interrupted initial declarations do not create a new replay entry unless HTTP success was observed; this is not an end-to-end transaction with the server.

Hardening Proposals

• proposed — Make the receiving-service contract explicit and validate that plan/workspace authorization, replay without plan_id, and retry after an accepted but unacknowledged POST preserve the intended document ownership. This is a proposal to close an evidence gap, not an observed authorization failure.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: allowing plan documents to be declared from other session checkouts.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Declare plan documents from other session checkouts

🐞 Bug fix ✨ Enhancement 🧪 Tests 🕐 40+ Minutes

AI Description

• Accept plan documents in linked worktrees and explicitly named checkouts without weakening path
 containment.
• Allow declarations to attach to an existing plan and preserve named checkouts during edit refresh.
• Document the workflow and test checkout resolution, request payloads, and replay.

Diagram

graph TD
  A["Declare document"] --> B{"Root named?"} -->|yes| C["Named checkout"] --> E["Chosen checkout"] --> F["Contain and hash"] --> G["Plans API"]
  B -->|no| D["Git common dir"] --> E
  H["Edit refresh"] --> A

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Require workspace_root for every other checkout

• ➕ Simpler checkout selection and fewer implicit Git lookups.
• ➖ Agents must identify and supply the root even for linked worktrees discoverable from an absolute document path.

Recommendation: Keep automatic detection for linked worktrees and require an explicit root for unrelated repositories. This supports the common absolute-path workflow without implicitly trusting paths in other repositories, while reusing the existing containment check.

Files changed (7) +178 / -32

Enhancement (2) +28 / -9

GitRepository.csResolve the Git directory shared by linked worktrees +16/-0

Resolve the Git directory shared by linked worktrees

• Adds ResolveCommonDir, which follows a worktree's commondir pointer and returns the shared Git directory used to identify worktrees of one repository.

src/Capacitor.Cli.Core/GitRepository.cs

DeclaredDocument.csPersist named workspace roots for declaration replay +12/-9

Persist named workspace roots for declaration replay

• Stores an explicitly named checkout in serialized declarations and restores it when edit refresh rebuilds the request. plan_id is not included in replay arguments.

src/Capacitor.Cli/Plans/DeclaredDocument.cs

Bug fix (1) +55 / -15

McpPlansServer.csBuild checkout-aware plan document declarations +55/-15

Build checkout-aware plan document declarations

• Selects a checkout from an explicit workspace_root or a matching Git common directory, then applies the existing containment check. Sends documents in other checkouts by absolute path with their workspace root, forwards optional plan_id, and exposes both arguments in the tool schema.

src/Capacitor.Cli/Commands/McpPlansServer.cs

Tests (2) +86 / -0

GitRepositoryGitDirTests.csTest shared Git directory resolution +16/-0

Test shared Git directory resolution

• Verifies that a main checkout and its linked worktree resolve to the same common directory, unlike an unrelated repository.

test/Capacitor.Cli.Core.Tests.Unit/GitRepositoryGitDirTests.cs

McpPlansServerTests.csTest cross-checkout declaration and replay +70/-0

Test cross-checkout declaration and replay

• Covers sibling and nested worktrees, explicitly named unrelated repositories, invalid or escaping roots, replayed request bodies, and forwarding plan_id without replaying it.

test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs

Documentation (2) +9 / -8

README.mdDocument declaration options for other checkouts +1/-1

Document declaration options for other checkouts

• Describes workspace_root, plan_id, and automatic acceptance of documents in linked worktrees in the MCP tool overview.

README.md

SKILL.mdRevise agent guidance for cross-checkout plans +8/-7

Revise agent guidance for cross-checkout plans

• Explains how documents join a session's plan, when to provide workspace_root, and how to use plan_id when resuming from another checkout.

kcap/skills/plans/SKILL.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Requested plans are ignored ✗ Dismissed

Description

BuildDeclaration adds plan_id to the request body, but kcap-server's declaration request and
plan-selection logic do not consume it. When a continuing session declares a document with a new
key, the server selects a plan from document claims instead of attaching the document to the
requested plan.

Code

src/Capacitor.Cli/Commands/McpPlansServer.cs[R374-375]

+        if (OptionalPlanId(args) is { } planId)
+            body["plan_id"] = planId;

Relevance

●●● Strong

Plan continuation and task adoption semantics are actively reviewed and correctness findings are
accepted.

PR-#1254
PR-#1112

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The CLI sends plan_id, while the server DTO has no corresponding field and its store derives the
destination plan solely from document claims or a deterministic document ID.

kcap-cli -> kcap-server
src/Capacitor.Cli/Commands/McpPlansServer.cs[370-378]
External repo: kurrent-io/kcap-server, src/Capacitor.Api.Public.Abstractions/Plans/DeclarePlanDocumentRequest.cs [5-14]
External repo: kurrent-io/kcap-server, src/Capacitor.Server.Services/Plans/PlanStore.cs [63-75]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pinned server has no declaration `plan_id` field and selects plans from document claims, so the CLI's new argument cannot attach a newly keyed document to an existing plan.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/McpPlansServer.cs[374-375]
- /cross_repos/kcap-server/src/Capacitor.Api.Public.Abstractions/Plans/DeclarePlanDocumentRequest.cs[5-14]
- /cross_repos/kcap-server/src/Capacitor.Server.Services/Plans/PlanStore.cs[63-75]

## Recommended Fix
Add and validate explicit plan selection in the server declaration endpoint and store, deploy that support before advertising the CLI argument, and test a continuation declaration against the deployed server contract.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Other checkouts fail server validation ✗ Dismissed

Description

BuildDeclaration sends an alternate checkout as workspace_root with an absolute path, but
kcap-server selects the session's captured root ahead of the supplied root. A sibling checkout is
rejected with path_rejected; a nested worktree can instead be accepted under the parent root and
receive the wrong document key.

Code

src/Capacitor.Cli/Commands/McpPlansServer.cs[R339-341]

+        var ownCheckout = PathComparison.Equal(checkout, repoRoot ?? cwd);
+        var keyRoot     = ownCheckout ? repoRoot : checkout;
+        string Wire(string path) => ownCheckout ? WirePath(path, repoRoot) : path;

Relevance

●●● Strong

Cross-version request-contract mismatches affecting scope or placement are treated as correctness
issues.

PR-#761

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The CLI emits an absolute path and alternate root. The server overrides that root with the captured
session root, normalizes the path against it, and computes the key from it.

kcap-cli -> kcap-server
src/Capacitor.Cli/Commands/McpPlansServer.cs[337-352]
External repo: kurrent-io/kcap-server, src/Capacitor.Api.Public/Plans/PlanEndpointHandlers.cs [45-59]
External repo: kurrent-io/kcap-server, src/Capacitor.Server.Services/Sessions/Plans/PlanDocumentKey.cs [45-76]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pinned server prioritizes the session root over the declaration's alternate checkout root, rejecting sibling paths or miskeying nested worktrees.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/McpPlansServer.cs[337-352]
- /cross_repos/kcap-server/src/Capacitor.Api.Public/Plans/PlanEndpointHandlers.cs[45-59]

## Recommended Fix
Deploy server support that validates and keys declarations against an authorized alternate checkout root before enabling these CLI inputs. Add an integration test covering sibling and nested worktrees against that server version.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. The pull request misses issue links ✗ Dismissed

Description

The PR description begins with Fixes AI-3854 but contains no GitHub closing keyword followed by a
#<number> reference on the same reference line. Without both references together, reviewers and
automation cannot associate the change with the required GitHub issue and Linear issue.

Code

README.md[737]

+- **`declare_plan_document`** — declare the document this session works from: `kind` (`plan`, `spec` or `design`) and `path`, plus optional `argues_from` (the spec a plan implements, or the design a spec refines, so both land on one plan), `work_item_id`, `plan_id` (the plan to attach it to, when continuing one from a different checkout) and `workspace_root` (the checkout the document is in, when it is not the project directory). A document in another worktree of the session's repository is accepted by absolute path without naming it; one in another repository needs `workspace_root`. The CLI reads the file, sends its SHA-256 and — at or under 256 KB — its content, and keys the path relative to the git repository root so the declared document and its discovered twin share one identity; a larger file is declared by hash only and the result says so. Returns `plan_id`, `document_key` and `created`; declaring the same file again lands on the same plan and replaces the stored copy with the file's current text, so an agent declares it again after changing it (Claude Code sessions do this automatically for `Write`/`Edit`/`MultiEdit`; see [Declared-document refresh](#what-it-records)).

Relevance

●●● Strong

The repository explicitly requires paired GitHub and Linear references in PR descriptions.

PR-#659

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The supplied PR description references only the Linear issue AI-3854; it does not include a
same-line GitHub closing reference such as Closes #123, contrary to PR Compliance ID 2897991.

Rule 2897991: PR description must contain both GitHub and Linear issue references; PR title must not contain issue IDs

---

4. A checkout alias can split one plan document ✓ Resolved

Description

ownCheckout compares checkout paths as strings, so a symlink alias of the session's own checkout
is treated as another checkout and sent with an absolute path and aliased workspace_root. When an
agent names that alias, the declaration no longer uses the root-relative path used for the same file
through the session checkout, allowing the two declarations to acquire different document
identities.

Code

src/Capacitor.Cli/Commands/McpPlansServer.cs[R339-341]

+        var ownCheckout = PathComparison.Equal(checkout, repoRoot ?? cwd);
+        var keyRoot     = ownCheckout ? repoRoot : checkout;
+        string Wire(string path) => ownCheckout ? WirePath(path, repoRoot) : path;

Relevance

●●● Strong

Recent path-canonicalization and symlink findings were accepted as correctness issues.

PR-#191
PR-#643

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

NamedCheckout returns the root found through the supplied path, while FindRoot preserves that
path's spelling. PathComparison.Equal does not resolve links, and the new equality branch
determines whether the request sends a root-relative or absolute path; the existing declaration test
shows the root-relative form used for the session checkout.

src/Capacitor.Cli/Commands/McpPlansServer.cs[329-344]
src/Capacitor.Cli/Commands/McpPlansServer.cs[394-401]
src/Capacitor.Cli.Core/GitRepository.cs[8-25]
src/Capacitor.Cli.Core/PathComparison.cs[17-25]
test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs[95-111]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A symlink alias of the session checkout is classified as a separate checkout, changing the wire path and workspace root for the same document.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/McpPlansServer.cs[329-341]
- src/Capacitor.Cli/Commands/McpPlansServer.cs[385-401]

## Recommended Fix
Compare canonical checkout locations when selecting own-checkout behavior, and ensure paths sent for an aliased checkout use the same document identity as paths sent through the session checkout. Add a test declaring one file through both spellings.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. The commit subject fails format checks 📘 Rule violation ⚙ Maintainability

Description

The commit subject is Declare plan documents from the session's other checkouts, which does not
end with the required (#digits) GitHub issue reference. The missing reference makes the subject
fail the repository's enforced merge-subject format.

Code

README.md[737]

+- **`declare_plan_document`** — declare the document this session works from: `kind` (`plan`, `spec` or `design`) and `path`, plus optional `argues_from` (the spec a plan implements, or the design a spec refines, so both land on one plan), `work_item_id`, `plan_id` (the plan to attach it to, when continuing one from a different checkout) and `workspace_root` (the checkout the document is in, when it is not the project directory). A document in another worktree of the session's repository is accepted by absolute path without naming it; one in another repository needs `workspace_root`. The CLI reads the file, sends its SHA-256 and — at or under 256 KB — its content, and keys the path relative to the git repository root so the declared document and its discovered twin share one identity; a larger file is declared by hash only and the result says so. Returns `plan_id`, `document_key` and `created`; declaring the same file again lands on the same plan and replaces the stored copy with the file's current text, so an agent declares it again after changing it (Claude Code sessions do this automatically for `Write`/`Edit`/`MultiEdit`; see [Declared-document refresh](#what-it-records)).

Relevance

●●● Strong

Repository compliance findings for missing issue references are typically accepted.

PR-#659

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The supplied commit subject and PR title lack the required trailing GitHub issue reference, while PR
Compliance ID 2897961 requires a single imperative subject ending in (#<digits>) and no more than
80 characters.

Rule 2897961: Enforce single-clause imperative commit subject with GitHub issue reference and 80-char limit

Dismiss ↗ | View ↗

---

Context sources

✅ Compliance rules (platform): 63 rules

✅ Cross-repo context — repo relationships

  Explored: repo: kurrent-io/kcap-server (sha: 795c0f63) — View relationship

Review mode: Auto: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 13/18, lines 210/200; both must reach the floor). Router rationale: Multiple path-containment, checkout-resolution, replay, and API changes create dense independent risk.

Tip of the day

💡 Did you know, you can pick a display mode instead of tweaking every Display option by hand

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[coderabbitai]

🔇 Additional comments: 7

src/Capacitor.Cli.Core/GitRepository.cs: 1

96-110: LGTM!

test/Capacitor.Cli.Core.Tests.Unit/GitRepositoryGitDirTests.cs: 1

26-40: LGTM!

test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs: 1

26-35: LGTM!

Also applies to: 180-237

src/Capacitor.Cli/Plans/DeclaredDocument.cs: 1

9-35: LGTM!

kcap/skills/plans/SKILL.md: 1

21-26: LGTM!

Also applies to: 63-63, 69-69

src/Capacitor.Cli/Commands/McpPlansServer.cs: 1

329-332: 🔒 Security & Privacy | 🛡️ Detected with Advanced Tier

Security Misconfiguration

Reachability: External
Exploitability: Moderate
CWE: CWE-22 — Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')

workspace_root intentionally selects another Git checkout. NamedCheckout requires the directory to be inside a Git working tree, and ContainedPath still rejects paths and symlinks outside that checkout. The tool schema documents worktrees and clones as supported selectors, and tests cover cross-repository declarations and replay. This is an explicit, approval-marked operation, not an accidental bypass of the session boundary.

Likely an incorrect or invalid review comment.

README.md-737-737: 1

737-737: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Reduce the repeated "again" in the declare_plan_document bullet.

The sentence uses "again" twice: once for re-declaring the same file and once for re-declaring after a change. Rewrite one clause to remove the repeat.

Source: Linters/SAST tools

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: a9cfa0eb-7ef8-4d83-9f39-ecb3df616406

📥 Commits

Reviewing files that changed from the base of the PR and between 703a3d8 and 507f14d.

📒 Files selected for processing: 7

• README.md
• kcap/skills/plans/SKILL.md
• src/Capacitor.Cli.Core/GitRepository.cs
• src/Capacitor.Cli/Commands/McpPlansServer.cs
• src/Capacitor.Cli/Plans/DeclaredDocument.cs
• test/Capacitor.Cli.Core.Tests.Unit/GitRepositoryGitDirTests.cs
• test/Capacitor.Cli.Tests.Unit/Commands/McpPlansServerTests.cs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• kurrent-io/skills (auto-detected)

Limit details: You’ve used all 10 included reviews currently available.