docs(archive): Decompose pr-discussions from #4992

docs/pr-discussions/PR-4972-docs-add-agent-work-rhythm-and-prompt-flows.md

@@ -0,0 +1,119 @@
+---
+pr_number: 4972
+title: "docs: add agent work rhythm and prompt flows"
+author: "maximdolphin"
+state: "MERGED"
+created_at: "2026-05-25T18:57:13Z"
+merged_at: "2026-05-25T19:08:13Z"
+closed_at: "2026-05-25T19:08:13Z"
+head_ref: "codex/agent-work-rhythm"
+base_ref: "main"
+archived_at: "2026-05-25T20:41:09Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #4972: docs: add agent work rhythm and prompt flows
+
+## PR description
+
+## Summary
+
+- Adds `AGENT_WORK_RHYTHM_AND_PROMPT_FLOWS.md` to define hat-bound work schedules, free-time, review/red-team, reflection, and memory-maintenance blocks.
+- Documents deterministic MCP-driven prompt flows with reusable phases, phase gates, reviewer hats, artifacts, memory behavior, and graph ingestion.
+- Threads schedule and prompt-flow concepts through runtime architecture, implementation concepts, Work OS, build plan, UI, readiness checklist, Dapr actor context, and graph/retrieval docs.
+
+## Validation
+
+- `git diff --check HEAD~1 HEAD`
+- `rg -n "Agent Work Rhythm|Work Rhythm and Prompt Flows|validate_prompt_flow_start|Prompt Flow Registry|free time" agentic-organization/docs`
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-25T19:00:19Z)
+
+## Pull request overview
+
+Adds a new documentation surface describing hat-bound work schedules (“work rhythm”) and deterministic MCP-driven prompt flows, then threads those concepts through existing runtime, UI/observability, knowledge-graph, and implementation planning docs so the Organization layer treats time-blocks and flow execution as first-class governed artifacts.
+
+**Changes:**
+- Introduces `AGENT_WORK_RHYTHM_AND_PROMPT_FLOWS.md` defining schedule blocks, review/reflection/free-time expectations, and prompt-flow lifecycle/registry concepts.
+- Extends multiple architecture/plan docs to include schedule blocks + prompt flows in signals, UI views, runtime context, services, schema, and readiness checks.
+- Updates tool inventory and orchestration runtime notes to account for schedule/prompt-flow operations.
+
+### Reviewed changes
+
+Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
+
+<details>
+<summary>Show a summary per file</summary>
+
+| File | Description |
+| ---- | ----------- |
+| agentic-organization/docs/WORK_AND_RELEASE_MANAGEMENT_OS.md | Adds Work Schedule + Prompt Flow as core objects and introduces related signal families and governance bullets. |
+| agentic-organization/docs/UI_AND_OBSERVABILITY_CONCEPTS.md | Adds UI views for work rhythm and prompt-flow registry; extends graph node list. |
+| agentic-organization/docs/RUNTIME_TECH_AND_PACKAGE_STRATEGY.md | Extends actor-backed runtime context to include schedule block + prompt-flow run/phase identifiers. |
+| agentic-organization/docs/README.md | Links the new work-rhythm/prompt-flow doc from the docs index. |
+| agentic-organization/docs/ORGANIZATION_RUNTIME_ARCHITECTURE.md | Adds a new section describing work rhythm + prompt-flow concepts in the runtime architecture narrative. |
+| agentic-organization/docs/ORGANIZATION_LAYER_BUILD_PLAN.md | Adds services, workspace elements, and schema entities for schedules and prompt flows. |
+| agentic-organization/docs/IMPLEMENTATION_READINESS_CHECKLIST.md | Extends readiness requirements and preflight validations for schedules + prompt flows. |
+| agentic-organization/docs/IMPLEMENTATION_CONCEPTS.md | Adds entities/services and state-machine sketches for schedule blocks and prompt-flow runs; expands capability request requirements. |
+| agentic-organization/docs/DEPARTMENT_HAT_TOOL_INVENTORY.md | Adds tool bundles for Work Rhythm + Prompt Flow; expands Memory tool bundle. |
+| agentic-organization/docs/ALWAYS_ON_ORCHESTRATION_RUNTIME.md | Threads schedule block / prompt-flow linkage into scheduled job semantics. |
+| agentic-organization/docs/AGENT_WORK_RHYTHM_AND_PROMPT_FLOWS.md | New document defining the schedule model, prompt-flow phases/gates, and registry + reflection/free-time guardrails. |
+| agentic-organization/docs/AGENT_NATIVE_KNOWLEDGE_GRAPH.md | Extends node/edge kinds and suggested tables for schedule blocks and prompt-flow artifacts/runs. |
+</details>
+
+### COMMENTED — @maximdolphin (2026-05-25T19:05:08Z)
+
+_(no body)_
+
+### COMMENTED — @maximdolphin (2026-05-25T19:05:19Z)
+
+_(no body)_
+
+### COMMENTED — @maximdolphin (2026-05-25T19:05:24Z)
+
+_(no body)_
+
+## Review threads
+
+### Thread 1: agentic-organization/docs/AGENT_WORK_RHYTHM_AND_PROMPT_FLOWS.md:227 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:00:18Z):
+
+P1: The suggested prompt-flow registry table names drift from the authoritative names already used elsewhere in this doc set (e.g., `hat_prompt_flow_bindings`, `prompt_flow_phase_runs`). This will make cross-doc schema discussions ambiguous.
+
+**@maximdolphin** (2026-05-25T19:05:08Z):
+
+Fixed in `f37700e93` by aligning the registry entries to the authoritative schema names already used elsewhere: `hat_prompt_flow_bindings` and `prompt_flow_phase_runs`.
+
+### Thread 2: agentic-organization/docs/AGENT_WORK_RHYTHM_AND_PROMPT_FLOWS.md:228 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:00:19Z):
+
+P1: For consistency with the rest of the docs (which use `prompt_flow_gate_decisions` for reviewer decisions between phases), this entry should use the same name instead of `prompt_flow_review_decisions`.
+
+**@maximdolphin** (2026-05-25T19:05:19Z):
+
+Fixed in `f37700e93` by replacing `prompt_flow_review_decisions` with the canonical `prompt_flow_gate_decisions`.
+
+### Thread 3: agentic-organization/docs/RUNTIME_TECH_AND_PACKAGE_STRATEGY.md:174 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:00:19Z):
+
+P2: This section adds a runtime context field for the current prompt-flow phase ID, but the preceding list of `AgentSessionActor` setters doesn’t include a way to update it. Adding an explicit setter keeps the interface description aligned with the fields you expect to track.
+
+**@maximdolphin** (2026-05-25T19:05:24Z):
+
+Fixed in `f37700e93` by adding `setCurrentPromptFlowPhase()` to the `AgentSessionActor` interface list so it matches the runtime context fields.
+
+## General comments
+
+### @chatgpt-codex-connector (2026-05-25T18:57:19Z)
+
+Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
+Credits must be used to enable repository wide code reviews.
+
+### @maximdolphin (2026-05-25T19:03:54Z)
+
+Follow-up added in `fb59ae506`: researched the repo's existing universal-action-space/action-grammar prior art and folded it into the prompt-flow docs. The integration anchors to B-0200 (F# <-> CodeAct bridge), B-0201 (universal-action-space research lane), `docs/SAFE-AUTONOMOUS-ACTIONS.md`, and the action-mode/provenance research doc. Prompt flows now host Universal Action Grammar atoms with typed actor/target/precondition/observation/reversibility/evidence fields, and the concept is threaded into graph nodes/edges, DB records, Work OS signals/guardrails, MCP tools, implementation services, and readiness preflights.

docs/pr-discussions/PR-4974-feat-tools-flash-usb-ts-hardening-runtime-nonce-responsibili.md

@@ -0,0 +1,112 @@
+---
+pr_number: 4974
+title: "feat(tools): flash-usb.ts hardening \u2014 runtime nonce + responsibility acceptance + agent permission rule"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-25T19:22:15Z"
+merged_at: "2026-05-25T19:29:28Z"
+closed_at: "2026-05-25T19:29:28Z"
+head_ref: "feat/flash-usb-responsibility-acceptance-nonce-2026-05-25-c2"
+base_ref: "main"
+archived_at: "2026-05-25T20:59:30Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #4974: feat(tools): flash-usb.ts hardening — runtime nonce + responsibility acceptance + agent permission rule
+
+## PR description
+
+## Summary
+
+Strengthens `flash-usb.ts`'s confirmation gate so the runner's acceptance of responsibility is explicit + un-pre-bakeable, AND adds the agent permission rule so an authorized agent can invoke the script.
+
+Two changes, one coherent PR:
+
+### Script hardening
+
+- **Fresh 4-byte random nonce per run** (`node:crypto.randomBytes`)
+- **Acceptance phrase** the runner must type EXACTLY: `accept-destroy <device> <nonce>`
+- Nonce makes pre-baked agent input infeasible — runner has to OBSERVE the nonce at THIS run
+- Phrase explicitly says `accept-destroy` so the runner is SIGNING acceptance, not just verifying a path
+- Header + README updated with explicit liability framing
+
+### Permission rule
+
+- `Bash(bun full-ai-cluster/tools/flash-usb.ts *)` added to `.claude/settings.json` permissions.allow
+- The specific path-scoped rule registers with the classifier as "this script is pre-vetted" vs the broader `Bash(bun *)` wildcard
+
+## Liability framing (per the README + script header)
+
+> The permission rule grants INVOCATION, not absolution.
+> By completing the runtime confirmation prompt, the runner
+> (whether human OR agent acting on a runner's behalf) accepts
+> responsibility for the contents of the destination device.
+> The maintainer who committed this script + the permission rule
+> has no liability for a downstream runner who accepts responsibility
+> at the runtime gate.
+
+Composes with the framework's autonomy-first-class + NCI disciplines: agents act on their owner's behalf; the owner is responsible for their agent's actions; you are not responsible for what another maintainer's agent decides to do with substrate you provided in good faith.
+
+## Test plan
+
+- [ ] `bun full-ai-cluster/tools/flash-usb.ts` (no args) still exits 2
+- [ ] With one USB plugged in + valid ISO: shows device summary + the new acceptance phrase with fresh nonce
+- [ ] Typing `yes` is rejected (acceptance phrase required)
+- [ ] Typing an old nonce from a prior run is rejected (nonce is fresh per run)
+- [ ] Typing the correct phrase proceeds to dd
+- [ ] After merge: an authorized agent can invoke the script under the new permission rule
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-25T19:24:35Z)
+
+## Pull request overview
+
+Hardens the `full-ai-cluster/tools/flash-usb.ts` safety confirmation gate by requiring an explicit responsibility-acceptance phrase that includes a fresh per-run nonce, and documents/permits agent invocation via `.claude/settings.json`.
+
+**Changes:**
+- Add a per-run random nonce and require typing `accept-destroy <device> <nonce>` to proceed.
+- Expand README + script header text around the new confirmation semantics and liability framing.
+- Add a path-scoped Claude permissions allow rule for invoking `flash-usb.ts`.
+
+### Reviewed changes
+
+Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
+
+| File | Description |
+| ---- | ----------- |
+| full-ai-cluster/tools/README-flash-usb.md | Documents the nonce-based acceptance phrase and adds liability framing before agent authorization instructions. |
+| full-ai-cluster/tools/flash-usb.ts | Implements nonce-based acceptance phrase and updates confirmation prompt/error text. |
+| .claude/settings.json | Adds an explicit allow rule for `bun full-ai-cluster/tools/flash-usb.ts *`. |
+
+### COMMENTED — @AceHack (2026-05-25T19:25:46Z)
+
+_(no body)_
+
+### COMMENTED — @AceHack (2026-05-25T19:25:48Z)
+
+_(no body)_
+
+## Review threads
+
+### Thread 1: .claude/settings.json:54 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:24:35Z):
+
+`permissions.allow` already includes `Bash(bun *)`, which would permit running `bun full-ai-cluster/tools/flash-usb.ts ...` regardless of the newly added path-scoped rule. If the goal is to rely on a pre-vetted, narrow allowlist (as described in the PR), consider removing or narrowing `Bash(bun *)` so this entry is actually security-relevant (or document why both are needed).
+
+**@AceHack** (2026-05-25T19:25:48Z):
+
+Acknowledged — the path-scoped rule IS redundant from the permissions.allow standpoint (Bash(bun *) already matches). Keeping it because: (a) the auto-mode classifier's prior block message explicitly said 'add a Bash permission rule' — that classifier layer appears to look for SPECIFIC pre-vetted rules vs broad wildcards; (b) self-documenting for reviewers ('this script is explicitly permitted' is more legible than 'falls under bun *'); (c) future-proof if Bash(bun *) ever gets narrowed. The redundancy is by design, not oversight. Worth a CONTRIBUTING note though — filed as part of B-0728's pattern docs.
+
+### Thread 2: full-ai-cluster/tools/flash-usb.ts:296 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:24:35Z):
+
+The prompt says "type EXACTLY", but the input is normalized with `.trim()`, so leading/trailing whitespace will still be accepted. Either remove the `.trim()` to make "EXACTLY" true, or relax the prompt wording to match the actual comparison behavior.
+
+**@AceHack** (2026-05-25T19:25:46Z):
+
+Fixed — dropped .trim() so the prompt's 'EXACTLY' contract holds literally. Pushed in latest commit.

docs/pr-discussions/PR-4975-backlog-b-0728-destructive-tool-authoring-contract-rails-per.md

@@ -0,0 +1,85 @@
+---
+pr_number: 4975
+title: "backlog(B-0728): destructive-tool authoring contract (rails + permission-grants-invocation + runtime-acceptance gate)"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-25T19:24:43Z"
+merged_at: "2026-05-25T19:26:45Z"
+closed_at: "2026-05-25T19:26:45Z"
+head_ref: "backlog/b0728-destructive-tool-authoring-contract-2026-05-25-c2"
+base_ref: "main"
+archived_at: "2026-05-25T20:59:25Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #4975: backlog(B-0728): destructive-tool authoring contract (rails + permission-grants-invocation + runtime-acceptance gate)
+
+## PR description
+
+## Summary
+
+Codifies the pattern landed in PR #4974 (flash-usb.ts hardening) as a repo convention so future destructive tools follow the same shape. Three-part contract:
+
+1. **Hard safety rails** — refuse known bad inputs early with class exit codes
+2. **`.claude/settings.json` permission rule** grants INVOCATION, not absolution — path-scoped + reviewed alongside the target script in the same PR
+3. **Runtime acceptance gate with per-run nonce** — runner types `accept-<verb> <target> <nonce>` to sign acceptance of responsibility; nonce makes pre-baked agent input infeasible
+
+## Why now
+
+Aaron 2026-05-25:
+> *"this is a good flow now that addison and max are on the project i dont mind thinking about safety more"*
+> *"i have 27 years of land-the-lesson-before-anyone-has-to-relearn-it. i can bake in over time"*
+
+Solo-maintainer + single-trusted-agent: ceremony costs more than it pays back. Team + agents + new-to-CLI / new-to-K8s contributors: every safety rail is a contract everyone can audit.
+
+## What's in the row
+
+- Three-part contract explained
+- TypeScript template for future destructive-tool authors
+- Liability framing language for header / README / PR body
+- Composition with framework's autonomy-first-class + NCI
+- List of future destructive-tool candidates this contract would govern (wipe-cluster, restore-from-backup, rotate-master-keys, delete-pvc, drop-database, force-merge)
+- Acceptance criteria for the codification work itself
+
+## P2 because
+
+Cheap to codify NOW; every destructive tool added after benefits. Becomes P1 if a destructive tool gets authored without following the contract.
+
+Single file (+ index regen) — docs only; no code in this PR.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-25T19:26:59Z)
+
+## Pull request overview
+
+Codifies a repository convention for authoring destructive CLI tools by documenting a three-part “destructive-tool authoring contract” (safety rails, path-scoped agent invocation permission, and a runtime acceptance gate with a per-run nonce) using `flash-usb.ts` as the canonical reference.
+
+**Changes:**
+- Adds a new P2 backlog row (B-0728) documenting the destructive-tool contract, including a TypeScript skeleton/template.
+- Regenerates `docs/BACKLOG.md` to include the new backlog entry.
+
+### Reviewed changes
+
+Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
+
+| File | Description |
+| ---- | ----------- |
+| docs/backlog/P2/B-0728-destructive-tool-authoring-contract-rails-plus-permission-grants-invocation-plus-runtime-acceptance-gate-2026-05-25.md | New backlog row that defines the destructive-tool authoring contract and provides a template. |
+| docs/BACKLOG.md | Index update to include B-0728 under P2. |
+
+## Review threads
+
+### Thread 1: docs/backlog/P2/B-0728-destructive-tool-authoring-contract-rails-plus-permission-grants-invocation-plus-runtime-acceptance-gate-2026-05-25.md:52 (unresolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:26:59Z):
+
+The exit-code contract here doesn’t match the “canonical reference” behavior in `full-ai-cluster/tools/flash-usb.ts`: that script uses exit 1 both for confirmation-gate aborts *and* for unexpected/unhandled errors in `main().catch(...)`. Either update this section to describe exit 1 as the generic “non-success after safety rails passed” class (abort or runtime failure), or change the reference implementation to use a distinct exit code for internal errors so the contract is accurate.
+
+### Thread 2: docs/backlog/P2/B-0728-destructive-tool-authoring-contract-rails-plus-permission-grants-invocation-plus-runtime-acceptance-gate-2026-05-25.md:141 (unresolved)
+
+**@copilot-pull-request-reviewer** (2026-05-25T19:26:59Z):
+
+The TypeScript template includes imports (`execFileSync`, `spawn`) that aren’t used anywhere in the snippet. With this repo’s TS settings (`noUnusedLocals: true` in tsconfig), copy/pasting this skeleton into a real tool will fail typecheck/lint unless the author immediately edits imports. Consider removing unused imports from the template (or adding a clear placeholder use) so the template is “drop-in” for new scripts.