docs(adr): ADR-0077 — authoring-surface boundary (hook / flow / validation)#2422
Merged
Conversation
…ation), route by intent, loud-not-silent Names the hook vs flow vs validation-rule boundary for an AI-authored platform. Routes by intent not mechanism; tiers surfaces by audience (validation/flow business-legible, hook deliberately not); sets review friction by static provability (hook bodies always human-reviewed). Rules record-before-* flows cannot rewrite or veto the triggering write (output discarded, errors swallowed by design) and makes that loud via two new os build lints instead of silent at runtime. Declares extending record-change flow to mutate/veto/join-the-tx an explicit non-goal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This was referenced Jul 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds ADR-0077 — names the long-term boundary between hook, flow, and validation rule for an AI-authored platform.
Triggered by the review question "now that flow is this capable, is hook metadata still necessary, and when should each be used?" Answer: yes, hook stays — it uniquely owns the in-transaction write path (rewrite + veto) and the read path (
beforeFind/afterFind), neither of which flow can express by construction.Decisions
after-*side effects go to flow if ops may ever want to change them, else hook.)os build-provable (lower friction); a hook body is the only non-provable surface → always human-reviewed (ties to ADR-0038 / ADR-0033 draft-gating).os buildlints so the named failure mode becomes a build error instead of a silent runtime no-op.Code-grounded fact
record-before-*flows cannot rewrite or veto the triggering write: therecord_changetrigger discards the flow output and swallows its errors by design ("a flow failure must NEVER break the CRUD write that triggered it"); flow CRUD nodes don't thread the transaction, and ADR-0034's ALS ambient-tx doesn't survivesetImmediate. The "visual write-time gate" belongs to validation rule (veto) / hook (rewrite), never a before-flow.Non-goals (explicit)
Do not extend record-change flow to mutate / veto / join-the-transaction — that re-creates Salesforce's order-of-execution swamp and hands the AI more overlapping ways to express one intent.
Scope
Docs-only (one new ADR). The two
os buildlints and the skill decision-tree updates are recorded as follow-ups, not in this PR.🤖 Generated with Claude Code