docs: refresh active documentation by aaight · Pull Request #1277 · mongrel-intelligence/cascade

aaight · 2026-05-09T08:25:20Z

Summary

Refreshes active CASCADE documentation against the current source of truth.

Card: https://trello.com/c/69feeabdd0108e5d166b7f51

Changes

Added documentation drift guards in tests/unit/architecture-docs.test.ts for active Markdown links, .md.done spec links, canonical alerting:issue-alert, current cascade-tools namespaces, stale work_items wording, and CLAUDE.md/AGENTS.md synchronization.
Updated quick-start and setup docs for current webhook behavior, alerting trigger names, alerts PM slot setup, .cascade/ensure-services.sh, and current cascade-tools command examples.
Refreshed architecture, integration, database, resilience, gadget, and testing docs for PM manifests, single integration entrypoint, pr_work_items alert materialization, deferred re-checks, dispatch retry/lock compensation, worker crash diagnostics, and D2 source coverage for Linear/Sentry.
Repaired broken active-doc links to archived .md.done specs.

Notes

docs/architecture.d2 was updated to include Linear and Sentry. Generated docs/architecture.svg and docs/architecture.jpg were not regenerated because the d2 renderer is not installed in this environment.
npm run lint exits successfully but still reports two pre-existing Biome complexity warnings in Sentry alerting runtime files unrelated to this documentation change.

Verification

npx vitest run --project unit-core tests/unit/architecture-docs.test.ts
npx vitest run --project unit-core tests/unit/agents/prompts.test.ts --project unit-triggers tests/unit/triggers/trigger-event-consistency.test.ts
npm run lint:fix
npm run lint
npm run typecheck
npm test

🕵️ codex · gpt-5.5 · run details

nhopeatall

Summary

Requesting changes because the active README still renders stale generated architecture assets: the D2 source includes Linear/Sentry, but the generated diagram assets were not regenerated.

Code Issues

Should Fix

docs/architecture.d2:18 — The visible architecture diagram remains stale. README embeds docs/architecture.jpg, and the generated SVG/JPG do not include the newly added Linear/Sentry nodes. Updating only the D2 source means users still see the old diagram in the README.

🕵️ codex · gpt-5.5 · run details

nhopeatall · 2026-05-09T08:34:21Z

 PM: {
  trello
  jira
+  linear


Adding Linear/Sentry to the D2 source is not enough while the generated assets stay stale: README.md embeds docs/architecture.jpg, and docs/architecture.svg still has no linear/sentry labels. Please regenerate the generated diagram assets or stop embedding the stale image in active docs before merging this documentation refresh.

Fixed. Since the d2 renderer is not available in this environment, I've taken the alternative approach you suggested: removed the stale <img src="docs/architecture.jpg"> embed from README.md and replaced it with a prose note that points readers to docs/architecture.d2 and the D2 CLI render command. The README no longer surfaces a diagram that contradicts the updated D2 source.

Fixed. The Post-spec-011 table row now says the WebhookStep "was retained temporarily" and "was fully migrated into the manifest path in spec 012 (see Post-spec-012 additions below)" — removing the contradictory "remains for now / follow-up scope" language.

Replace the embedded docs/architecture.jpg (stale — missing Linear/Sentry nodes) with a prose note pointing readers to the D2 source and the d2 CLI render command, so the README no longer surfaces a diagram that contradicts the updated docs/architecture.d2. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

nhopeatall

Summary

Requesting changes because one active integration guide section still documents the pre-spec-012 webhook migration state.

Code Issues

Should Fix

src/integrations/README.md:195 — This row still says the legacy WebhookStep remains and that migration into the manifest path is follow-up scope. That is now false: the same README says spec 012 deleted WebhookStep/LinearWebhookInfoPanel and that every PM wizard step renders through the manifest path, and current web/src/components/projects/pm-wizard.tsx confirms the legacy webhook slot is gone. This was also an explicit work-item requirement (remove the stale “WebhookStep remains” statement), so the active docs remain internally contradictory.

🕵️ codex · gpt-5.5 · run details

The Post-spec-011 integration guide row said "The legacy WebhookStep remains … migration into the manifest path is follow-up scope." Spec 012 completed that migration (WebhookStep deleted, every PM wizard step now renders via the manifest path), making the statement both false and internally contradictory with the Post-spec-012 section immediately below it. Update the row to reflect that WebhookStep was temporarily retained during spec 011 and fully migrated in spec 012. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

codecov · 2026-05-09T08:52:57Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

nhopeatall

Summary

Requesting changes because two refreshed architecture sections still describe runtime contracts incorrectly.

Code Issues

Should Fix

docs/architecture/03-trigger-system.md:60 — The TriggerResult code block still documents waitForChecks?: boolean, but the actual type in src/types/index.ts no longer has that field and the GitHub webhook code documents that worker-side wait-for-checks polling was removed.
docs/architecture/01-services.md:98 — mergeabilityRecheckAttempt is documented on the JOB_TYPE row, but the router serializes it into the GitHub job object inside JOB_DATA and the worker reads jobData.mergeabilityRecheckAttempt after parsing JOB_DATA.

Verification: npx vitest run --project unit-core tests/unit/architecture-docs.test.ts passes.

🕵️ codex · gpt-5.5 · run details

nhopeatall · 2026-05-09T08:57:53Z

  prTitle?: string;
  waitForChecks?: boolean;         // Poll CI before starting
  onBlocked?: () => void;          // Cleanup if job can't be enqueued
+  deferredRecheck?: {


Since this interface block is being refreshed for deferred re-checks, it also needs to drop the stale waitForChecks?: boolean line above. The actual TriggerResult in src/types/index.ts no longer has that field, and the GitHub webhook path explicitly documents that worker-side waitForChecks polling was removed.

Fixed. Removed the stale waitForChecks?: boolean line from the TriggerResult code block — the field no longer exists in src/types/index.ts. The block now correctly shows only the fields that are actually present in the type.

nhopeatall · 2026-05-09T08:57:53Z

 |----------|---------|
 | `JOB_ID` | Unique job identifier |
-| `JOB_TYPE` | `trello`, `github`, `jira`, `linear`, `sentry`, `manual-run`, `retry-run`, `debug-analysis` |
+| `JOB_TYPE` | `trello`, `github`, `jira`, `linear`, `sentry`, `manual-run`, `retry-run`, `debug-analysis`; GitHub jobs may also carry `mergeabilityRecheckAttempt` for deferred re-checks |


mergeabilityRecheckAttempt is not part of JOB_TYPE; the router serializes it into the GitHub job object and passes it through JOB_DATA, then the worker reads jobData.mergeabilityRecheckAttempt. Keeping it on the JOB_TYPE row makes the worker env contract look different from the source.

Fixed. Moved the mergeabilityRecheckAttempt mention from the JOB_TYPE row to the JOB_DATA row in the environment-variable table. The router serializes it into the GitHub job object (confirmed in src/router/queue.ts and src/worker-entry.ts), so it lives in the JSON-encoded JOB_DATA payload, not in the job-type discriminator string.

- Remove `waitForChecks?: boolean` from the TriggerResult code block in 03-trigger-system.md; the field no longer exists in src/types/index.ts - Move `mergeabilityRecheckAttempt` mention from the JOB_TYPE row to the JOB_DATA row in 01-services.md; the router serializes it into the GitHub job object inside JOB_DATA, not as part of the job type string Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

nhopeatall

LGTM - the refreshed active docs now match the source-of-truth paths I checked, the previous review issues are resolved, and the architecture docs guard passes locally.

🕵️ codex · gpt-5.5 · run details

docs: refresh active documentation

e1ae9ba

nhopeatall requested changes May 9, 2026

View reviewed changes

nhopeatall approved these changes May 9, 2026

View reviewed changes

aaight merged commit b5d28ce into dev May 9, 2026
9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: refresh active documentation#1277

docs: refresh active documentation#1277
aaight merged 4 commits into
devfrom
docs/refresh-active-documentation

aaight commented May 9, 2026

Uh oh!

nhopeatall left a comment

Uh oh!

nhopeatall May 9, 2026

Uh oh!

aaight May 9, 2026

Uh oh!

aaight May 9, 2026

Uh oh!

nhopeatall left a comment

Uh oh!

codecov Bot commented May 9, 2026

Uh oh!

nhopeatall left a comment

Uh oh!

nhopeatall May 9, 2026

Uh oh!

aaight May 9, 2026

Uh oh!

nhopeatall May 9, 2026

Uh oh!

aaight May 9, 2026

Uh oh!

nhopeatall left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

aaight commented May 9, 2026

Summary

Changes

Notes

Verification

Uh oh!

nhopeatall left a comment

Choose a reason for hiding this comment

Summary

Code Issues

Should Fix

Uh oh!

nhopeatall May 9, 2026

Choose a reason for hiding this comment

Uh oh!

aaight May 9, 2026

Choose a reason for hiding this comment

Uh oh!

aaight May 9, 2026

Choose a reason for hiding this comment

Uh oh!

nhopeatall left a comment

Choose a reason for hiding this comment

Summary

Code Issues

Should Fix

Uh oh!

codecov Bot commented May 9, 2026

Codecov Report

Uh oh!

nhopeatall left a comment

Choose a reason for hiding this comment

Summary

Code Issues

Should Fix

Uh oh!

nhopeatall May 9, 2026

Choose a reason for hiding this comment

Uh oh!

aaight May 9, 2026

Choose a reason for hiding this comment

Uh oh!

nhopeatall May 9, 2026

Choose a reason for hiding this comment

Uh oh!

aaight May 9, 2026

Choose a reason for hiding this comment

Uh oh!

nhopeatall left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants