docs: production scope — remove MVP gating, add SSO + register ACs#146
Merged
Conversation
- Replace MVP/Phase-2 product gating with production platform scope - Rename Out of scope to Deferred capabilities across use cases - Add ADR-027 (Microsoft, Google, GitHub) and expand sign-in/register-org ACs - Require Terms/Privacy checkbox and editable org slug on registration - Add scripts/remove-mvp-from-docs.py for bulk terminology cleanup Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
📝 WalkthroughWalkthroughThis PR reframes product documentation from MVP/Phase terminology to production-scope language, specifies external identity provider behavior, and adds a Markdown code-fence integrity checker plus CI and schema-registration automation updates. ChangesDocumentation scope reframing and identity provider specification
Documentation integrity and CI automation tooling
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
|
- Remove dot-collapse regex that turned ../ into ./ - Add scripts/repair-doc-markdown-links.py to restore paths from main - Fix domain README back-links and ARCHITECTURE CLAUDE.md paths Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Revert mechanical regex corruption (collapsed code fences, spread/ ellipsis, ranges, relative links) by resetting docs to main, then re-apply only the genuine semantic changes: - PRODUCT_VISION/PROGRESS/README: production-scope reframe; no separate MVP or Phase product cut; page-builder marked not-started in-scope. - TECH_STACK: ADR-027 (Microsoft/Google/GitHub external identity providers via OpenIddict); ADR-004 reason + "production scale". - sign-in / register-org: external-provider AC group, ToS/Privacy acceptance, slug; layer statuses downgraded to reflect unbuilt ACs. - Domain READMEs: Phase -> Scope (production scope, implementation order is sequencing, not a product phase cut). - Plan/billing use-cases: MVP/Phase 2 -> separate billing initiative. - parallel-group + diagram comment: Phase 2 -> not yet implemented. - Strip "not in MVP" tails across use-case ACs. - AC group name kept as "Out of scope" to match agent-checklist owner. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
A bulk find-replace once collapsed indentation inside markdown code fences (PR #146) and every existing gate passed: lychee/link-targets check only links, use-case-docs only structure, prettier ignores unsupported-language fences and collapses prose whitespace anyway, and dotnet format/Biome never touch .md. The corruption was invisible. Add scripts/check-doc-code-fences.py: flags code-block lines indented by a single space (the fingerprint of collapsed indentation), exempting diff/patch fences. Zero false positives on the current tree; 453 lines across 7 files on the corrupted commit. Wire it into the doc-drift umbrella and widen the doc-drift-scope CI filter to all docs/** so playbook/reference edits — where the PR #146 corruption landed — also run the full-tree checks. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Comments that cite a specific PR ("landed in PR #142", "ships in PR #97")
go stale as the codebase evolves and duplicate provenance that git history
already owns. Keep the durable rationale, drop the PR pointers. Also widen
the doc-drift-scope CI filter to glob scripts/** instead of enumerating each
checker, so a new checker triggers the job without a manual list edit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ase indexes register-avro-schemas.sh hardcoded 15 of 22 published event schemas, so 7 (Identity user/role events, FormBuilder task events, WorkflowEngine form-step-reached) were silently never seeded. Replace the static list with a glob over src/Modules/**/Schemas/*Event.avsc, deriving each subject the same way Confluent's TopicNameStrategy does (axis.<module>.<kebab>-value) — verified to match every *KafkaTopics.cs constant. Adding a schema now needs no script edit. Also ran regenerate-domain-readme-index.py: the domain README "## Use Cases" tables had drifted from the use-case Purpose/title lines (notably the sign-in / register-org OAuth-provider updates). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (15)
docs/use-cases/workflow-builder/script-step/README.md (1)
50-63: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winStatus/deferred formatting should match the required use-case contract.
Please replace the table-based implementation status with the inline per-layer callout immediately after Out of scope, and record pending work using
**Deferred (PR#Nfollow-up):**.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/script-step/README.md` around lines 50 - 63, Replace the table-based "Implementation status" block with an inline callout placed immediately after the "Out of scope" section: change the existing markdown table to a single-line callout in the form "> **Implementation status** — Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳". Also convert the current "Gaps vs spec" bullet into a deferred note using the required phrasing: "**Deferred (PR `#N` follow-up):** JS sandbox execution, timeout enforcement, and \"Run test\" button pending workflow-engine + Frontend." Ensure these edits are applied in README.md around the same section that currently contains the table and the "Gaps vs spec" sentence.docs/use-cases/workflow-engine/cancel-execution/README.md (1)
50-63: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winUpdate this use-case to the required status/deferred callout format.
Please replace the table-style status + gaps section with the mandated inline implementation-status callout and explicit deferred entries (
**Deferred (PR#Nfollow-up):**) after Out of scope.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/cancel-execution/README.md` around lines 50 - 63, Replace the table-style implementation status and gaps under the "Pausing an execution and resuming it — cancel only." use-case with the mandated inline callout format: add a single callout line after the "Out of scope" section reading "> **Implementation status** — Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳", and move each outstanding item (Cancel button UI, Wolverine job abandonment, Form Task cancellation pending engine) into explicit deferred callouts using the exact wording "**Deferred (PR `#N` follow-up):** <short item description>" (replace N with the appropriate PR number) and ensure the API endpoint `POST /api/executions/{id}/cancel` remains noted as implemented; remove the old markdown table and the previous "Gaps vs spec" header entirely.docs/use-cases/workflow-builder/schedule-trigger/README.md (1)
50-64: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winConvert status section to the mandated use-case callout style.
This file still uses table-based status + “Gaps vs spec.” Please switch to the required inline per-layer implementation-status callout and express pending scope explicitly with
**Deferred (PR#Nfollow-up):**.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/schedule-trigger/README.md` around lines 50 - 64, Replace the table-based "Implementation status" and "Gaps vs spec" block with the mandated inline callout style placed immediately after the "Out of scope" section: a single-line blockquote starting with "> **Implementation status** — Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⚠️" and then convert each pending gap into explicit deferred items using the exact phrasing "**Deferred (PR `#N` follow-up):**" before each item (e.g., "**Deferred (PR `#N` follow-up):** Wolverine cron job registration on publish and deregistration on archive pending workflow-engine" and "**Deferred (PR `#N` follow-up):** cron expression validation (min 5-min interval, IANA timezone)"). Ensure you remove the old table and the "Gaps vs spec." heading so only the inline callout and the deferred bullets remain.docs/use-cases/workflow-builder/webhook-trigger/README.md (1)
49-63: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winUse the standardized implementation/deferred callouts for use-case docs.
Please switch from table-based status + gaps text to the required inline implementation-status callout and deferred entries in the
**Deferred (PR#Nfollow-up):**form.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/webhook-trigger/README.md` around lines 49 - 63, Replace the table-based "Implementation status" and "Gaps vs spec" sections in README.md with the standardized inline implementation-status callout and add explicit deferred entries: remove the markdown table and the "Gaps vs spec" paragraph, insert a single callout line like "> **Implementation status** — Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳" immediately after the "Out of scope" section, and create a "**Deferred (PR `#N` follow-up):**" bullet list that names the pending items (unique webhook URL generation, HMAC verification, payload mapping for workflow-engine + API layer) so they are proactively documented; ensure the new callout and deferred block replace the original table and gap text and keep the rest of the README.md content intact.docs/use-cases/workflow-builder/step-side-panel/README.md (1)
48-62: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winBring implementation status and deferrals into the required callout format.
This use-case should use the inline per-layer implementation-status callout after Out of scope, with pending items documented as
**Deferred (PR#Nfollow-up):**.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/step-side-panel/README.md` around lines 48 - 62, Update the "Implementation status" block to the required inline callout format used after the "Out of scope" section: replace the markdown table with a single callout line beginning with "> **Implementation status** —" followed by each layer and its status (e.g. "Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳"); move the "Gaps vs spec" items into the same callout as deferred entries using the exact phrasing "**Deferred (PR `#N` follow-up):**" (e.g. "**Deferred (PR `#N` follow-up):** slide-over panel, inline error indicators, auto-save pending Frontend; step config stored as JSONB dict in `steps` column.") and ensure this callout appears immediately after the "Out of scope" section header.docs/use-cases/workflow-builder/publish-workflow/README.md (1)
46-61: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winPlease align status/deferred callouts with the use-case doc standard.
After Out of scope, this should use the inline implementation-status callout format, and pending items should be captured as
**Deferred (PR#Nfollow-up):**entries rather than a generic gaps list.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/publish-workflow/README.md` around lines 46 - 61, Replace the current blocked "Implementation status" table and "Gaps vs spec" section with the standardized inline implementation-status callout immediately after the "Out of scope" section (use the exact phrasing style: "> **Implementation status** — Domain: ✅ | Application: ⚠️ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳"). Move each item currently under "Gaps vs spec" into one or more `**Deferred (PR `#N` follow-up):**` entries (e.g., "**Deferred (PR `#N` follow-up):** cron job registration and webhook URL generation pending WorkflowEngine integration (workflow-engine)" and "**Deferred (PR `#N` follow-up):** broken-step validation pending data-modeling/form-builder integration", replacing the generic gaps list), and remove the old table and "Gaps vs spec" heading so the file follows the use-case doc standard.docs/use-cases/workflow-builder/parallel-results/README.md (1)
45-59: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winUse the required implementation-status callout format and deferred notation.
This use-case still uses a status table plus free-form “Gaps vs spec.” Please convert to the required per-layer inline callout and mark pending items with
**Deferred (PR#Nfollow-up):**.As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files:
> **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/parallel-results/README.md` around lines 45 - 59, Replace the current table-style "Implementation status" and "Gaps vs spec" text in the parallel-results use-case README with the required inline callout format placed after the "Out of scope" section: create a single-line callout like "> **Implementation status** — Domain: ✅ | Application: ✅ | Infrastructure: ✅ | API: ✅ | Frontend: ⏳" and convert each gap item into a deferred entry using the exact syntax "**Deferred (PR `#N` follow-up):** <description>" (e.g., include "context namespacing by step ID and sibling-output blocking pending workflow-engine" and "design-time duplicate output warning pending" as separate Deferred lines), ensuring no status table remains and all deferred items use the PR # placeholder format.docs/use-cases/workflow-engine/error-channels/README.md (1)
47-63:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd explicit deferred follow-up entry in the implementation callout.
Line 48 introduces a deferred capability but it is only listed under Out of scope. Per use-case doc rules, also record it in the callout using the required deferred format.
Suggested doc patch
> **Gaps vs spec:** > - error notification channel config is not modeled in the domain (no channel list on `WorkflowExecution`) > - no `UpdateErrorNotificationChannelsCommand` handler > - notification channel configuration UI and per-workflow channel storage pending API + Frontend. +> - **Deferred (PR `#146` follow-up):** scenario-specific channel routing (e.g., notify only on HTTP step failures).As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/error-channels/README.md` around lines 47 - 63, Add an explicit deferred follow-up entry in the use-case implementation callout: update the "Implementation status" / "**Gaps vs spec:**" callout to include a line formatted exactly as "**Deferred (PR `#N` follow-up):**" noting that error notification channel config (no channel list on WorkflowExecution) and absence of an UpdateErrorNotificationChannelsCommand handler will be implemented in a follow-up PR; ensure the phrasing matches existing callout style and references WorkflowExecution and UpdateErrorNotificationChannelsCommand so the deferral is discoverable.docs/use-cases/workflow-engine/retry-history/README.md (1)
46-60:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd deferred tracking for side-by-side comparison in the implementation callout.
Please include this as
**Deferred (PR#Nfollow-up):** Comparing two retry attempts side-by-sidein the status callout.As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/retry-history/README.md` around lines 46 - 60, Update the implementation callout block that lists component statuses (the table and surrounding text labeled "Implementation status") to include a deferral note exactly as "**Deferred (PR `#N` follow-up):** Comparing two retry attempts side-by-side" (use PR `#N` placeholder) instead of leaving that functionality unmentioned; ensure the deferral is added as a separate line in the callout so it reads alongside the table and follows the documented pattern for deferred items.docs/use-cases/workflow-engine/execution-detail/README.md (1)
47-63:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winInclude a deferred callout entry for the replay/simulation capability.
Line 48 is a deferred scope item; add it under the callout as
**Deferred (PR#Nfollow-up):** ...for guideline compliance.As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/execution-detail/README.md` around lines 47 - 63, Add the deferred scope item "Replaying or simulating an execution from any point with a different context." into the use-case callout region by inserting a line under the existing "Implementation status" callout (the block that starts with "**Implementation status**" and the status table) as "**Deferred (PR `#N` follow-up):** Replaying or simulating an execution from any point with a different context." so the deferral follows the project's documentation guideline and appears alongside the other callout entries instead of remaining only under "Out of scope".docs/use-cases/workflow-engine/error-detail/README.md (1)
47-62:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winTrack this out-of-scope item as a formal deferred follow-up in the callout.
The out-of-scope bullet at Line 48 should also be captured in the implementation status callout using the required deferred template.
As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/error-detail/README.md` around lines 47 - 62, Update the implementation status callout to record the out-of-scope item as a formal deferred follow-up using the required template: add a line under the callout like "**Deferred (PR `#N` follow-up):** Sharing a link to a specific error detail view" (or similar) and reference the pending work items (`GetExecutionQuery` and error detail UI) so the out-of-scope bullet is captured there instead of only in the list; ensure the wording and template exactly follow the project's deferred format and include PR placeholder "`#N`" for tracking.docs/use-cases/workflow-engine/org-execution-history/README.md (1)
45-60:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winCapture this tenant-wide monitoring deferral in the callout with the standard template.
Please add
**Deferred (PR#Nfollow-up):** Platform-wide execution monitoring across all tenantsunder the implementation callout.As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/org-execution-history/README.md` around lines 45 - 60, Update the implementation callout under the "Implementation status" section to document the deferral using the standard template: insert the line "**Deferred (PR `#N` follow-up): Platform-wide execution monitoring across all tenants**" (replace N with the PR number) beneath the callout header so the tenant-wide monitoring is recorded as deferred rather than left as "Out of scope"; target the callout block containing the "Implementation status" table in README.md for this change.docs/use-cases/workflow-engine/isolated-steps/README.md (1)
48-77:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a deferred follow-up line for custom step types in the status callout.
The out-of-scope item on Line 49 should be mirrored in the callout using
**Deferred (PR#Nfollow-up):** ....As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/isolated-steps/README.md` around lines 48 - 77, The README's "Out of scope" list omits mirroring the custom step types deferral inside the Implementation status callout; update the callout block that begins with "> **Implementation status**" to include a line reading "**Deferred (PR `#N` follow-up):** Custom step types defined by users." so the deferral is documented per guidelines (use the exact "Deferred (PR `#N` follow-up):" phrasing) and ensure it appears alongside the existing status/gaps notes.docs/use-cases/workflow-engine/retry-execution/README.md (1)
49-67:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRecord automatic retry as an explicit deferred follow-up in the callout.
Line 50 should be reflected in the implementation status section using the required
**Deferred (PR#Nfollow-up):**format.As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/retry-execution/README.md` around lines 49 - 67, Update the use-case callout to record automatic retry as a documented deferred follow-up: replace the plain “Automatic retry (without user action).” note with a callout formatted as "**Deferred (PR `#N` follow-up):** Automatic retry (without user action)." and ensure the Implementation status table or the "Gaps vs spec" text reflects this deferred status (use the exact "**Deferred (PR `#N` follow-up):**" wording) so the README's callout and status entries follow the project's deferral documentation convention.docs/use-cases/workflow-engine/failure-notify/README.md (1)
46-63:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winDocument notification-integrations deferral in the implementation callout.
Line 47 marks a deferred capability; please add a matching
**Deferred (PR#Nfollow-up):**item in the callout section.As per coding guidelines, "Document deferrals in use-case callouts as
**Deferred (PR#Nfollow-up):**, not as ✅; proactively document without waiting for user to ask".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/failure-notify/README.md` around lines 46 - 63, Update the callout under the "Implementation status" section to add a deferred-note entry: add a line formatted exactly as "**Deferred (PR `#N` follow-up):** Notification integrations (PagerDuty/OpsGenie/Slack), the Application-layer notification dispatch handler, and wiring for the raised `ExecutionFailed` domain event (email/in‑app/webhook dispatch + rate-limiting) are deferred and will be implemented in a follow-up PR; ensure this text appears alongside the existing Implementation status/table so the deferral is explicitly documented per guidelines.
🟡 Minor comments (27)
docs/use-cases/README.md-53-56 (1)
53-56:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language to the fenced code block.
Line 53 opens a fence without a language, which triggers MD040 in CI tooling.
Proposed fix
-``` +```text Platform setup → Identity & users → Model data → Build workflows → Add forms → Execute & monitor → Build pages & widgets → End users</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/use-cases/README.mdaround lines 53 - 56, The fenced code block
containing the step sequence (the block that begins with "" and shows "Platform setup → Identity & users → Model data → Build workflows → Add forms → Execute & monitor → Build pages & widgets → End users") is missing a language tag which triggers MD040; update the opening fence to include a language (e.g. change the opening "" to "```text") so the block is recognized as plain text
and CI linting passes.</details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/field-validation/README.md-49-49 (1)</summary><blockquote> `49-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add required deferred follow-up notation for this scope exclusion.** Line 49 marks deferred work and should be reflected in the callout with `**Deferred (PR `#N` follow-up):** ...`. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/field-validation/README.md` at line 49, The callout for the scope exclusion "Cross-field validation (e.g., "end_date must be after start_date")." should be marked as a deferred follow-up using the project's required notation; replace the current phrasing or emoji with a callout starting "**Deferred (PR `#N` follow-up):** Cross-field validation (e.g., "end_date must be after start_date")." and fill in the correct PR number (or placeholder) so the README's use-case callout follows the documented convention. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/search-records/README.md-48-49 (1)</summary><blockquote> `48-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Track these deferred capabilities using required callout syntax.** Lines 48–49 should be reflected in the use-case callout as `**Deferred (PR `#N` follow-up):** ...` items. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/search-records/README.md` around lines 48 - 49, Update the use-case callout in README.md to document the two deferred capabilities by replacing the plain list items "OR-logic between filters" and "Saved filters" with entries prefixed using the required callout syntax; specifically change them to lines beginning with "**Deferred (PR `#N` follow-up):** OR-logic between filters" and "**Deferred (PR `#N` follow-up):** Saved filters" (replace N with the PR number when known) so the use-case callout follows the project's deferral documentation guideline. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/list-records/README.md-49-50 (1)</summary><blockquote> `49-50`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Record both deferred items with explicit PR follow-up callouts.** Lines 49–50 define deferred capabilities and should be listed in callouts as `**Deferred (PR `#N` follow-up):** ...` entries. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/list-records/README.md` around lines 49 - 50, Update the two deferred bullets "Saved views / custom column configurations." and "Inline editing in the list." to be explicit PR follow-up callouts using the required format; replace each bullet with a callout line like **Deferred (PR `#N` follow-up):** Saved views / custom column configurations. and **Deferred (PR `#N` follow-up):** Inline editing in the list., ensuring you use the exact Markdown callout syntax requested and keep the original text after the colon so reviewers can find these items in README.md (search for the exact phrases "Saved views / custom column configurations." and "Inline editing in the list."). ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/list-models/README.md-47-47 (1)</summary><blockquote> `47-47`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Capture this deferred capability in the mandated callout format.** Line 47 should have a corresponding `**Deferred (PR `#N` follow-up):** ...` entry in the use-case callouts. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/list-models/README.md` at line 47, The line containing "Folders or categories for organizing models." should be turned into a mandated use-case callout by replacing that plain sentence with a deferred callout; change it to the format "**Deferred (PR `#N` follow-up):** Folders or categories for organizing models." (ensure you pick the correct PR number in place of N) so the deferred capability is documented using the required callout style. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/edit-record/README.md-47-47 (1)</summary><blockquote> `47-47`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Document this deferral explicitly in the status callout.** Line 47 defines deferred scope, but it is not captured using the required `**Deferred (PR `#N` follow-up):**` callout format. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/edit-record/README.md` at line 47, Replace the plain deferred note "Edit history / audit trail per record." with the required callout format by prepending "**Deferred (PR `#N` follow-up):**" so the line reads e.g. "**Deferred (PR `#N` follow-up):** Edit history / audit trail per record." and update N to the actual PR number; ensure this change is applied in the README.md use-case status callout where that deferred scope is declared. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/edit-model/README.md-49-49 (1)</summary><blockquote> `49-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Track this deferred scope item using the required deferral format.** Line 49 is a deferred capability and should be mirrored in the callout as `**Deferred (PR `#N` follow-up):** ...` instead of remaining only in Out of scope. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/edit-model/README.md` at line 49, Replace the plain "Undo history for field changes." out-of-scope note with a proper deferred callout: add a callout line reading "**Deferred (PR `#N` follow-up):** Undo history for field changes." so the deferred capability is explicitly documented in the use-case callout; locate the existing plain text "Undo history for field changes." in README.md and mirror it into that exact deferred callout format (update PR `#N` to the actual PR number when known). ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/reorder-fields/README.md-46-46 (1)</summary><blockquote> `46-46`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add a deferred follow-up callout for this new exclusion.** Line 46 should be paired with an explicit `**Deferred (PR `#N` follow-up):** ...` entry in the callout section. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/reorder-fields/README.md` at line 46, Add an explicit deferred follow-up callout for the new exclusion "Hiding fields from the default list view per user." by inserting a line in the callout section reading "**Deferred (PR `#N` follow-up):** Hiding fields from the default list view per user." so the line at "Hiding fields from the default list view per user." (the new exclusion) is paired with a documented deferred action; ensure the callout uses the exact "Deferred (PR `#N` follow-up):" prefix per guidelines and appears in the callout block near the other deferred entries in README.md. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/data-modeling/edit-data-class/README.md-45-45 (1)</summary><blockquote> `45-45`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add explicit deferral callout for this out-of-scope item.** Line 45 introduces a deferred capability, but the file does not document it in the required callout format. Please add an `Implementation status` callout entry like `**Deferred (PR `#N` follow-up):** ...` for this item. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/data-modeling/edit-data-class/README.md` at line 45, The README currently lists "Version history of data class changes." but lacks the required deferral callout; add an "Implementation status" callout immediately after that line using the exact formatting `**Deferred (PR `#N` follow-up):** <brief reason/next steps>` (replace `#N` with the PR number and give a short action item), ensuring the callout appears as a separate bullet or paragraph under the same section so it follows the project's "Document deferrals" guideline. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/add-form-field/README.md-49-50 (1)</summary><blockquote> `49-50`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Use required deferral callout format for deferred scope items.** This deferred capability is documented as a plain out-of-scope bullet. Please record it as a deferral using the required `**Deferred (PR `#N` follow-up):**` format. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/add-form-field/README.md` around lines 49 - 50, Replace the plain "Out of scope" bullet about conditional field visibility with the project's required deferral callout format: change the line referencing "Conditional field visibility (show field only if another field has a certain value)" to a deferral entry using the exact prefix "**Deferred (PR `#N` follow-up):**" followed by the same text (e.g., "**Deferred (PR `#N` follow-up):** Conditional field visibility (show field only if another field has a certain value)"), replacing N with the follow-up PR number when known; ensure the rest of the "Out of scope" section follows the same deferral style. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/create-form/README.md-44-45 (1)</summary><blockquote> `44-45`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Track this deferred capability with the required deferral callout.** Please replace the plain out-of-scope bullet with `**Deferred (PR `#N` follow-up):** Form templates / starter library.` As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/create-form/README.md` around lines 44 - 45, Replace the plain out-of-scope bullet that currently reads "Out of scope - Form templates / starter library." with the required deferral callout text: "**Deferred (PR `#N` follow-up):** Form templates / starter library." Locate the exact list item in README.md that contains the "Out of scope" bullet (the line with "Form templates / starter library.") and substitute it with the specified deferral phrasing, keeping punctuation and bold formatting exactly as shown. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/edit-form/README.md-45-46 (1)</summary><blockquote> `45-46`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Document this deferred scope item using the required callout format.** Please express this as `**Deferred (PR `#N` follow-up):** Form versioning ...` instead of a plain out-of-scope bullet. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/edit-form/README.md` around lines 45 - 46, Replace the current out-of-scope bullet with the required deferred-callout format: change the line "*Out of scope* - Form versioning (publishing a new "version" of a form) — edits are live immediately." to "**Deferred (PR `#N` follow-up):** Form versioning (publishing a new \"version\" of a form) — edits are live immediately." (update PR `#N` to the actual PR number if known); look for the same text in README.md under the "Out of scope" or use-case callouts to ensure consistency. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/delete-form/README.md-45-46 (1)</summary><blockquote> `45-46`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Use the standardized deferred-callout notation here.** This item should be documented as a deferral (`**Deferred (PR `#N` follow-up):** ...`) instead of a plain out-of-scope bullet. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/delete-form/README.md` around lines 45 - 46, Replace the plain out-of-scope bullet "Recovering a soft-deleted form." with the standardized deferred-callout format by turning that bullet into "**Deferred (PR `#N` follow-up):** Recovering a soft-deleted form." (use the real PR number in place of N) so the README's Out of scope section uses the required deferred-callout notation instead of a plain bullet. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/assignment-notify/README.md-46-49 (1)</summary><blockquote> `46-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Convert deferred items to the mandated deferral callout format.** Both deferred capabilities are currently plain bullets under Out of scope. Please document them as `**Deferred (PR `#N` follow-up):** ...`. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/assignment-notify/README.md` around lines 46 - 49, The two items under the "Out of scope" section ("Push notifications (mobile)." and "Escalation notifications if the form is not submitted after X hours — timeout causes failure, not escalation.") should be converted from plain bullets into mandated deferred callouts by replacing each bullet with a line starting "**Deferred (PR `#N` follow-up):**" followed by the original text (choose the correct PR number for N); update the README.md "Out of scope" block so both entries use the exact callout format and ensure punctuation and wording remain the same after the prefix. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/form-field-validation/README.md-48-49 (1)</summary><blockquote> `48-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Switch this deferred item to the mandated deferral callout.** Please record this using `**Deferred (PR `#N` follow-up):** ...` rather than an out-of-scope bullet. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/form-field-validation/README.md` around lines 48 - 49, Replace the "*Out of scope* - Cross-field validation (e.g., "end date must be after start date")." bullet with the mandated deferral callout format by changing that line to begin with "**Deferred (PR `#N` follow-up):**" followed by the same description (e.g., "**Deferred (PR `#N` follow-up):** Cross-field validation (e.g., \"end date must be after start date\")."); ensure the exact phrase "Cross-field validation" is preserved so readers can find it and update PR number when filing the follow-up. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/form-timeout/README.md-47-48 (1)</summary><blockquote> `47-48`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Use the required deferral callout for this deferred capability.** Please replace the plain bullet with `**Deferred (PR `#N` follow-up):** Sending a reminder notification before timeout expires.` As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/form-timeout/README.md` around lines 47 - 48, Replace the plain out-of-scope bullet "Sending a reminder notification before timeout expires." with the required deferral callout format: change that line to "**Deferred (PR `#N` follow-up):** Sending a reminder notification before timeout expires." so the deferred capability is documented using the mandated `**Deferred (PR `#N` follow-up):**` callout instead of a plain bullet. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/form-builder/link-form-step/README.md-47-47 (1)</summary><blockquote> `47-47`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Use required deferred-callout format for this deferred scope item.** This out-of-scope bullet should be mirrored in the use-case callout as `**Deferred (PR `#N` follow-up):** ...` instead of remaining only as a plain scoped bullet. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/form-builder/link-form-step/README.md` at line 47, Replace the plain out-of-scope bullet "Creating a new form from within the workflow canvas (must go to Form Builder)" with the required deferred-callout format and mirror it in the use-case callout: change the bullet to start with "**Deferred (PR `#N` follow-up):**" followed by the original text, and update the corresponding use-case callout in this README to include the same "**Deferred (PR `#N` follow-up):** ..." entry so the deferral is explicitly documented; ensure you update the README.md use-case callout section where deferred items are listed. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/canvas-nav/README.md-47-47 (1)</summary><blockquote> `47-47`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Document this as a formal deferral in the callout block.** Line 47 should be mirrored as `**Deferred (PR `#N` follow-up):**` to keep deferred-scope tracking consistent. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/canvas-nav/README.md` at line 47, Replace the plain line "Touch/gesture controls for tablet use." inside the use-case callout with a formal deferral header: prepend "**Deferred (PR `#N` follow-up):**" so the callout becomes "**Deferred (PR `#N` follow-up):** Touch/gesture controls for tablet use."; update the callout containing that phrase (search for the exact string "Touch/gesture controls for tablet use.") to ensure it follows the documented deferral format and keep PR number placeholder or actual PR number when known. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/platform-foundation/view-plans/README.md-42-43 (1)</summary><blockquote> `42-43`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Track these out-of-scope items as explicit deferrals.** Lines 42–43 read as deferred product work; please add a `**Deferred (PR `#N` follow-up):**` callout under Implementation status so the follow-up path is explicit. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/platform-foundation/view-plans/README.md` around lines 42 - 43, Update the "Implementation status" section in the README to explicitly mark the two deferred items with the required deferral callout instead of leaving them as plain list entries: add a line starting with "**Deferred (PR `#N` follow-up):**" underneath the Implementation status heading and list "Monthly vs annual billing toggle" and "Per-seat pricing" there (replace N with the follow-up PR number when known); ensure these items are not marked as completed or with a checkmark and keep the wording exactly as the prescribed deferral callout. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/archive-workflow/README.md-46-46 (1)</summary><blockquote> `46-46`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Convert this out-of-scope bullet into an explicit deferred tracker entry.** Line 46 should be reflected in a `**Deferred (PR `#N` follow-up):**` callout so ownership/timeline is documented. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/archive-workflow/README.md` at line 46, Convert the out-of-scope bullet "Automatic archiving after N days of inactivity." into an explicit deferred callout by replacing the bullet with a callout starting with "**Deferred (PR `#N` follow-up):**" followed by a short ownership/timeline note (owner and expected follow-up or backlog ticket), e.g., "**Deferred (PR `#N` follow-up):** Automatic archiving after N days of inactivity — owner: `@team-or-person`, follow-up: implement scheduled archiver or add to backlog by YYYY-MM-DD." Ensure the original bullet text is removed and the new callout appears in the same list/section so the deferral is clearly documented. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/add-canvas-step/README.md-48-48 (1)</summary><blockquote> `48-48`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add a deferred follow-up callout for this scope exclusion.** Line 48 marks a deferred capability; please mirror it in the implementation callouts as `**Deferred (PR `#N` follow-up):**`. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/add-canvas-step/README.md` at line 48, The README for the "Add canvas step" use-case currently marks a deferred capability but doesn't follow our deferral format; update the implementation callouts to include a matching deferred callout by adding "**Deferred (PR `#N` follow-up):**" for the same scope exclusion referenced in the deferred capability, ensuring the implementation callouts mirror the deferred status; locate the deferred mention in the Add-canvas-step README and add the exact "**Deferred (PR `#N` follow-up):**" prefix where implementation actions or exclusions are listed so the deferral is documented consistently. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/bulk-export/README.md-45-45 (1)</summary><blockquote> `45-45`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add deferred-callout traceability for scheduled backups.** Line 45 is deferred scope and should be paired with a `**Deferred (PR `#N` follow-up):**` callout in the status section. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/bulk-export/README.md` at line 45, The "Scheduled automatic backups." deferred scope on the line should be documented in the status callouts as a deferred item; update the status section to add a matching callout like "**Deferred (PR `#N` follow-up):** Scheduled automatic backups." (replace PR `#N` with the actual PR number) so the deferred scope is explicitly recorded and paired with the line "Scheduled automatic backups." in the README. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/platform-foundation/verify-email/README.md-49-49 (1)</summary><blockquote> `49-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Link this deferred item to an explicit follow-up callout.** Line 49 introduces a deferred capability (“Automatic re-send after X minutes.”) but it isn’t explicitly tracked in a `**Deferred (PR `#N` follow-up):**` callout. Add that linkage in the implementation status block for traceability. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/platform-foundation/verify-email/README.md` at line 49, The deferred capability "Automatic re-send after X minutes." must be added to the implementation status callouts: locate the implementation status block in README.md and add a callout line formatted exactly as "**Deferred (PR `#N` follow-up):** Automatic re-send after X minutes." (replace PR `#N` with the actual follow-up PR number or a placeholder if unknown) so the item is explicitly tracked instead of left inline. ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/canvas-undo/README.md-48-48 (1)</summary><blockquote> `48-48`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Track server-side snapshots as a deferred follow-up item.** Line 48 marks deferred work and should be called out in implementation status using `**Deferred (PR `#N` follow-up):**`. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/canvas-undo/README.md` at line 48, Replace the standalone "Server-side version history with named snapshots." bullet with the documented deferral format required by our guidelines: change that text to start with "**Deferred (PR `#N` follow-up):** Server-side version history with named snapshots." so that the README use-case callout explicitly marks it as a deferred follow-up; locate the line containing the phrase "Server-side version history with named snapshots." and update it accordingly (replace N with the PR number when known). ``` </details> </blockquote></details> <details> <summary>docs/use-cases/workflow-builder/parallel-group/README.md-63-63 (1)</summary><blockquote> `63-63`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Use required deferred-callout format for pending `ParallelGroup`/`JoinType`.** This line describes deferred implementation but doesn’t use the mandated `**Deferred (PR `#N` follow-up):**` format in the use-case callout. Please rewrite this gap item using that prefix and a follow-up PR reference placeholder if needed. As per coding guidelines, "Document deferrals in use-case callouts as `**Deferred (PR `#N` follow-up):**`, not as ✅; proactively document without waiting for user to ask". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-builder/parallel-group/README.md` at line 63, Replace the informal deferred note about ParallelGroup and JoinType with the mandated deferred-callout format; specifically, update the sentence that currently reads "parallel group represented via step config in existing JSONB storage. `ParallelGroup` and `JoinType` are not yet implemented — shown as planned (dashed) in diagram." to start with "**Deferred (PR `#N` follow-up):**" and then state the deferral e.g. "**Deferred (PR `#N` follow-up):** ParallelGroup and JoinType are pending implementation; parallel group is represented via step config in existing JSONB storage and shown as planned (dashed) in diagram." so the callout uses the exact prefix and includes a PR placeholder. ``` </details> </blockquote></details> <details> <summary>scripts/check-doc-code-fences.py-83-86 (1)</summary><blockquote> `83-86`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Preserve full fence marker length for fence closing detection** In `scripts/check-doc-code-fences.py` (around Lines 83-86), truncating the opener via `fence_marker = marker[:3]` can incorrectly close fences opened with 4+ backticks/tilde, breaking `in_fence` state when a code line starts with only 3 backticks. The repo contains 4+ fence openers matching the pattern `^( {0,3})(`{4,}|~{4,})`, so this can affect real runs. <details> <summary>Proposed fix</summary> ```diff - fence_marker = marker[:3] + fence_marker = marker exempt = fence_match.group(2).lower() in EXEMPT_LANGS - elif fence_marker and line.lstrip().startswith(fence_marker): + elif fence_marker and re.match( + rf"^(?: {{0,3}}){re.escape(fence_marker)}(?:\s*)$", + line, + ): in_fence = False fence_marker = None exempt = False ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check-doc-code-fences.py` around lines 83 - 86, The fence closing logic truncates the opener to three chars causing premature closes; instead of assigning fence_marker = marker[:3], preserve the full marker (use fence_marker = marker) and continue using the existing check that compares line.lstrip().startswith(fence_marker); adjust any logic that relied on a 3-char marker so closing detection matches the original opener length (marker, fence_match) and keeps in_fence accurate. ``` </details> </blockquote></details> <details> <summary>scripts/register-avro-schemas.sh-33-36 (1)</summary><blockquote> `33-36`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **`DRY_RUN=0` still enables dry-run mode.** `[[ -n "$DRY_RUN" ]]` is true for any non-empty value, so the intuitive "off" value `DRY_RUN=0` skips registration. Gate on the documented value instead. <details> <summary>🔧 Proposed fix</summary> ```diff - if [[ -n "$DRY_RUN" ]]; then + if [[ "$DRY_RUN" == "1" ]]; then ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/register-avro-schemas.sh` around lines 33 - 36, The current dry-run guard uses [[ -n "$DRY_RUN" ]] which treats DRY_RUN=0 as enabled; change the if condition in the register block to test for the documented "on" values explicitly (e.g. check if DRY_RUN == "1" or DRY_RUN == "true" (case-insensitive)) so only those values enable dry-run; update the if that references DRY_RUN in the registration branch to use that explicit comparison. ``` </details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comment on lines
64
to
75
| > **Implementation status** | ||
| > | ||
| > | Layer | Status | | ||
| > |-------|--------| | ||
| > | Domain | ✅ | | ||
| > | Application | ✅ | | ||
| > | Infrastructure | ✅ | | ||
| > | API | ✅ | | ||
| > | Application | ⚠️ | | ||
| > | Infrastructure | ⚠️ | | ||
| > | API | ⚠️ | | ||
| > | Frontend | ⚠️ | | ||
| > | ||
| > **Gaps vs spec:** Login page + PKCE flow + app shell/dashboard scaffold on PR #50 branch. BroadcastChannel multi-tab refresh, account lockout UI, and unverified-email screen polish pending. | ||
| > | ||
| > **Deferred (PR #50 follow-up):** none for this US. | ||
| > **Gaps vs spec:** Email/password sign-in (login page + PKCE flow + app shell/dashboard scaffold) on PR #50 branch. **External identity providers (Microsoft/Google/GitHub, ADR-027) are spec'd but not yet implemented** — no provider registration in OpenIddict, no account-linking handler, no provider buttons on the sign-in page. BroadcastChannel multi-tab refresh, account lockout UI, and unverified-email screen polish also pending. | ||
| > |
There was a problem hiding this comment.
Align implementation-status and deferral callouts with use-case doc rules.
Line 64 onward still uses a table-style status block and free-form pending text. Please switch to the required per-layer callout format and mark unfinished scope using the required deferred notation (with PR reference) in the callout.
As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files: > **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as **Deferred (PR #N follow-up):**, not as ✅; proactively document without waiting for user to ask”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/use-cases/identity-access/sign-in/README.md` around lines 64 - 75,
Replace the table-style "Implementation status" block and the free-form "Gaps vs
spec" text with the project's required per-layer callout format: add a single
callout line after the "Out of scope" section that reads like ">
**Implementation status** — Domain: ✅ | Application: ⚠️ | Infrastructure: ⚠️ |
API: ⚠️ | Frontend: ⚠️" and convert the free-form deferrals into the formal
deferred notation (e.g. "**Deferred (PR `#50` follow-up):** External identity
providers (Microsoft/Google/GitHub, ADR-027); account-linking handler; provider
registration in OpenIddict; provider buttons on sign-in page; BroadcastChannel
multi-tab refresh; account lockout UI; unverified-email screen polish") so each
unfinished item is clearly marked per the use-case doc rules.
Comment on lines
64
to
75
| > **Implementation status** | ||
| > | ||
| > | Layer | Status | | ||
| > |-------|--------| | ||
| > | Domain | ✅ | | ||
| > | Application | ✅ | | ||
| > | Infrastructure | ✅ | | ||
| > | API | ✅ | | ||
| > | Frontend | ✅ | | ||
| > | Domain | ⚠️ | | ||
| > | Application | ⚠️ | | ||
| > | Infrastructure | ⚠️ | | ||
| > | API | ⚠️ | | ||
| > | Frontend | ⚠️ | | ||
| > | ||
| > **Gaps vs spec:** none. `Idempotency-Key` header on `POST /api/organizations/` deduplicates rapid resubmits (Pending/Completed/Failed state). | ||
| > **Gaps vs spec:** Email/password registration is complete — `Idempotency-Key` header on `POST /api/organizations/` deduplicates rapid resubmits (Pending/Completed/Failed state), slug auto-generated with uniqueness retry. **Not yet implemented:** Terms of Service / Privacy Policy acceptance (recording accepted version on the account) and external-provider sign-up (Microsoft/Google/GitHub, ADR-027) — no provider registration in OpenIddict, no provider buttons on the registration page. | ||
| > |
There was a problem hiding this comment.
Use the required implementation-status/deferred callout format.
Line 64 onward should use the mandated implementation-status callout syntax and explicit deferred follow-up notation instead of a status table + free-form gap text.
As per coding guidelines, “Add implementation status callout per layer after Out of scope section in use-case files: > **Implementation status** — Domain: ✅ | Application: ⚠️ | …” and “Document deferrals in use-case callouts as **Deferred (PR #N follow-up):**, not as ✅; proactively document without waiting for user to ask”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/use-cases/platform-foundation/register-org/README.md` around lines 64 -
75, Replace the current status table and free-form "Gaps vs spec" text in the
README.md with the mandated single-line implementation-status callout format;
specifically change the block beginning at the Implementation status header to
use the prescribed syntax: "> **Implementation status** — Domain: ⚠️ |
Application: ⚠️ | Infrastructure: ⚠️ | API: ⚠️ | Frontend: ⚠️" and convert each
"Not yet implemented" gap into explicit deferred callouts using the exact
phrasing "**Deferred (PR `#N` follow-up):**" followed by the item (e.g., Terms of
Service/Privacy Policy acceptance — record accepted version; external-provider
sign-up — OpenIddict provider registration and provider buttons on registration
page), ensuring each deferred item references a PR placeholder number and
appears directly after the callout line.
Comment on lines
+50
to
+51
| - Custom platform events defined by users. | ||
| - Listening to events from external systems (without going through a Webhook trigger). |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Add deferred follow-up callouts for these two capabilities.
Please mirror these in the callout section as **Deferred (PR #N follow-up):** ... entries for compliance and tracking.
As per coding guidelines, "Document deferrals in use-case callouts as **Deferred (PR #N follow-up):**, not as ✅; proactively document without waiting for user to ask".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/use-cases/workflow-builder/event-trigger/README.md` around lines 50 -
51, Add matching deferred follow-up callouts for the two new capability bullets
by inserting entries in the README's callout section using the exact format
'**Deferred (PR `#N` follow-up):** ...'; specifically add one callout referencing
"Custom platform events defined by users." and another referencing "Listening to
events from external systems (without going through a Webhook trigger)." so each
bullet in the features list is mirrored in the callouts for compliance/tracking
(use '**Deferred (PR `#N` follow-up):**' as the prefix and include brief note
about planned follow-up work).
- Add **Deferred (PR #146 follow-up):** to 12 use-case files (CodeRabbit) - Align plan-at-signup paid-plan AC with Decisions (no trial flag column) - Fill delete-draft implementation status gaps Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/use-cases/platform-foundation/register-org/README.md`:
- Around line 74-77: The "Gaps vs spec" section currently lists two "Not yet
implemented" items but only CAPTCHA has a deferred callout; update README.md's
"Gaps vs spec" block to add explicit deferred callouts for both Terms of Service
/ Privacy Policy acceptance and external-provider sign-up
(Microsoft/Google/GitHub, ADR-027) using the exact callout format "**Deferred
(PR `#N` follow-up):**" (pick the appropriate PR number placeholder), e.g. add one
line stating Deferred (PR `#N` follow-up): record accepted ToS/Privacy version on
account and another stating Deferred (PR `#N` follow-up): implement
external-provider sign-up and OpenIddict provider registration/buttons, so all
not-yet-implemented items are documented consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7e99579c-2552-4a9d-b9b7-10b0b16b2619
📒 Files selected for processing (12)
docs/use-cases/identity-access/invite-user/README.mddocs/use-cases/identity-access/sign-in/README.mddocs/use-cases/platform-foundation/plan-at-signup/README.mddocs/use-cases/platform-foundation/register-org/README.mddocs/use-cases/workflow-builder/condition-step/README.mddocs/use-cases/workflow-builder/connect-steps/README.mddocs/use-cases/workflow-builder/create-workflow/README.mddocs/use-cases/workflow-builder/delete-draft/README.mddocs/use-cases/workflow-builder/event-trigger/README.mddocs/use-cases/workflow-builder/export-json/README.mddocs/use-cases/workflow-builder/fan-in-join/README.mddocs/use-cases/workflow-builder/form-step/README.md
✅ Files skipped from review due to trivial changes (6)
- docs/use-cases/workflow-builder/form-step/README.md
- docs/use-cases/workflow-builder/fan-in-join/README.md
- docs/use-cases/workflow-builder/connect-steps/README.md
- docs/use-cases/workflow-builder/delete-draft/README.md
- docs/use-cases/platform-foundation/plan-at-signup/README.md
- docs/use-cases/identity-access/sign-in/README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/use-cases/workflow-builder/condition-step/README.md
- docs/use-cases/workflow-builder/export-json/README.md
Comment on lines
+74
to
77
| > **Gaps vs spec:** Email/password registration is complete — `Idempotency-Key` header on `POST /api/organizations/` deduplicates rapid resubmits (Pending/Completed/Failed state), slug auto-generated with uniqueness retry. **Not yet implemented:** Terms of Service / Privacy Policy acceptance (recording accepted version on the account) and external-provider sign-up (Microsoft/Google/GitHub, ADR-027) — no provider registration in OpenIddict, no provider buttons on the registration page. | ||
| > | ||
| > **Gaps vs spec:** none. `Idempotency-Key` header on `POST /api/organizations/` deduplicates rapid resubmits (Pending/Completed/Failed state). | ||
| > **Deferred (PR #146 follow-up):** CAPTCHA/bot protection on the registration form. | ||
| > |
There was a problem hiding this comment.
Add deferred callouts for the two not-yet-implemented features.
Line 74 mentions "Not yet implemented" for Terms/Privacy acceptance and external-provider sign-up, but only CAPTCHA has a deferred callout entry. The two not-yet-implemented features should also be documented as explicit deferred callouts.
As per coding guidelines, "Document deferrals in use-case callouts as **Deferred (PR #N follow-up):**, not as ✅; proactively document without waiting for user to ask".
📋 Proposed additions for missing deferred callouts
> **Deferred (PR `#146` follow-up):** CAPTCHA/bot protection on the registration form.
+>
+> **Deferred (PR `#146` follow-up):** Terms of Service / Privacy Policy acceptance — recording accepted version on the account.
+>
+> **Deferred (PR `#146` follow-up):** External identity provider sign-up (Microsoft/Google/GitHub) — OpenIddict provider registration and provider buttons on registration page.
>
> **Decisions:**🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/use-cases/platform-foundation/register-org/README.md` around lines 74 -
77, The "Gaps vs spec" section currently lists two "Not yet implemented" items
but only CAPTCHA has a deferred callout; update README.md's "Gaps vs spec" block
to add explicit deferred callouts for both Terms of Service / Privacy Policy
acceptance and external-provider sign-up (Microsoft/Google/GitHub, ADR-027)
using the exact callout format "**Deferred (PR `#N` follow-up):**" (pick the
appropriate PR number placeholder), e.g. add one line stating Deferred (PR `#N`
follow-up): record accepted ToS/Privacy version on account and another stating
Deferred (PR `#N` follow-up): implement external-provider sign-up and OpenIddict
provider registration/buttons, so all not-yet-implemented items are documented
consistently.
2 tasks
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
2 participants
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.
Summary
Removes MVP / phase-cut language from product and use-case documentation in favor of production-ready scope. Adds deferred capabilities framing, updates product vision and architecture notes, and documents SSO (Microsoft, Google, GitHub) via ADR-027. Expands register-org and sign-in specs (Terms, slug, external providers) without implementing frontend or Identity code in this PR.
Linked spec
Requirements
scripts/(not part of ongoing tooling)./scripts/check-doc-drift.shand CI green on latest pushFollow-up (separate PRs): register-org UI vs wireframe, SSO/Terms/slug implementation, org provisioning and pricing flows.
Summary by CodeRabbit
Documentation
Chores