docs(agents): name a file to a human with an absolute path #1368

Merged

coilyco-ops merged 1 commit from aos/claude/tc69-abspath into main

2026-08-29 01:55:44 +00:00

coilyco-ops commented

2026-08-29 01:53:08 +00:00

Owner

New section after Command delivery, which already governs what an agent hands a person and already keys on the recipient rather than the framing.

Two carve-outs, because a flat rule breaks what is already in the tree:

A path inside a tracked file stays repo-relative, since the Markdown links in AGENTS.md resolve against whatever checkout reads it.
A surface carrying its own path rule wins, since SendFeedback asks for repo-relative or ~-prefixed paths so a home directory does not travel with the report.

Caps move 245 to 247 lines and 33600 to 34600 chars, justified in pyproject.toml as that block requires. The rule binds every session and every role, and no role source can hold it, because the failure is a property of where the agent runs rather than of what it was asked to do. It landed as one normalized paragraph, so the two-line raise is the heading and its blank line rather than prose.

This rule was written once before

#1362 was opened against a branch carrying only a merge of main, with no content commit under it. It reported zero changed files, failed its merge with a 500, was closed unmerged, and read as shipped for a day while the file never changed. Recorded in coilysiren/inbox#480.

Verified before opening this one: git diff origin/main...origin/aos/claude/tc69-abspath returns 2 files, 17 insertions.

A predecessor devrel seat handed Kai a draft at a scratchpad path from a session shadow she was never in, so it resolved for nobody but the agent that wrote it. A shadow, a linked worktree, and a container all reproduce that. New section after **Command delivery**, which already governs what an agent hands a person and already keys on the recipient rather than the framing. **Two carve-outs**, because a flat rule breaks what is already in the tree: - A path inside a tracked file stays repo-relative, since the Markdown links in `AGENTS.md` resolve against whatever checkout reads it. - A surface carrying its own path rule wins, since `SendFeedback` asks for repo-relative or `~`-prefixed paths so a home directory does not travel with the report. **Caps move 245 to 247 lines and 33600 to 34600 chars**, justified in `pyproject.toml` as that block requires. The rule binds every session and every role, and no role source can hold it, because the failure is a property of where the agent runs rather than of what it was asked to do. It landed as one normalized paragraph, so the two-line raise is the heading and its blank line rather than prose. ## This rule was written once before `#1362` was opened against a branch carrying only a merge of `main`, with no content commit under it. It reported zero changed files, failed its merge with a 500, was closed unmerged, and read as shipped for a day while the file never changed. Recorded in `coilysiren/inbox#480`. Verified before opening this one: `git diff origin/main...origin/aos/claude/tc69-abspath` returns 2 files, 17 insertions.

coilyco-ops added 1 commit

2026-08-29 01:53:08 +00:00

docs(agents): name a file to a human with an absolute path

ci / aos-cli-tests (pull_request) Successful in 28s

Details

ci / aos-eval-tests (pull_request) Successful in 31s

Details

ci / gate (pull_request) Successful in 49s

Details

0b52b964b9

A predecessor devrel seat handed Kai a draft at a scratchpad path from a
session shadow she was never in, so it resolved for nobody but the agent that
wrote it. A shadow, a linked worktree, and a container all reproduce that.

Two carve-outs, because a flat rule breaks what is already in the tree. A path
inside a tracked file stays repo-relative, since the Markdown links in
AGENTS.md resolve against whatever checkout reads it. A surface carrying its
own path rule wins, since SendFeedback asks for repo-relative or ~-prefixed
paths so a home directory does not travel with the report.

Placed after Command delivery, which already governs what an agent hands a
person and already keys on the recipient rather than the framing.

The caps move 245 to 247 lines and 33600 to 34600 chars, justified in
pyproject.toml as that block requires. The rule binds every session and every
role, and no role source can hold it, because the failure is a property of
where the agent runs rather than of what it was asked to do.

This rule was written once before. PR #1362 was opened against a branch
carrying only a merge of main, with no content commit under it, so it reported
zero changed files, failed its merge with a 500, and was closed unmerged while
reading as shipped. Recorded in coilysiren/inbox#480.

Refs coilysiren/inbox#480

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: advocate

coilyco-ops merged commit 329b223625 into main

2026-08-29 01:55:44 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-29 01:55:46 +00:00

docs(agents): name a file to a human with an absolute path (#1368)

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/agentic-os!1368

No description provided.

Rows
Columns