docs: select epic-named projects and link authored tasks

archdev/SKILL.md

@@ -164,14 +164,13 @@ Three beats, one command
    `log post --kind` — `start` once scope is clear, `lesson` on a reusable
    root cause or fix, `abandoned` for a failed approach, `done` (with
    the PR URL) or an `@name` `handoff` at the end. Before the first
-   post, find the project the work belongs to
-   (`archdev projects list --query "<subject>"`) and pass its ID as
-   `--project <id>` on every `archdev log post` for that work. If no
-   active project covers it, create one
-   (`archdev projects create "<name>" --description "<scope>"`), named
-   for the product area or initiative, never for the PR, task, or
-   session. Look the project up again when a steer moves the session
-   to a different initiative. Re-read the stream before committing or
+   post, find the project for this work. For an epic, search active projects
+   for its exact name and matching scope; reuse that match or create it with
+   the epic name. Without an epic, select an active product-area or initiative
+   project covering the work, creating one only if none fits. Pass its ID as
+   `--project <id>` on every stream post. Never create a project per PR, task,
+   or session. Look it up again when the work changes scope. Re-read the stream
+   before committing or
    opening a PR. After `gh pr create` and after every push that moves
    a PR head, store that head's review annotations before doing
    anything else (see "PR review annotations" in monitor.md).
@@ -195,6 +194,17 @@ Three beats, one command
    --sha <head>` lists them under `assessments`); publish the missing
    ones (see "Focus range seals" in monitor.md).
 
+
+For work with an epic, search active projects for that exact epic name and
+confirm the scope. Reuse the matching project, or create one named for the epic
+when none fits. Resolve duplicate names by scope, never by result order. Set
+both `epic` and `project_id` on tasks (`tasks create/update --epic <name>
+--project <id>`); graph previews use top-level `epic` and `project_id` on each
+node. Use the same project ID on stream posts. Keep existing project IDs stable;
+do not rename a broad project based on one task. Without an epic, use the
+product area or initiative. These fields remain optional for older tasks and
+clients; agents authoring new work should set both.
+
 Every post carries human-readable text: structured posts add
 `--message "<one-line summary>"` as the headline over the CLI-rendered
 payload summary.
@@ -211,3 +221,11 @@ the risks you find within scope, then recompute, at most twice, before
 you post (monitor.md, Report and PR review annotations). No daemon, no
 log tailing: the model is the sensor until an event proves reliable
 enough to promote into the stop hook.
+
+
+During staggered releases, check `tasks create --help` for `--project`
+before authoring tasks with this guidance. If unavailable, upgrade the CLI;
+do not silently omit membership. Keep project names at most 80 characters
+until the deployed project schema and all participating CLI readers support
+200. Do not truncate an epic to create a misleading match; defer creating
+that project until those deployments are ready.

archdev/references/monitor.md

@@ -222,17 +222,20 @@ works on its own or on top of any `--event`.
 ### Tag every post with its project
 
 Before the first lifecycle post, find the project this work belongs to:
-`"$archdev" projects list --query "<subject>"`, then read the
-descriptions. Pick the project whose scope covers this work and pass its
-ID as `--project <id>` on every `archdev log post` for that work —
-notes, events, and `--kind` posts alike. The project belongs to the
-work, not the session: when a steer moves you to a different initiative
-(`agent.steered`), or a task turns out to sit elsewhere, look it up
-again before the next post. Create a project only when no
-active project fits (`"$archdev" projects create "<name>" --description
-"<which work belongs here>"`), and name it for the product area or
-initiative, not for the task or PR. Never create a project per PR, per
-task, or per session.
+`"$archdev" projects list --query "<epic or subject>"`, then read the
+descriptions. Pass its ID as `--project <id>` on every post, including
+notes, events, and `--kind` posts. When the work changes scope, look it up
+again before the next post.
+
+For work with an epic, search active projects for that exact epic name and
+confirm the scope. Reuse the matching project, or create one named for the epic
+when none fits. Resolve duplicate names by scope, never by result order. Set
+both `epic` and `project_id` on tasks (`tasks create/update --epic <name>
+--project <id>`); graph previews use top-level `epic` and `project_id` on each
+node. Use the same project ID on stream posts. Keep existing project IDs stable;
+do not rename a broad project based on one task. Without an epic, use the
+product area or initiative. These fields remain optional for older tasks and
+clients; agents authoring new work should set both.
 
 The tag lands in `metadata.project_id` beside the `pull_request` and
 `task_id` join keys, the key readers such as minimap file the post by.
@@ -732,3 +735,11 @@ the taxonomy proves itself.
   session posts; subagents never post.
 - Never post secrets, tokens, customer data, or unreviewed private
   content.
+
+
+During staggered releases, check `tasks create --help` for `--project`
+before authoring tasks with this guidance. If unavailable, upgrade the CLI;
+do not silently omit membership. Keep project names at most 80 characters
+until the deployed project schema and all participating CLI readers support
+200. Do not truncate an epic to create a misleading match; defer creating
+that project until those deployments are ready.

tasks/SKILL.md

@@ -10,6 +10,19 @@ browser handoff, feedback collection, revisions, and save verification; the
 human reviews the plan in the web UI. This works from any coding harness and
 does not require Factory, a daemon, a resident agent, or `archdev setup`.
 
+## Epic and project membership
+
+Before creating Tasks, search `archdev projects list --query "<epic>"` for an
+active project with the epic's exact name and the appropriate scope. Reuse it;
+if none fits, create it with `archdev projects create "<epic>" --description
+"<scope>"`. Resolve duplicate names by scope. Set both `--epic` and `--project`
+on task create/update. For graph import and review, set top-level `epic` and
+`project_id` on every node. Preserve the project ID across name changes.
+Without an epic, select the project by product area or initiative. Older tasks
+and artifacts may omit these optional fields; new agent-authored work should
+include both. Project membership does not change task visibility.
+
+
 ## 1. Connect this machine
 
 Resolve the absolute directory containing this loaded `SKILL.md`, independently
@@ -455,3 +468,11 @@ user's direction on decisions and scope.
 7. **Comment every status change** with why and what it unblocks. A
    status change with no comment is as opaque to the next person as the
    pause it resolved.
+
+
+During staggered releases, check `tasks create --help` for `--project`
+before authoring tasks with this guidance. If unavailable, upgrade the CLI;
+do not silently omit membership. Keep project names at most 80 characters
+until the deployed project schema and all participating CLI readers support
+200. Do not truncate an epic to create a misleading match; defer creating
+that project until those deployments are ready.