docs(solutions): column-agent execution-principal blast-radius learning

[gsxdsm]

Summary

Captures the institutional learning from the column-agent-assignment feature (#1432), which merged before the compound pass landed on its branch.

• New learning doc — docs/solutions/architecture-patterns/per-entity-execution-principal-override-blast-radius.md: when work can run as an identity other than the one stored on the entity, seven subsystems must be re-keyed in one design pass (session identity, permission gating, heartbeat serialization in both directions, resume queries, hot-swap/release invalidation, kill-switch flag parity, write-surface parity for safety gates). Each was discovered separately and at increasing cost across plan review, code review, and two PR-bot rounds — the checklist converts that into one up-front pass.
• CONCEPTS.md — adds Column agent and Effective agent (execution principal) to the Workflow columns & traits cluster.

Docs-only; no runtime changes.

Post-Deploy Monitoring & Validation

No additional operational monitoring required — documentation-only change.

---

Summary by CodeRabbit

• Documentation
  • Expanded workflow documentation with new glossary entries covering agent behavior patterns and execution-principal concepts under the experimental workflow model.
  • Added comprehensive architecture-pattern guidance addressing execution-principal overrides, including affected subsystems, integration requirements, session management, permission gating, serialization, change detection, and implementation examples.

[coderabbitai]

Too many files changed? Review this PR in Change Stack to see how the pieces fit before you dive in.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5b918023-1ec8-4494-a253-277bc186af59

📥 Commits

Reviewing files that changed from the base of the PR and between b8eea85 and c5c7293.

📒 Files selected for processing (2)

• CONCEPTS.md
• docs/solutions/architecture-patterns/per-entity-execution-principal-override-blast-radius.md

---

📝 Walkthrough

Walkthrough

This PR adds documentation for execution-principal agent binding in the experimental workflow columns model. It introduces two key concepts—Column agent and Effective agent—then provides a comprehensive architecture-pattern guide detailing which subsystems must be re-keyed when execution identity is overridden per entity.

Changes

Agent Execution Principal Glossary & Override Pattern

Layer / File(s)	Summary
Agent and execution principal concepts CONCEPTS.md	Workflow glossary entries define Column agent (feature-gated, defer/override scoped binding) and Effective agent (resolved execution principal used for permissions, heartbeats, resume, and change detection).
Execution-principal override blast-radius pattern docs/solutions/architecture-patterns/per-entity-execution-principal-override-blast-radius.md	Architecture-pattern guide for per-entity overrides covering subsystem re-keying checklist (session, gating, serialization, resume, watchers, kill-switch, write-surface), applicability criteria, and examples for test matrices and composite instance IDs.

A glossary grows wise with agent knowledge true, 🐰
When Column and Effective dance as they do,
Override patterns guide with seven-fold care,
Through sessions and gates and watchers to share,
So Fusion workflows execute bright and fair! ✨

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: documentation additions about column-agent execution-principal blast-radius patterns and related learning.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/column-agent-compound-learnings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

Documentation-only PR capturing institutional learning from the column-agent-assignment feature (PR #1432). No runtime changes.

• CONCEPTS.md — adds two new entries to the "Workflow columns & traits" cluster: Column agent (permanent binding of a registry agent + mode to a workflow column, with defer/override semantics and flag-guard behavior) and Effective agent (execution principal) (the resolved identity every identity-keyed subsystem must consult at execution time).
• docs/solutions/architecture-patterns/per-entity-execution-principal-override-blast-radius.md — new learning doc with proper YAML frontmatter, a seven-subsystem blast-radius checklist (session identity, permission gating, heartbeat serialization both directions, resume queries, change-detection/hot-swap, kill-switch parity, write-surface parity), and worked examples tied to FN-5893 surface-matrix testing. Both related file paths resolve in the repo.

Confidence Score: 5/5

Documentation-only change with no runtime impact; safe to merge.

Both changed files are pure documentation. The new CONCEPTS.md definitions are placed correctly within the Workflow columns & traits section, the YAML frontmatter in the learning doc contains all required fields, and both related file paths resolve to real files in the repo. Content is internally consistent with existing engine terminology and the FN-5893 surface-matrix rule already in AGENTS.md.

No files require special attention.

Important Files Changed

Filename	Overview
CONCEPTS.md	Adds "Column agent" and "Effective agent (execution principal)" definitions to the Workflow columns & traits cluster; placement between Trait and Lane is appropriate and content is consistent with the new learning doc.
docs/solutions/architecture-patterns/per-entity-execution-principal-override-blast-radius.md	New architecture-pattern learning doc with proper YAML frontmatter (all required fields present); both related file paths resolve in the repo; seven-subsystem checklist is internally consistent with CONCEPTS.md definitions and existing engine terminology.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Work item dispatched"] --> B{"Column has agent binding?"}
    B -- No --> C["Use task.assignedAgentId\n(legacy resolution)"]
    B -- Yes --> D{"Binding mode?"}
    D -- defer --> E{"Work carries own agent\nor complete model pair?"}
    E -- Yes --> C
    E -- No --> F["Effective agent =\nColumn agent"]
    D -- override --> F
    F --> G["Re-key ALL identity-keyed subsystems"]
    G --> G1["1. Session identity\n(model, persona, attribution)"]
    G --> G2["2. Permission gating\n(buildActionGateContext)"]
    G --> G3["3. Heartbeat serialization\n(both directions)"]
    G --> G4["4. Resume queries\n(effective identity pass)"]
    G --> G5["5. Change detection / hot-swap\n(release branch too)"]
    G --> G6["6. Kill-switch parity\n(every entry point)"]
    G --> G7["7. Write-surface parity\n(shared validator)"]

Loading

_{Reviews (1): Last reviewed commit: "docs(solutions): per-entity execution-pr..." | Re-trigger Greptile}