aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-05-28 08:18:10 -0500
committerCraig Jennings <c@cjennings.net>2026-05-28 08:18:10 -0500
commitdb7f82711978da5e7f152297942854c7b753f480 (patch)
tree68ea4ce52cbb278114acf0243fe7397d2f1d6efc
parentee7049aaa62d0c38e83f20c0b3796e5eded4ca23 (diff)
downloadrulesets-db7f82711978da5e7f152297942854c7b753f480.tar.gz
rulesets-db7f82711978da5e7f152297942854c7b753f480.zip
chore(audit): task-audit pass + pearl intake from 2026-05-28 morning
All 16 open tasks bucketed and updated. 14 received autonomous Phase C edits (13 type-tag additions per the new scheme plus #15's body refresh for the accumulating pearl signal). Phase D adjudicated two priority bumps and the morning's inbox spillover. Phase E stamped :LAST_AUDIT: in notes.org Workflow State. Autonomous Phase C: - Tagged tasks 1-11 and 13-14 with their type tag (:feature:, :chore:, :spec:), bumped LAST_REVIEWED to 2026-05-28. Tasks 12, 15, 16 already carried type tags. - Refreshed task #15 body to reference the four pearl pattern-catalog notes now in docs/design/ (six worked patterns total). Phase D adjudication: - #15 (cross-project pattern catalog) bumped [#C] to [#B]. Pearl shipped 6 worked examples plus a synthesizing principle and is asking for spec-review iterations. Design questions still open but evidence is past the tipping point. - Filed new [#B] :feature: TODO for the codex Phase 1 race-fix (AI_AGENT_ID + session-context.d/<id>.org), lifted from the broader runtime spec (#16). Phase 1 alone is low-risk and fixes a real correctness issue under simultaneous agents. Pearl intake (4 inbox files from this morning): - Moved 0155 (patterns 4-5) and 0303 (pattern 6) into docs/design/ alongside the prior two pattern-catalog notes. Referenced from #15. - Filed new [#C] :chore:quick:solo: TODO for pearl 0138's --archive-done sweep at the start of open-tasks.org Phase A. - Filed new [#C] :feature:solo: TODO for pearl 0226's spec-review.org Phase 6 implementation-task enumeration. - Deleted 0124. Already implemented this session as the audit-warranted pre-step plus the LAST_AUDIT stamp now live in the workflow files.
-rw-r--r--.ai/notes.org2
-rw-r--r--docs/design/2026-05-28-pattern-catalog-prompt-collapse.org (renamed from inbox/2026-05-28-0303-from-pearl-rulesets-followup-collapse-prompts.org)0
-rw-r--r--docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org (renamed from inbox/2026-05-28-0155-from-pearl-rulesets-followup-prompts-ux.org)0
-rw-r--r--inbox/2026-05-28-0124-from-.emacs.d-suggestion-whats-next-auto-considers-task-audit.org86
-rw-r--r--inbox/2026-05-28-0138-from-pearl-rulesets-open-tasks-archive-done.org29
-rw-r--r--inbox/2026-05-28-0226-from-pearl-rulesets-spec-review-implementation.org53
-rw-r--r--inbox/2026-05-28-0814-from-pearl-no-approvals.org98
-rw-r--r--todo.org105
8 files changed, 175 insertions, 198 deletions
diff --git a/.ai/notes.org b/.ai/notes.org
index 3228009..1389e02 100644
--- a/.ai/notes.org
+++ b/.ai/notes.org
@@ -78,6 +78,6 @@ Format:
Markers maintained by workflows to record when they last ran. Read by other workflows that gate their behavior on freshness.
-:LAST_AUDIT: (unset — first =task-audit= run will populate)
+:LAST_AUDIT: 2026-05-28
Format: one =:MARKER: YYYY-MM-DD= line per workflow. Workflows overwrite their own marker on completion.
diff --git a/inbox/2026-05-28-0303-from-pearl-rulesets-followup-collapse-prompts.org b/docs/design/2026-05-28-pattern-catalog-prompt-collapse.org
index bef4516..bef4516 100644
--- a/inbox/2026-05-28-0303-from-pearl-rulesets-followup-collapse-prompts.org
+++ b/docs/design/2026-05-28-pattern-catalog-prompt-collapse.org
diff --git a/inbox/2026-05-28-0155-from-pearl-rulesets-followup-prompts-ux.org b/docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org
index cc2cb77..cc2cb77 100644
--- a/inbox/2026-05-28-0155-from-pearl-rulesets-followup-prompts-ux.org
+++ b/docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org
diff --git a/inbox/2026-05-28-0124-from-.emacs.d-suggestion-whats-next-auto-considers-task-audit.org b/inbox/2026-05-28-0124-from-.emacs.d-suggestion-whats-next-auto-considers-task-audit.org
deleted file mode 100644
index 4e3e6fd..0000000
--- a/inbox/2026-05-28-0124-from-.emacs.d-suggestion-whats-next-auto-considers-task-audit.org
+++ /dev/null
@@ -1,86 +0,0 @@
-#+TITLE: Suggestion — what's-next should auto-consider task-audit and run when warranted
-#+FROM: dotemacs (~/.emacs.d)
-#+DATE: 2026-05-28
-
-* Suggestion
-
-Extend =claude-templates/.ai/workflows/open-tasks.org= Next Mode with a pre-step: before producing the cascade + friction output, evaluate whether a =task-audit= is warranted and offer to run it first. The user shouldn't have to remember to schedule audits — they get triggered by the workflow when needed.
-
-* Why
-
-Task-audit is the "is each task factually accurate?" workflow. Its value compounds with drift: as sessions land changes, as deadlines pass, as referenced files move, the open-task body content drifts out of sync with reality. Today the user has to remember to invoke =task-audit= explicitly. In practice that means audits happen rarely and the open-task set accumulates stale claims.
-
-The =task-review= workflow already runs daily as a habit. The =task-audit= workflow runs roughly never. Coupling audit to "what's next" closes that gap — every time the user asks the system to recommend work, the system checks whether the recommendation is being made over stale facts and offers to clean up first.
-
-* The criteria for "warranted"
-
-Hybrid: temporal threshold OR state-signal detection. Either trips it.
-
-** Temporal threshold
-
-Track =:LAST_AUDIT:= in =notes.org= under a new "Workflow State" section (or, alternately, as a single-line marker like =# LAST_AUDIT: YYYY-MM-DD= at the bottom of =notes.org=). If absent, treat as "never run." If older than 14 days, the threshold trips.
-
-The threshold value (14 days) is a starting point — projects with high churn could tune it down, low-churn projects up. Lives as a per-project knob in =notes.org=.
-
-** State-signal scan
-
-During Phase A's existing snapshot, check these cheap signals:
-
-1. *Reminder-vs-task mismatch.* Active Reminder names a task or completion target that doesn't appear in =todo.org= (or vice versa: =todo.org= names a reminder that isn't in =notes.org='s Active Reminders).
-2. *Passed scheduled date.* A task with a =SCHEDULED:= or =DEADLINE:= date earlier than today, still =TODO= or =DOING=, no completion log.
-3. *"Waiting on X" matches a completed X.* Task body contains a phrase like "waiting on", "after X ships", "blocked by"; the recent session summaries (already in the snapshot) log the named X as shipped.
-4. *Reference to deleted artifact.* A task body's =file:= link points to a path that doesn't exist (use a single existence check per linked path).
-5. *Sub-task DONE coverage.* A task with many sub-tasks where >75% are DONE/CANCELLED but the parent is still =TODO= or =DOING= — a likely promotion candidate.
-
-Any one signal trips the audit-warranted flag. Signals 1–3 are cheap. Signal 4 needs filesystem access (still cheap per-task). Signal 5 is a counting pass.
-
-** Combined
-
-Audit warranted if (temporal threshold tripped) OR (any state signal tripped).
-
-* Proposed Phase A addition
-
-Add to the Phase A parallel batch (after the existing 4 reads):
-
-5. Read the =:LAST_AUDIT:= marker from =notes.org= (or note its absence).
-
-* Proposed new section: Phase A.1 — Audit warranted?
-
-Between Phase A and Phase B, evaluate the warranted check from the snapshot. If tripped, surface to the user with numbered options:
-
-#+begin_example
-Task-audit looks worth running before this recommendation:
-- Temporal: <N> days since last audit (threshold 14)
-- Signal: <specific finding, e.g. "L46 reminder names 'fix X' but no task matches">
-
-1. Run task-audit first — fixes the facts, then I'll come back to next-task
-2. Skip the audit — proceed straight to what's next
-3. Run audit but only the autonomous half (factual updates) — defer the judgment calls to a later session
-#+end_example
-
-If not tripped, proceed silently to Phase B.
-
-* Refreshing :LAST_AUDIT:
-
-When =task-audit= runs from anywhere, its Phase C should stamp =:LAST_AUDIT:= to today's date in =notes.org=. The trigger has to live in =task-audit.org= so it works for the manual invocation too, not just the chained-from-whats-next path. That's a one-line addition to that workflow's Phase D close-out.
-
-* Implementation order
-
-Two coupled changes that should land together:
-
-1. =task-audit.org= Phase D — stamp =:LAST_AUDIT:= on completion (date format =YYYY-MM-DD= for trivial parsing).
-2. =open-tasks.org= — add the Phase A read, the new Phase A.1 evaluate-warranted block, and a "Common Mistakes" entry "Running the cascade over stale facts — always evaluate audit-warranted first; let the user override."
-
-If only one of the two lands, the feature is broken — the stamp wouldn't get set without the audit edit; the audit-warranted check would fail without the read. Land them as a pair.
-
-* Open questions
-
-- Storage location for =:LAST_AUDIT:= — a top-of-notes.org property line, a dedicated "Workflow State" subsection in notes.org, or a sibling =.ai/workflow-state.org= file. (The sibling file is cleanest if more workflow-state markers accumulate; notes.org is fine for one or two.)
-- Threshold value — 14 days is a defensible default but should be a per-project knob. Naming the knob: a top-of-notes.org line =# AUDIT_THRESHOLD_DAYS: 14= alongside the marker?
-- Should the audit run automatically (no prompt) when both signals AND threshold trip? The recommendation-first convention argues for prompting with item 1 = "yes run it" rather than silent auto-run, since "what's next" is interactive anyway.
-
-* Source
-
-Drafted from the dotemacs session 2026-05-28. The user's framing: "I won't really ever have to think about the task-audit workflow." This suggestion answers that — by hooking it to the workflow the user already invokes.
-
-References the prior two rulesets suggestions (=2026-05-28-0014-from-.emacs.d-...= for recommendation-first option ordering, and =2026-05-28-0117-from-.emacs.d-...= for the open-tasks.org hybrid output shape). The auto-audit pre-step is the third leg of the same triple — together they make "what's next" the single point of entry for task-level work.
diff --git a/inbox/2026-05-28-0138-from-pearl-rulesets-open-tasks-archive-done.org b/inbox/2026-05-28-0138-from-pearl-rulesets-open-tasks-archive-done.org
deleted file mode 100644
index fd6687b..0000000
--- a/inbox/2026-05-28-0138-from-pearl-rulesets-open-tasks-archive-done.org
+++ /dev/null
@@ -1,29 +0,0 @@
-#+TITLE: open-tasks workflow should run --archive-done before reading
-#+DATE: [2026-05-28 Thu]
-#+SOURCE: pearl session 2026-05-28
-
-* The gap
-
-=workflows/open-tasks.org= (the "what's next" / "list open tasks" workflow that merged in the older =whats-next.org=) reads =todo.org='s =* Project Open Work= section in Phase A and skips =* Project Resolved=. That's correct in principle, but in practice a level-2 task that completed during the session sits as =** DONE= under =Open Work= until something archives it. The cleanup tool's =--archive-done= sweep is what moves it to =Resolved=, and only =workflows/clean-todo.org= and the wrap-up workflow currently run it.
-
-The consequence: between cleanups, =open-tasks.org= can surface a freshly-DONE task as a "what's next" candidate. The reconcile phase doesn't filter on TODO state. In a session where Craig shipped a few things and immediately asks "what's next," he gets recommendations that include work he just finished.
-
-* Proposed fix
-
-Add an =--archive-done= sweep as the first step of =open-tasks.org='s Phase A, before the parallel reads. One line:
-
-#+begin_src bash
-emacs --batch -q -l .ai/scripts/todo-cleanup.el --archive-done todo.org
-#+end_src
-
-Then Phase A's read of =todo.org= sees a clean Open Work section and the reconciliation works against current state.
-
-The cost is a few hundred milliseconds at the start of every "what's next" invocation. The win is recommendations that never include DONE work.
-
-* Optional refinement
-
-If the workflow ever runs in a context where Craig actively does *not* want write side effects (a read-only dry run, a presentation mode), gate the sweep behind a check. The default invocation should still archive — the dry-run case is the exception.
-
-* Triggered by
-
-2026-05-28 pearl session, after marking several VERIFY tests DONE inline during a verify walk-through. Craig flagged that the next "what's next" would see those still in Open Work until the next cleanup.
diff --git a/inbox/2026-05-28-0226-from-pearl-rulesets-spec-review-implementation.org b/inbox/2026-05-28-0226-from-pearl-rulesets-spec-review-implementation.org
deleted file mode 100644
index 5af3502..0000000
--- a/inbox/2026-05-28-0226-from-pearl-rulesets-spec-review-implementation.org
+++ /dev/null
@@ -1,53 +0,0 @@
-#+TITLE: spec-review.org should enumerate implementation tasks for todo.org
-#+DATE: [2026-05-28 Thu]
-#+SOURCE: pearl session 2026-05-28
-
-* The gap
-
-=workflows/spec-review.org= Phase 6 says "log deferred work to =todo.org=: v1 implementation = [#B] ... vNext/someday = [#D]." That covers *deferred* items (vNext) and a passing mention of v1 implementation, but it doesn't ask the workflow to enumerate, in the review output, the *concrete tasks* that fully implementing and testing the spec would require. The result: a spec gets marked =Ready=, the reviewer hands off, and the next session has to re-derive the task breakdown from the spec text rather than reading a ready-made list.
-
-For specs that decompose cleanly into commits (which is most of them now that the =Implementation phases= convention from =issue-sources-spec.org= has spread), the breakdown is *already in the spec*. The workflow just needs to lift it into the review output in a form that drops straight into =todo.org=.
-
-* Proposed addition to Phase 6
-
-After the existing "log deferred work to todo.org" sentence, add a structured step:
-
-#+begin_src org
-,*** Step: Enumerate the implementation tasks
-
-Read the spec's =Implementation phases= section (or equivalent commit/phase breakdown). For each phase, produce a =[#B] TODO= entry as it would appear in =todo.org=, including:
-
-- Subject line (descriptive topic, kebab-case slug, conventional-commit style).
-- Tags (=:feature:= / =:bug:= / =:refactor:= / =:test:= and any of =:quick:= / =:solo:= / =:discuss:= that apply).
-- One-line body: what lands in this phase.
-- Pointer back to the spec.
-
-Add a final =[#B] TODO= entry for the test surface that lands alongside the commits (unit tests, integration tests, manual-verify checklist). If the spec's =Acceptance criteria= section enumerates verifiable behaviors, mirror them as the manual-verify entries.
-
-Append the enumerated entries to the review file under a new heading:
-
-,* Implementation tasks (drop-in for todo.org)
-The full list of todo.org entries that fully implementing and testing this spec would require. Copy-paste into =todo.org='s =* $Project Open Work= header. Each entry is independently shippable per the spec's commit decomposition.
-
-If the spec doesn't have an =Implementation phases= section, this step is the prompt to ask the author to add one before assigning =Ready=. A spec without a phase breakdown is hard to plan against and harder to review the implementation of.
-#+end_src
-
-The step lives inside Phase 6 because it's part of "update tracking," but the output is sized to drop straight into =todo.org= — Craig (or the next agent) copy-pastes rather than re-deriving. The format mirrors =todo-format.md= (terse heading + body, tags on the heading line, no sentence-shaped headings).
-
-* Why this matters
-
-Three concrete wins:
-
-1. *Hand-off is one paste, not a re-read.* The reviewer already understands the spec well enough to assign a rubric. They're the right person to enumerate the work. Doing it in the review file means the spec-response author (or implementer) doesn't re-derive the breakdown from the spec narrative.
-
-2. *Forces a spec to be implementable in pieces.* If the reviewer can't write the implementation-tasks list, the spec doesn't have a clean phase decomposition. That's a spec-shape problem worth surfacing before =Ready=. The step is its own implementation-readiness check.
-
-3. *Closes the loop on =Acceptance criteria=.* Specs often have a numbered acceptance list and a separate commit decomposition. Mirroring the acceptance numbers as manual-verify task entries ensures every claim gets a check — the verify list isn't an afterthought.
-
-* Merge-with-pending note
-
-I noticed three uncommitted edits in =claude-templates/.ai/workflows/= (open-tasks, spec-response, spec-review) when I rsynced templates earlier today. If there's already a pending recommendation thread for =spec-review.org=, merge this addition with it rather than treating them as separate proposals. The change is additive (new step inside an existing phase, new review-file section), so it should compose with most other changes cleanly.
-
-* Triggered by
-
-2026-05-28 pearl session, while writing =docs/saved-query-sync-spec.org= and entering its sprint-review cycle. Craig: "update the spec review workflow such that it also lists all the actual tasks it would enter in todo.org to fully implement and test the functionality of the spec." Worked example landed at the bottom of =docs/saved-query-sync-spec.org= showing what the section looks like in practice.
diff --git a/inbox/2026-05-28-0814-from-pearl-no-approvals.org b/inbox/2026-05-28-0814-from-pearl-no-approvals.org
new file mode 100644
index 0000000..e61b69d
--- /dev/null
+++ b/inbox/2026-05-28-0814-from-pearl-no-approvals.org
@@ -0,0 +1,98 @@
+#+TITLE: No-Approvals Mode
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-05-28
+
+* Heads-up from pearl (2026-05-28)
+
+Craig flagged that he plans to use a "no-approvals" mode and the rulesets project is already building one. He drafted this in pearl as a project-workflow (=.ai/project-workflows/no-approvals.org=) and asked that a copy come here so rulesets can compare with whatever is in flight there and take the best from both.
+
+Source path in pearl: =/home/cjennings/code/pearl/.ai/project-workflows/no-approvals.org=.
+
+Key points Craig dictated, in his own framing:
+- Explicit way to signal there are no approval gates until he turns them back on.
+- Don't stop at any approval gate. Finish each task fully, then start the next. Continue until a question arises or the next work item is unknown.
+- Triggers he'll use: queuing several tasks in =todo.org= then "do all =:quick:solo:= with no-approval", or just "no-approval" / "no approvals" / "no need for approval gates" in a command.
+- Engineering discipline still applies. He named specifically: =/code-review= before every commit and =/voice personal= on every commit message (he flagged this as by far the most common). The rest of CLAUDE.md / commits.md / testing.md / verification.md still binds.
+
+Action: review against rulesets' draft, merge the better framing of each section, decide where the canonical version lives (rulesets' workflow vs claude-rules vs both).
+
+* Overview
+
+A mode Craig switches on to drop the approval gates between work items, so a pre-agreed batch of tasks runs straight through without "OK to proceed?" interruptions. Stays on until Craig turns it off, until a genuine question arises, or until the queue runs out.
+
+The point is throughput on work where the approval has already been earned upfront — a queue of tagged tasks Craig has already triaged, a "do all the =:quick:solo:= ones" sweep, a multi-step refactor with no design calls left. Approval gates are valuable when judgment is uncertain. They are friction when the decision is already made.
+
+This is *not* a license to skip the engineering discipline that keeps work shippable. Code review, voice pass, testing, and verification all stay on. The gates this turns off are the *interaction* gates — "I drafted a commit message, approve?" / "Plan looks like X, OK to start?" / "Ready to push?"
+
+* When to Use This Workflow
+
+Craig activates it with any of:
+- "no-approval" / "no approvals"
+- "no need for approval gates"
+- "do all <selector> with no-approval" (e.g. "do all =:quick:solo:= tasks with no-approval")
+- Queuing several tasks in =todo.org= followed by any phrase above
+- Any equivalent phrasing that signals he does not want to be re-asked between items
+
+Deactivates when:
+- Craig says it is back on (any explicit "approvals back on" signal)
+- A new top-level user message arrives that does not reaffirm no-approvals — assume the mode resets when Craig switches topics
+- A genuine question or unknown next step is hit — return control to Craig and exit the batch
+
+* What's Suspended
+
+Approval gates that step the workflow back to Craig for an "OK to proceed?" check:
+
+- The commit-message gate in =commits.md= Step 2 (draft inline, get approval, commit). Print the final commit message inline, then commit immediately. No "approve / request changes / open in editor" prompt.
+- The PR-description gate in the same flow. Print the final body, then create the PR.
+- The PR-review-reply gate. Print the final reply, then post.
+- "Ready to start?" / "Plan looks like X, proceed?" gates before implementation work begins.
+- "Move on to the next task?" gates between items in a queued batch.
+- Per-task summary prompts at the end of each item. Give one short result line and proceed to the next.
+
+* What Stays On
+
+Engineering discipline gates that protect quality, not Craig's interaction time:
+
+- =/code-review= against the staged diff before every commit. Critical and Important findings still block. Minor findings still surface. No "proceed anyway" override unless Craig has given it explicitly for this batch.
+- =/voice personal= against every publish artifact (commit messages, PR titles + bodies, PR review comments). The 41-pattern walk happens. The printed result just does not wait for approval.
+- The full test suite + lint + compile before commit (=verification.md=).
+- Fetch-and-reconcile in =commits.md= Step 0.
+- Any destructive or irreversible operation per =CLAUDE.md= "Executing actions with care". Those need explicit consent regardless of the mode — force push, =rm -rf=, dropping a column. No-approvals is for *interaction* gates, not destructive-action consent.
+- Anything specifically requiring Craig's design call, preference, or sign-off. Stop and ask. The batch ends here.
+- Subagent review-gate cadence (=subagents.md=). Review each subagent's output before the next dispatch.
+
+* When to Break Out of the Batch
+
+Even with no-approvals on, return control to Craig immediately if:
+
+- A genuine ambiguity surfaces (multiple ways to do the next step, no clear default).
+- A finding suggests the user's stated goal is wrong (e.g. the "fix" reveals the bug is elsewhere).
+- =/code-review= surfaces a Critical or Important finding the batch cannot resolve safely.
+- Tests fail in a way that needs Craig's judgment.
+- The queued work is done and no obvious next item exists.
+- Any guideline above says "stop and ask" — that wins over no-approvals.
+
+When breaking out, say so explicitly: "Pausing no-approvals batch — <reason>. Decision needed: <question>."
+
+* Activation Pattern
+
+When Craig invokes no-approvals (with one of the phrases above):
+
+1. Acknowledge the mode is on and name the scope ("no-approvals for the =:quick:solo:= tasks; stays on until done or until I hit a question").
+2. Identify the queue — the tasks named explicitly, or the org-tag selector, or "the next N tasks in todo.org".
+3. Walk them in order. For each: do the work, run =/code-review= + =/voice personal= + tests as required, commit, move to the next.
+4. Brief one-line status between items ("Task X done, on to Y").
+5. At the end of the queue: summarize what shipped, confirm batch is complete, return control.
+
+* Common Mistakes
+
+1. *Bypassing =/code-review= or =/voice personal=* — these are not approval gates, they are quality gates. They stay on.
+2. *Plowing through a Critical finding* — Critical and Important findings still block. The batch pauses, the issue gets fixed, the batch resumes.
+3. *Skipping destructive-action consent* — force push, =rm -rf=, dropping production data still need explicit consent per =CLAUDE.md= "Executing actions with care". No-approvals does not cover these.
+4. *Continuing past genuine ambiguity* — if there are two reasonable ways forward, stop and ask. The batch's purpose is to skip *redundant* approvals, not to invent decisions Craig did not pre-agree to.
+5. *Forgetting to surface progress* — Craig still wants the one-line status between items so he knows what is happening.
+6. *Carrying no-approvals across sessions or unrelated user messages* — assume it resets when the work it was scoped for finishes, or when Craig moves to a different topic.
+
+* Living Document
+
+If a recurring pattern emerges (e.g. Craig wants the one-line status to include the commit SHA, or wants per-task tests skipped because the suite runs once at the end), fold it in. The mode is shaped by use — refine as the dogfooding signal arrives.
diff --git a/todo.org b/todo.org
index 12bdd25..2595ec6 100644
--- a/todo.org
+++ b/todo.org
@@ -1,4 +1,4 @@
-#+TITLE: Rulesets — Open Work
+#+TITLE: Rulesets — Work
#+AUTHOR: Craig Jennings
#+DATE: 2026-04-19
@@ -34,9 +34,9 @@ Tags are assigned and refreshed by =task-audit=; =task-review= keeps them honest
* Rulesets Open Work
-** TODO [#C] Check that memories are sync'd across machines via git
+** TODO [#C] Check that memories are sync'd across machines via git :spec:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
*** 2026-05-16 Sat @ 01:12:52 -0500 Spec
#+begin_src cj: comment
@@ -74,9 +74,9 @@ Created bare =git@cjennings.net:claude-memory.git=, cloned to =~/.claude-memory=
*** 2026-05-24 Sun @ 01:53:35 -0500 Reversed the migration — back to unmanaged per-project memory
Cancelled the follow-up brainstorm and undid the dedicated-repo migration at Craig's call. Moved all 7 memory dirs back to =~/.claude/projects/<enc>/memory/= (content preserved), deleted the =~/.claude-memory= clone, and deleted the bare =claude-memory.git= on the server. Memory is back to its original at-risk state, so the task reopens at [#C] pending a direction. The brainstorm landed on a two-tier idea for whenever this resumes: promote general lessons into a rulesets-tracked file symlinked into =~/.claude/rules/= (loaded into every project natively, one repo), and keep project-specific memory under each project's own =.ai/memory/= (committed where =.ai/= is tracked, at-risk where it's gitignored). Not implemented.
-** TODO [#C] Build =create-documentation= skill for high-quality project/product docs
+** TODO [#C] Build =create-documentation= skill for high-quality project/product docs :feature:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Create a Claude skill named =create-documentation= that can plan, write,
@@ -711,9 +711,9 @@ The skill should reject:
public/library/API docs: =llms.txt= or markdown export is valuable, but normal
human navigation remains primary.
-** TODO [#C] Build =/update-skills= skill for keeping forks in sync with upstream
+** TODO [#C] Build =/update-skills= skill for keeping forks in sync with upstream :feature:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
The rulesets repo has a growing set of forks (=arch-decide= from
@@ -797,9 +797,9 @@ write the specification here.
- [ ] Rate-limit / offline mode: if GitHub is unreachable, should skill fail
or degrade gracefully? Likely degrade; print warning per fork.
-** TODO [#C] Build /research-writer — clean-room synthesis for research-backed long-form
+** TODO [#C] Build /research-writer — clean-room synthesis for research-backed long-form :feature:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Gap in current rulesets: between =brainstorm= (idea refinement → design doc)
@@ -854,9 +854,9 @@ Triggers that would prompt "let's build it now":
Upstream reference (do not vendor): ComposioHQ/awesome-claude-skills
=content-research-writer/SKILL.md=.
-** TODO [#C] Try Skill Seekers on a real DeepSat docs-briefing need
+** TODO [#C] Try Skill Seekers on a real DeepSat docs-briefing need :chore:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
=Skill Seekers= ([[https://github.com/yusufkaraaslan/Skill_Seekers]]) is a Python
@@ -901,9 +901,9 @@ discard and stick with hand briefing.
- Companion =skill-seekers-configs= community repo has only 8 stars
despite main's 12.9k — ecosystem thinner than headline adoption
-** TODO [#C] Revisit =c4-*= rename if a second notation skill ships
+** TODO [#C] Revisit =c4-*= rename if a second notation skill ships :chore:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Current naming keeps =c4-analyze= and =c4-diagram= as-is (framework prefix
@@ -1047,9 +1047,9 @@ having a skill to generate or check OV-1-shaped artifacts. Don't build
speculatively — defense-specific notations are narrow enough that each
skill should be driven by a concrete contract need, not aspiration.
-** TODO [#C] Add =make uninstall-mcp= + =mcp/install.py --check= for symmetry :solo:quick:
+** TODO [#C] Add =make uninstall-mcp= + =mcp/install.py --check= for symmetry :feature:solo:quick:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Currently the MCP install pipeline only flows one direction. No way to remove rulesets-managed MCP servers in one command. No way to ask "what's the drift between =servers.json= and =claude mcp list=" without eyeballing.
@@ -1068,16 +1068,16 @@ Dry-run mode. Decrypt secrets, but instead of registering, print the drift repor
Useful for diagnosing connection failures and for the eventual =make doctor= integration.
-** TODO [#C] Update =README.org= with MCP install pipeline section :solo:quick:
+** TODO [#C] Update =README.org= with MCP install pipeline section :chore:solo:quick:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
=README.org= covers global install, per-project language bundles, and design principles, but doesn't mention =make install-mcp= or the =mcp/= directory. Add a short section after "Per-project language bundles" describing the user-scope MCP install pattern (decrypt → expand → register) and pointing at the eventual =mcp/README.org=.
-** TODO [#C] Token-rotation helper for =@a-bonus/google-docs-mcp= OAuth refresh
+** TODO [#C] Token-rotation helper for =@a-bonus/google-docs-mcp= OAuth refresh :feature:quick:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
When a Google refresh token gets revoked (re-grant scopes, removed Connected App, account password reset), recovery is currently manual: run =npx -y @a-bonus/google-docs-mcp= with the right env, follow the URL in a browser, kill the process, base64-encode the new =token.json=, decrypt =secrets.env.gpg=, replace the var, re-encrypt. A small =mcp/refresh-google-docs-token.sh <profile>= would chain that into one command.
@@ -1100,9 +1100,9 @@ rm /tmp/secrets.env.tmp
The flow tonight worked but took a handful of manual steps. One script collapses it.
-** TODO [#C] Decide on category-3 rule copies in the deepsat tree
+** TODO [#C] Decide on category-3 rule copies in the deepsat tree :chore:quick:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
While symlinking personal-project =.claude/rules/= mirrors to the rulesets canonical on 2026-05-07, two locations didn't fit the "personal mirror → symlink" pattern and were left untouched pending judgment:
@@ -1112,9 +1112,9 @@ While symlinking personal-project =.claude/rules/= mirrors to the rulesets canon
For each: read the file, diff against the rulesets canonical, decide whether it's an intentional diverge (leave alone), stale (sync content), or should canonicalize (replace with symlink and accept the cross-repo dependency). The orchestration_dashboard_mvp pair is the project where Vrezh's PR review surfaced this whole thread, so any decision there has team-visibility implications.
-** TODO [#C] Audit language-specific rule files for cross-project duplication
+** TODO [#C] Audit language-specific rule files for cross-project duplication :chore:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
The four canonical rules (=commits=, =testing=, =verification=, =subagents=) are now symlinked across the five personal-project mirrors as of 2026-05-07. But several language-specific rule files exist in multiple project mirrors and may be duplicated or drifted:
@@ -1127,7 +1127,7 @@ The Elisp pair is the most suspicious — three repos using essentially the same
** TODO [#C] Consolidate =claude-templates/Makefile= after fold :chore:quick:solo:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Sibling follow-up from the fold child (2026-05-15). After the subtree merge, =rulesets/claude-templates/Makefile= still has its standalone =install= / =uninstall= / =list= / =test-scripts= targets. The =install= target's =bin/ai= logic is now duplicated in =rulesets/Makefile=. Both work; the redundancy is harmless but worth cleaning up.
@@ -1139,9 +1139,9 @@ Options:
Triggered by: 2026-05-15 fold session's refactor audit (commit =2d645fc=).
-** TODO [#C] Refactor =daily-prep.org= to delegate to =triage-intake.org= for the triage section
+** TODO [#C] Refactor =daily-prep.org= to delegate to =triage-intake.org= for the triage section :chore:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
=daily-prep.org= still does its own inline triage (Gmail × 3 accounts, Slack, Linear, GHE PRs, calendars) as part of the full prep flow. =triage-intake.org= is now a source-agnostic engine that loads =triage-intake.<source>.org= plugins (refactored 2026-05-26), so daily-prep could call the engine and consume its synthesis instead of duplicating the source-scan logic. That DRYs up a large workflow and keeps both flows in sync when sources change — a source change now lives in one plugin that both flows pick up.
@@ -1154,9 +1154,9 @@ Scope:
Origin: came up while authoring =triage-intake.org= on 2026-05-11; body refreshed after the engine/plugin refactor on 2026-05-26.
-** TODO [#C] Templatize =make coverage-summary= into the language bundles
+** TODO [#C] Templatize =make coverage-summary= into the language bundles :feature:
:PROPERTIES:
-:LAST_REVIEWED: 2026-05-26
+:LAST_REVIEWED: 2026-05-28
:END:
Borrow dotemacs's =make coverage-summary= into the language bundles. After =make coverage= writes a coverage file, =coverage-summary= prints per-unit covered/total with percentages, a unit-weighted project number, and a list of source files present on disk but missing from the coverage report.
@@ -1183,7 +1183,7 @@ Reference (dotemacs): =scripts/coverage-summary.el=, =modules/coverage-core.el=,
Origin: handoff from the .emacs.d session, 2026-05-25.
-** TODO [#C] Cross-project pattern catalog :spec:thinking:
+** TODO [#B] Cross-project pattern catalog :spec:thinking:
From pearl handoffs [[file:docs/design/2026-05-27-pattern-catalog-pearl-notes.org][2026-05-27]] + [[file:docs/design/2026-05-28-pattern-catalog-no-empty-input.org][2026-05-28 follow-up]].
Meta-question: how do good patterns travel from project A to project B? Pearl shipped three worked examples worth capturing — one-prompt picker with typed prefix (pearl-pick-source), magit-transient state buttons, and "no empty input as meaningful" (none-sentinel as first candidate). Each is a small principle with wide surface area; without a catalog, every project re-derives them from scratch.
@@ -1197,6 +1197,9 @@ Open design questions before any implementation:
Pearl recommends a one-page spec (problem + design + open questions + acceptance) before implementation. Pearl available to come back for spec-review iterations.
+*** 2026-05-28 Thu @ 08:12:55 -0500 Pearl shipped patterns 4-6, filed alongside the prior two
+Three more pearl handoffs landed and were filed during this audit. Filed: [[file:docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org][prompt-labels-and-defaults]] (patterns 4-5: label-matches-behavior, default-most-common with friction-proportional-to-consequence) and [[file:docs/design/2026-05-28-pattern-catalog-prompt-collapse.org][prompt-collapse]] (pattern 6: collapse N orthogonal prompts into one enriched prompt). The catalog's evidence base is now four pearl notes in =docs/design/= covering six patterns plus the synthesizing principle Pearl articulated — "choices on screen, accurately labeled, ordered by what the user most often wants, friction sized to the cost of being wrong."
+
:PROPERTIES:
:LAST_REVIEWED: 2026-05-28
:END:
@@ -1216,6 +1219,50 @@ Before any implementation: needs a real review pass on the spec, and a decision
:LAST_REVIEWED: 2026-05-28
:END:
+** TODO [#B] Codex Phase 1 — AI_AGENT_ID + session-context.d/<id>.org :feature:
+:PROPERTIES:
+:CREATED: [2026-05-28 Thu]
+:LAST_REVIEWED: 2026-05-28
+:END:
+
+Lifted from the broader codex runtime spec ([[file:docs/design/2026-05-28-generic-agent-runtime-spec.org]]) as the immediate-correctness slice independent of the larger arc. The singleton =.ai/session-context.org= is unsafe under simultaneous agents — two LLMs running in the same project at the same time would overwrite each other's session state.
+
+Scope: introduce an =AI_AGENT_ID= environment variable and split the single =session-context.org= into a per-agent =session-context.d/<id>.org= directory. No other phases of the runtime refactor are in this task — keep the surface small, fix the race, ship.
+
+Touches: =.ai/protocols.org= (rename rule + recovery anchor), =.ai/workflows/startup.org= (Phase A check), wrap-up workflow (rename target), per-project session record discoverability.
+
+Verification: simulate two agents sharing a project (separate AI_AGENT_ID values) and confirm session-context writes land in distinct files without interleaving.
+
+Parent: see [[#16 Generic agent runtime support][Generic agent runtime support — Codex spec v0]] above for the larger arc this is sliced from.
+
+** TODO [#C] Run =--archive-done= sweep at start of =open-tasks.org= Phase A :chore:quick:solo:
+:PROPERTIES:
+:CREATED: [2026-05-28 Thu]
+:LAST_REVIEWED: 2026-05-28
+:END:
+
+From pearl handoff 2026-05-28. =open-tasks.org= Next Mode reads =* Project Open Work= and skips =* Project Resolved= correctly, but a level-2 task that completed during a session sits as =** DONE= under Open Work until something archives it. Between cleanups, a freshly-DONE task can surface as a "what's next" candidate.
+
+Proposed fix: as the first step of =open-tasks.org= Phase A, run =emacs --batch -q -l .ai/scripts/todo-cleanup.el --archive-done todo.org=, then read =todo.org=. The cleanup tool already exists; this is wiring it into the workflow.
+
+Cost: a few hundred ms at the start of every "what's next" invocation. Win: recommendations never include DONE work.
+
+Optional refinement: gate behind a check for read-only / dry-run mode if that's ever introduced. The default invocation archives.
+
+** TODO [#C] Enumerate implementation tasks in =spec-review.org= Phase 6 :feature:solo:
+:PROPERTIES:
+:CREATED: [2026-05-28 Thu]
+:LAST_REVIEWED: 2026-05-28
+:END:
+
+From pearl handoff 2026-05-28. =spec-review.org= Phase 6 currently says "log deferred work to =todo.org=: v1 implementation = [#B] ... vNext/someday = [#D]." That covers deferred and v1 in passing but doesn't lift the spec's =Implementation phases= section into a drop-in =todo.org= block.
+
+Proposed addition to Phase 6: a structured step that reads the spec's =Implementation phases= section and produces a =[#B] TODO= entry per phase (subject line, tags, one-line body, pointer back to spec), plus a final entry for the test surface (unit / integration / e2e / manual-verify mirroring the spec's =Acceptance criteria= when present). Emit under a new section "Implementation tasks (drop-in for todo.org)" in the review file. Format follows =todo-format.md= (terse heading, body holds context, tags on heading).
+
+Three wins: handoff is one paste not a re-read; forces specs to be implementable in pieces (a spec without a phase decomposition fails this step, surfacing the shape problem); closes the loop on =Acceptance criteria= as manual-verify entries.
+
+If the spec lacks an =Implementation phases= section, the step is the prompt to ask the author to add one before =Ready=.
+
** DONE [#C] Iteration-history backfill for spec-review and spec-response :docs:followup:
CLOSED: [2026-05-28 Thu]
Source: org-drill inbox 2026-05-28.