Skip to content

docs(process): catch sibling systems before they're built; trim restated guidance - #3884

Merged
jhoffner merged 5 commits into
mainfrom
claude/nifty-curie-vw525v
Oct 25, 2026
Merged

jhoffner merged 5 commits into
mainfrom
claude/nifty-curie-vw525v

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Problem. Epic FIX-2058 built "a task waits on a person" twice. A suspension and a held question each had their own row field, Inbox source, answer route, deadline, cancel and crash recovery. A third PR then added glue to keep the two from colliding: a reconciler clause, a sweep rule, and refusals written on both sides. The amendment in #3881 fixed the design with one holds[] list. But every review step passed the split:

  • The split was decided as a sorting rule, with no shared type named.
  • An alternative was dropped for contradicting a rule from the same epic.
  • reuse-review compared each spec only against main, never against its siblings.
  • The glue looked like rigor.

Separately, our guidance has gotten bloated, with the same rules restated in many places.

What this does. Process docs only, no product code. 17 files, +146 / −318.

A. Five lessons, each a sentence or two, in one canonical home each:

  1. One job, one noun (philosophy.md, tenet 2, plus one line in asking-for-decisions.md). A decision that accepts a second way to do one job must name the type both ways write, and the next likely variant.
  2. A next-variant test in analysis → Other shapes. If adding the next variant would copy more than one piece, the shared abstraction is missing.
  3. An alternative that only contradicts the same epic's own decision goes back to the user (analysis guardrails, adhd scoring). It isn't "considered and dropped".
  4. reuse-review counts sibling specs' Adds as existing. Worked example Infer resource state types in projections and add portable projection resource schema options #3, which taught that separate holds are fine, is replaced by the holds[] case.
  5. Glue between our own mechanisms is a finding against the model (review coherence lens, cross-spec-review).

B. Streamlining. Rules stated in several places now live in one home, and the other copies are links:

  • asking for sign-off → asking-for-decisions.md
  • release notes → BP-022 and release-notes-workflow.md
  • POCs and settlements → spec-poc, settle-claim, orchestration.md
  • local PR watching → watch-pr
  • the convergence rule and PR-feedback cap → orchestration.md

CLAUDE.md's skill table is now one line per skill, and some history notes were removed. CLAUDE.md goes from 37.9 KB to 31.8 KB.

What's asked of you. Review the five additions, since tenet 2 is a philosophy change. Then decide on the proposals below.

Proposals left out (each changes a rule, so it's yours):

  • Drop orchestration.md → "Epics already running when this rule landed", a one-time migration note, once no epic from before the closure rule is still running.
  • Replace CLAUDE.md's full mirror of the universal BPs with a one-line index plus links. This needs the mirror policy in best-practices.md changed.
  • Reduce superseded BPs (001, 028, 029, 038) to one-line stubs that point at their tenets, instead of keeping their full text.
  • Make one canonical spec-review and PR-cap procedure that issue-lifecycle and epic-wake both cite. Today there are two prose copies.
  • Re-check reuse-review example Infer resource state types in projections and add portable projection resource schema options #3 against the code once FIX-2133 ships. For now it describes merged design, not shipped code.

Parts worth reviewing closely

  • The new tenet 2 line (docs/philosophy.md, about line 110). It's the one change at philosophy altitude.
  • issue-lifecycle and epic-lifecycle, the largest trims. I checked that every "never" and gate rule they dropped still exists in its canonical home: merge policy not waived by convergence, the coordinator dispatches, Codex as reviewer, private-package changesets, and approvals and merges in watch-pr.

Behavior preserved. No gate, approval, merge, "never", security, secrets or Linear-channel rule changed. No workflow script changed, and no heading or anchor was renamed.

Verification

  • node scripts/check-retired-terms.mjs: PASS, and --control PASS.
  • node goals/vocabulary/one-word-per-thing/sweep.mjs: PASS, and --control OK.
  • node scripts/check-isolation-coordinate.mjs: OK.
  • node scripts/validate-spec-folder.mjs: clear.
  • node .agents/workflows/verify.mjs: 332/332.
  • Relative-link and anchor check over every changed .md: 323 links. The only misses are pre-existing placeholder links in the example bodies of spec-template.md and pr-reviewer-guidance.md.
  • Not run: validate-side-chain-vocabulary.mjs, which needs pnpm install. CI covers it.

No changeset: process docs only, so no published package changes.


Generated by Claude Code

Five lessons from FIX-2058, where one user-visible concept (a task waits
on a person) was built twice and then glued together:

- tenet 2: a decision that accepts a second way to do one job names the
  shared type both write and the next likely variant, or it isn't ready
  for a gate; asking-for-decisions points at it
- analysis: the next-variant test under Other shapes
- analysis guardrails + adhd scoring: an alternative dropped only for
  contradicting a decision in the same epic goes back to the user
- reuse-review: sibling specs' Adds count as existing; worked example 3
  now teaches the holds[] case instead of "two holds are fine"
- review coherence lens + cross-spec-review: glue code that keeps two of
  our own mechanisms apart is a finding against the model

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
The always-loaded files restated rules whose full text lives elsewhere.
Each now keeps the one-line rule and links the canonical home:

- asking for sign-off (asking-for-decisions.md), in both files
- release notes (BP-022 + release-notes-workflow.md), in AGENTS.md
- artifacts a human reads (writing-for-humans.md), in AGENTS.md
- the Codex reviewer rule and workflow scripts (orchestration.md)
- the skill table: one line per skill; each skill's frontmatter holds
  the full description

No rule changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
orchestration.md and the lifecycle and POC skills each restated the same
rules. Kept the canonical statement and replaced the copies with links:

- spec POC vs settlement comparison and variant rules: spec-poc skill
- where a spec POC's record lives: spec-poc "Publishing it"
- when a settlement earns a draft PR: settle-claim Step 5
- settle-claim's restated trigger: orchestration.md "When it fires"
- local PR-watch mechanics (Monitor vs CronCreate, signals, cursor):
  watch-pr; orchestration.md keeps the coordinator's obligations
- spec-review budget and PR-feedback cap rationale in issue-lifecycle
  and epic-lifecycle: orchestration.md; the skills keep their mechanics
- drops the "considered and deferred: feedback router" history note

No gate, budget, cap or merge rule changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
issue-spec Step 6.5, BP-040, BP-041, pr-reviewer-guidance §3 and the
spec template each restated rules canonical in orchestration.md
("Spec review", "When it fires") or asking-for-decisions.md (the six
parts, the three-ask ceiling, filtering is sorting). They keep the
operational steps and link the rule. issue-spec's companion-skill
bullets for settle-claim and adhd shrink to when-to-reach-for-it.

No rule changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
@vercel

vercel Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 25, 2026 8:09pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 25, 2026 8:09pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 25, 2026 8:09pm UTC

Request Review

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: hold-unify
kind: reply

CI red: Test (2/3) (and the Typecheck & Test roll-up), not caused by this PR. This PR changes only .md files. The failure is packages/workforce/test/scheduled-task.test.ts:184, "the user's list of schedules … shows each schedule with its next run", with expected ['adoption','daily'] to deeply equal ['daily','adoption'].

Cause: the test depends on the clock. It hard-codes "the daily one runs before next Monday's":

  • adoption is 0 9 * * 1 in Europe/London, which is Mon 09:00 UTC (UK clocks went back today).
  • daily is 30 7 * * * in America/New_York, which is 11:30 UTC (still EDT).

So every week, from Sunday 11:30 UTC (after Sunday's daily run) until Monday 09:00 UTC, the next weekly run comes before the next daily one, and the hard-coded order is wrong. This run started at 18:29 UTC on a Sunday. main fails the same way inside that window. The code under test sorts correctly; only the test's assumption is wrong.

No fix exists yet. I'm not widening this docs PR to include one. Proposed patch: assert soonest-first from the values the test already checks, instead of a fixed order:

// Soonest first, whatever their keys.
const due = listed.schedules.map((s) => Date.parse(s.nextRunAt!));
expect(due).toEqual([...due].sort((a, b) => a - b));

The loop below it still pins each nextRunAt to the cron, so the test can still fail on a bad sort or a bad next-run time. An alternative is to pin Date to a midweek instant with vi.setSystemTime.

A re-run inside the window fails the same way, so I'll re-run this job once after Monday 09:00 UTC.


Generated by Claude Code

@jhoffner
jhoffner marked this pull request as ready for review October 25, 2026 20:05
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-25T20:10:49.261383Z f8ec42d New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review

Verdict: Direction is right — net −172 lines, budgets/POC/watch-pr/sign-off prose correctly delegated to orchestration.md, spec-poc, watch-pr, and asking-for-decisions.md. That is the cleaner maintenance shape this repo already uses elsewhere.

Where the approach overshot: The PR fixes duplication by deleting copies, but the FIX-2058 / sibling-reuse lesson is added in several skills at once (philosophy tenet, analysis next-variant test, reuse-review sibling search + §3 case study, cross-spec-review glue, review coherence glue). Agents now learn one invariant in ~5 places instead of one. A simpler alternative would have been:

  1. Two canonical homes — philosophy.md (why) + orchestration.md → Compose existing pieces (epic sibling specs count as “existing”; glue/reconciler = missing shared abstraction).
  2. One worked example — keep FIX-2058 in reuse-review §3 (or link specs/epics/FIX-2058/DECISIONS.md ER-8) without replacing the old generic hold/release table.
  3. Pointers elsewhere — analysis, cross-spec-review, review, adhd get one-line “apply compose-existing-pieces / reuse-review” links instead of restating tests.

What I would not revert: Removing the orchestration POC comparison table (→ spec-poc), watch-pr mechanics essay (→ skill), deferred feedback-router note, and lifecycle budget rewrites — all good layering.

Skipped (optional / follow-up): CLAUDE.md skill-table trigger column; AGENTS.md vs CLAUDE.md sign-off dedupe; audit-coherence alignment with the new glue smell.

No runtime/code risk. Happy to approve after a small canonicalization pass, but mergeable as-is if you accept the distributed-doc tradeoff.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/contributing/orchestration.md Resolved
Comment thread .agents/skills/reuse-review/SKILL.md Resolved
Comment thread .agents/skills/analysis/SKILL.md Resolved
Comment thread .agents/skills/review/SKILL.md Resolved
Comment thread .agents/skills/issue-lifecycle/SKILL.md Resolved
Name siblings-count-as-existing, glue as a missing abstraction, and the
next-variant test once, in orchestration.md -> Compose existing pieces.
analysis, reuse-review, cross-spec-review and review point at it instead
of each restating its slice. issue-lifecycle's round-cap reference gets a
real link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: hold-unify
kind: reply

CI red: Typecheck on f8ec42d5, not caused by this PR. It fails in @flow-state-dev/shift-manager: src/lib/usage.ts and test/usage.test.ts import LabClients from ./connection, which main no longer exports (TS2305, plus the implicit-any errors that follow from it). This PR touches only .md files. CI typechecks the PR merged with main, and main is red on its own now.

Cause: two merges crossed. FIX-2162 (7014ed3e) replaced LabClients with the single Client (connect(connection), with useLab() returning { client }). FIX-2141 (#3768) and FIX-2142 (#3795) were branched before that change and merged after it, so usage.ts still uses the old shape (clients.actions(flow).listFlows(), clients.sessions.listSessions, useLab().clients).

No fix exists yet (no open PR touches usage.ts). I'm not widening this docs PR to include one. Proposed patch, the same port 7014ed3e applied to action.ts and delegates.ts:

  • usage.ts:
    • import type { Client } from "@flow-state-dev/client" in place of LabClients; WeakMap<Client, …>.
    • usageFlowOf(client) reads client.flows().
    • runUsageQuery(client, flow) uses client.userId, runAction(client, …) and client.sessions.list({ userId: client.userId }).
    • useHarnessUsage reads const { client } = useLab().
  • test/usage.test.ts: fakeLab builds a fake Client (userId, flows(), flow(id).send / request(id).status(), sessions.list / sessions.requests) instead of the old actions() / sendAction shape.

Re-running won't help, because the failure is deterministic until main carries the port. The earlier Test (2/3) red is still the clock-dependent schedule test from my previous comment.


Generated by Claude Code

@jhoffner
jhoffner merged commit fb7c132 into main Oct 25, 2026
14 of 18 checks passed
@jhoffner
jhoffner deleted the claude/nifty-curie-vw525v branch October 25, 2026 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants