[dnlrsls]

🔗 Linked Issue

Closes #1580

Lifecycle Evidence

• Every linked issue is approved and has a real assignee (not necessarily the PR author).
• Evidence is proportional: trivial changes have scope/checks; bugs have current remote main SHA, reproduction, root cause, and regression tests; high-risk changes have approved design, non-goals, and completed independent review.
• Evidence may live in the issue; no separate design document is required by default.
• Existing PRs also comply before merge; backlog-wide migration is not an activation prerequisite.

---

🏷️ PR Type

• type:bug — Bug fix
• type:feature — New feature
• type:question — Question requiring tracked work
• type:docs — Documentation only
• type:refactor — Code refactoring (no behavior change)
• type:chore — Maintenance, dependencies, tooling
• type:breaking-change — Breaking change

---

📝 Summary

• Document the accepted single-user, trusted-local-client policy and distinguish standalone HTTP, session-owned HTTP, native MCP, and cloud authority.
• Separate explicit owner consistency from authentication, preserving deliberate cross-project maintenance.
• Keep broader authentication hardening separately scoped; no runtime behavior changes.

📂 Changes

File	Change
DOCS.md	Add local caller trust and ownership policy, boundary table, representative outcomes, and compatibility obligations.

🧪 Test Plan

• Focused regression: N/A, documentation-only; no Go behavior changed.
• Affected package tests: N/A, documentation-only; no Go behavior changed.
• git diff --check: PASS before commit.
• Node structural checks against runtime PATCH/DELETE route auth flags, session-owned Handler authentication, MCP profile membership and owner-independent update signature: PASS.
• Full changed-section readback and changed-path inspection: PASS, only DOCS.md, 31 added lines.
• Native assessment: passive, reviewDue=false, structuralReadbackOnly=true. No native review or independent verifier required.

---

🤖 Automated Checks

After pushing/opening the PR, GitHub CI runs the broad unit/E2E/lint and applicable platform checks. These automated statuses remain pending until the actual checks run; do not claim a pass from local evidence. Windows checks run for PRs but not merge groups, and are not among the six required contexts. Lint and Check PR Has No Transient Artifacts also run for PRs but are not required contexts; Lint also runs on pushes to main. All required checks must pass before merge:

Check	What it verifies	Status
Check Issue Reference	PR body contains Closes #N / Fixes #N / Resolves #N	⏳
Check Issue Has status:approved	Every linked issue is approved and assigned	⏳
Check PR Has type: Label*	Canonical labels, applicability, and cardinality	⏳
Check PR Has No Transient Artifacts	PR files comply with the Transient Artifact Policy	⏳
Unit Tests	go test ./... passes	⏳
E2E Tests	go test -tags e2e ./internal/server/... passes	⏳
Plugin Tests	npm test passes in plugin/pi	⏳
Lint	golangci-lint reports no new findings	⏳
Windows Setup Test	Windows setup preserves absolute paths and MCP job-object parent-lifetime tests pass	⏳
Cloud Sync Wrapper Tests (Windows)	Cloud sync wrapper and missing-PowerShell-Engram tests pass on Windows	⏳

---

✅ Contributor Checklist

• I linked an approved issue above (Closes #N)
• I added exactly one type:* label to this PR
• I recorded actual focused regression and affected package test commands/outcomes for behavior changes, or N/A for docs-only changes
• I recorded additional applicable local checks for an unpushed/no-PR or high-risk change, and identified any missing CI evidence
• Docs updated (if behavior changed)
• Commits follow conventional commits format
• No Co-Authored-By trailers in commits
• I checked every changed path against the Transient Artifact Policy

---

💬 Notes for Reviewers

Maintainer acceptance: #1580 (comment)

Risk: none. Passive documentation of existing behavior, no authentication or mutation changes. Historical tests in the issue are not new test evidence. Hosted CI remains pending. No merge or manual issue closure is authorized by this PR creation.

Summary by CodeRabbit

• Documentation
  • Added guidance on authentication and ownership boundaries across local, session-owned, native, and cloud connections.
  • Documented token protection, project ownership checks, cross-project maintenance rules, rejection statuses, and validation behavior.
  • Clarified the distinction between authentication checks and ownership checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: Gentleman-Programming/engram/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 475d901b-63e4-4ca6-9657-23dede771b31

📥 Commits

Reviewing files that changed from the base of the PR and between ace0dd6 and cc3876b.

📒 Files selected for processing: 1

• DOCS.md

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

📝 Walkthrough

DOCS.md adds a “Local caller trust and ownership policy” section. It describes authentication boundaries, ownership assertions, cross-project maintenance rules, rejection outcomes, and requirements for future HTTP-authentication changes.

Changes: Local caller trust policy

Layer / File(s)	Summary
Document caller and ownership boundaries DOCS.md	The new section distinguishes standalone and session-owned HTTP authentication, native MCP profiles, and cloud authentication. It documents normalized expected_project ownership checks, cross-project maintenance, rejection outcomes, and compatibility requirements for broader HTTP-authentication changes.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Possibly related issues

• bug(hooks): with an external Engram server, Claude/Codex hooks register sessions under the server-side folder-name project, so explicit writes to the real project are denied (session_project_mismatch) #1911: The documentation states that cwd or process project is not caller authority; the reported runtime attribution behavior remains outside this PR.

Possibly related PRs

• Gentleman-Programming/engram#1986: Both changes relate to the observation PATCH and mem_update ownership contract.
• Gentleman-Programming/engram#1954: The PR implements host-process session binding for native MCP, a caller-attribution boundary documented here.

Suggested reviewers: gentleman-programming, alan-thegentleman

Merge Risk: ⚪ Minimal · up to cc387

This documentation-only change introduces no identified merge-blocking risk.

Pre-merge checks: 4

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: documenting the local caller trust and ownership policy.
Linked Issues check		Issue #1580 requires a documented local caller-authority policy. The DOCS.md change distinguishes standalone HTTP, session-owned HTTP, native MCP, and cloud boundaries. It separates authentication f…
Out of Scope Changes check		The whole-PR diff changes only DOCS.md and adds the policy section required by issue #1580. The documented representative outcomes and compatibility obligations support the policy objective. No unre…

Full details: Linked Issues check

Explanation

Issue #1580 requires a documented local caller-authority policy. The DOCS.md change distinguishes standalone HTTP, session-owned HTTP, native MCP, and cloud boundaries. It separates authentication from normalized expected_project ownership checks. It preserves deliberate cross-project maintenance and states that cwd and process project are not authority. It records selective standalone token behavior, compatibility obligations, and separately scoped broader authentication hardening. The diff contains no runtime changes.

Full details: Out of Scope Changes check

Explanation

The whole-PR diff changes only DOCS.md and adds the policy section required by issue #1580. The documented representative outcomes and compatibility obligations support the policy objective. No unrelated code, authentication change, mutation change, RBAC, or project-identity work is present.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

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

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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