feat(rules): working-files convention for in-progress task artifacts

I added claude-rules/working-files.md as the canonical convention. In-progress task artifacts live in working/<task-slug>/ under the project root. On task completion the files get renamed individually with a YYYY-MM-DD-<slug>-<descriptor> shape and moved flat into assets/ (or the area-specific assets/). Never rename the directory as a substitute for filing, since that loses the flat-searchable property of assets/.

claude-templates/.ai/protocols.org gained a short reference to the rule so it propagates to every project's .ai/protocols.org on the next startup rsync.

2 files changed, 157 insertions, 0 deletions

diff --git a/claude-rules/working-files.md b/claude-rules/working-files.md
new file mode 100644
index 0000000..9a72702
--- /dev/null
+++ b/claude-rules/working-files.md
@@ -0,0 +1,145 @@
+# Working-Files Convention
+
+Applies to: `**/*` (every project)
+
+How in-progress task artifacts are organized in the project tree, and how
+they migrate to their permanent home when the task ships.
+
+## The Rule
+
+Every in-progress task that produces files (drafts, source documents,
+diagrams, scripts, sample data, transcripts, sub-deliverables) gets a
+dedicated subdirectory under the project's `working/` directory, named
+after the task. All artifacts for that task live in that subdirectory —
+the org source, every supporting file, every draft revision, every
+generated artifact — until the task is marked done.
+
+When the task is marked done, the files get **renamed individually** and
+**moved flat** into the appropriate permanent home (typically `assets/`,
+or an area-specific `assets/` like `deepsat/assets/`). The working
+subdirectory is then empty and gets deleted.
+
+**Never rename the directory itself as a substitute for filing.** Renaming
+the working subdir to its permanent name keeps every file together as a
+bundle, but loses the flat-filing property — future grep for an artifact
+hits a nested path instead of a single canonical name. Always rename the
+files individually with a shared prefix so they sort together but live as
+flat siblings in `assets/`.
+
+## Directory Layout
+
+    <project-root>/
+      working/
+        <task-slug>/
+          <artifact-1>
+          <artifact-2>
+          ...
+
+Examples:
+
+    work/working/tech-deck-vol2/
+      tech-deck-vol2.org
+      slide-04-platform-at-a-glance.mmd
+      slide-04-platform-at-a-glance.png
+      vol1-template.pptx
+
+    finances/working/2026-q2-tax-return/
+      schedule-c.org
+      receipts-import.csv
+      depreciation-worksheet.ods
+
+    work/working/SE-297-justin-onboarding/
+      justin-tasking-options.org
+      rate-research.org
+      advisory-agreement-draft.docx
+
+## Task-Slug Naming
+
+Keep the slug short, kebab-case, and recognizable on a 1-second scan.
+
+- Topic-led for narrative tasks: `tech-deck-vol2`, `branching-strategy-spec`, `tampa-trip`.
+- Ticket-led for ticket-driven tasks: `SE-297-justin-onboarding`, `DEE-722-vincent-vetting`.
+- Date-led for time-boxed work: `2026-q2-tax-return`, `2026-05-sofweek-prep`.
+
+Avoid: trailing dates on topic-led slugs (`tech-deck-vol2-2026-05-18`)
+when the task is open-ended; the slug names *the task*, not a snapshot.
+
+## Filing on Completion
+
+When the task is marked done:
+
+1. **Decide each file's permanent home.** Usually one of:
+   - `<area>/assets/` (e.g. `deepsat/assets/`) — for area-scoped reference
+     material (transcripts, PDFs, diagrams that document the area's state).
+   - Project-root `assets/` — for project-scoped material.
+   - `<area>/<topic>/` — for material that joins an existing topic
+     subdirectory (rare; only when the topic dir already exists).
+
+2. **Rename each file** so it carries the task context and is sortable
+   alongside its siblings. Standard form:
+   `<YYYY-MM-DD>-<task-slug>-<descriptor>.<ext>`
+
+   Examples:
+   - `tech-deck-vol2.org` → `2026-05-18-tech-deck-vol2-source.org`
+   - `slide-04-platform-at-a-glance.png` → `2026-05-18-tech-deck-vol2-slide-04-diagram.png`
+   - `vol1-template.pptx` → `2026-05-08-tech-deck-vol1-template.pptx`
+     (use the date the artifact originated, not the date the task closed,
+     when it's clearly meaningful — Vol 1 template predates Vol 2 work)
+
+3. **Move flat into the permanent home.** No nested subdirectory in
+   `assets/`. The files sort together by date + task-slug prefix.
+
+4. **Delete the now-empty `working/<task-slug>/` subdirectory.**
+
+5. **Update any inbound links.** Tasks in `todo.org`, references in
+   `notes.org`, cross-links from other documents — all need their `file:`
+   paths updated to the new flat-filed locations. Use grep to find every
+   occurrence before deleting the working dir.
+
+## Why This Shape
+
+- *Discovery during work* — every artifact for the current task is in
+  one place. No hunting across `assets/`, `drafts/`, scratch dirs.
+- *Discovery after completion* — `assets/` stays a flat searchable
+  store. Every artifact is reachable by a single `find assets/ -name '*<slug>*'`.
+- *Atomic completion* — the act of filing forces a review of every
+  artifact's permanent value. Files that aren't worth keeping get
+  deleted in the move; the rename forces a meaningful name.
+- *No orphan subdirs in `assets/`* — renaming the directory instead of
+  files would bury artifacts inside a nested path that no flat search
+  reaches. Three years from now `assets/old-tech-deck-2026/slide.png`
+  is harder to find than `assets/2026-05-18-tech-deck-vol2-slide-04-diagram.png`.
+
+## When the Rule Doesn't Apply
+
+- *Single-file scratch work that lives one day* — a `/tmp/foo.txt` for
+  a draft is fine. The convention is for tasks producing multiple
+  artifacts or artifacts worth keeping.
+- *Source-controlled subprojects* — code under `<project>/code/<repo>/`
+  follows the subproject's own conventions, not this rule.
+- *Inbox content* — `inbox/` and `daily-prep/` follow their own
+  conventions (dated filenames, processed and moved on cadence).
+
+## Implementation Note for Claude Sessions
+
+When the user starts a new task that's going to produce file artifacts:
+
+1. Propose the working-dir path before creating any files
+   (`working/<task-slug>/`).
+2. Create the directory and put the first artifact there.
+3. Add or update the inbound link in `todo.org` to point at the new
+   path.
+4. Note the working-dir in the task's body so future sessions find it.
+
+When the user marks the task done:
+
+1. List every file in the working subdir.
+2. Propose renames + permanent homes for each.
+3. Move flat after confirmation.
+4. Delete the empty working subdir.
+5. Update inbound links.
+
+The directory layout is the same shape across every project — see
+per-project `CLAUDE.md` or `notes.org` for project-specific
+permanent-home conventions (e.g. `deepsat/assets/` vs project-root
+`assets/`).
diff --git a/claude-templates/.ai/protocols.org b/claude-templates/.ai/protocols.org
index 30b0274..57ebf87 100644
--- a/claude-templates/.ai/protocols.org
+++ b/claude-templates/.ai/protocols.org
@@ -158,6 +158,18 @@ Each project's =.ai/= is the scope boundary: =protocols.org=, =session-context.o
 
 Canonical rule: =~/code/rulesets/claude-rules/cross-project.md=.
 
+** Working-Files Convention — =working/<task-slug>/= for In-Progress Artifacts
+
+Every in-progress task that produces files (drafts, source documents, diagrams, scripts, sub-deliverables) gets a dedicated subdirectory under =<project-root>/working/=, named after the task. All artifacts for that task live in that subdirectory until the task is marked done.
+
+When the task ships, files are **renamed individually** (standard form: =YYYY-MM-DD-<task-slug>-<descriptor>.<ext>=) and **moved flat** into the appropriate permanent home (typically =assets/= or an area-specific =<area>/assets/=). The working subdirectory is then empty and gets deleted.
+
+***Never rename the directory itself as a substitute for filing.*** The point is to keep =assets/= flat-searchable — a nested =assets/old-tech-deck-2026/slide.png= is harder to find than =assets/2026-05-18-tech-deck-vol2-slide-04-diagram.png=.
+
+When the user starts a new task that will produce file artifacts, propose the =working/<task-slug>/= path before creating any files. Add or update the inbound link in =todo.org= to point at the working dir. When the user marks the task done, list every file, propose renames + permanent homes, move flat after confirmation, delete the empty subdir, update inbound links.
+
+Canonical rule: =~/code/rulesets/claude-rules/working-files.md=.
+
 * Important Terminology
 
 ** "Let's run the [X] workflow" vs "I want to create an [X] workflow"