pal-e-docs
Note not found.

Convention: Cross-Pillar Triggers

convention-cross-pillar-triggers Convention

active convention
Project

Convention: Cross-Pillar Triggers

When a merge to one pillar's repo changes how agents or processes work, the affected pillar must review its artifacts. This convention defines the feedback loops that keep the three-pillar operating model (Platform, Docs, Agency) in sync.

The Problem

The three-pillar architecture (Platform, Docs, Agency) has static relationships: Agency DEFINES the process AND ENFORCES the rules, Platform PROVES the DORA numbers, Docs TRACKS the value stream. But these relationships are one-directional in the current architecture diagram. There is no reverse arrow — no mechanism for a platform change to trigger an agency review, or a docs change to trigger an agency update.
Without feedback loops, the operating model drifts from reality every time infrastructure ships a change that affects how agents work. Today this is caught manually (Lucas notices). That doesn't scale.

The Trigger Matrix

Source Pillar Merge Changes... Target Pillar Review What Example
<strong>Platform</strong> CI/CD pipeline, deploy behavior, infra topology <strong>Agency</strong> SOPs, agent-workflow state machine, autonomy levels Apply-on-merge changes what "deployed" means → agent-workflow needs deployed/deploy-failed states
<strong>Platform</strong> Observability stack, alerting rules <strong>Agency</strong> Recovery SOPs, escalation triggers New PrometheusRule adds OOMKilled alert → sop-deploy-recovery should reference it
<strong>Docs</strong> API schema, note types, block structure <strong>Agency</strong> Conventions, templates, MCP tool docs New note_type added → note-conventions must include it, templates may need updating
<strong>Agency</strong> Workflow changes, new agent types <strong>Platform</strong> CI pipeline scope, monitoring targets New agent type added → may need Woodpecker secrets, monitoring

Implementation (Progressive)

Three maturity levels, implemented incrementally:

Level 1: Convention (Today)

Add to sop-post-merge-docs checklist:
  • "Cross-pillar impact check" — If this PR changes agent-facing behavior (CI pipeline, hooks, enforcement, API schema), create a TODO note tagged todo,open for the target pillar's SOP review. Reference the merged PR.
This is manual but captures the pattern. Ava is responsible for the check during /update-docs.

Level 2: Woodpecker Trigger (Next)

Add a pipeline step to CI-enabled repos:
  • On merge to main, if changed files match trigger patterns (e.g., .woodpecker*, ci/*, hooks/*), auto-create a Forgejo issue in the target pillar's repo
  • Issue title: "[Cross-Pillar Review] {source-repo} PR #{N} — {title}"
  • Issue body: link to the merged PR, list of changed files that triggered the review, suggested SOPs/conventions to check
This requires Forgejo API credentials in Woodpecker secrets and file-pattern matching logic.

Level 3: Automated Audit (Future)

  • Scheduled Dottie audit: weekly scan of merged PRs across all repos, cross-referenced against SOP last-updated timestamps
  • Drift detection: if a platform repo has merged 5 PRs since the last agency SOP update, flag it
  • This is the DORA-aligned maturity endpoint: the operating model self-heals

File Pattern Triggers

For Level 2 implementation, these file patterns signal cross-pillar impact:
Repo Pattern Target Pillar Why
pal-e-platform <code>.woodpecker*</code> Agency CI pipeline behavior change
pal-e-platform <code>terraform/modules/*/main.tf</code> Agency New infra module may need onboarding SOP
claude-custom <code>hooks/*</code> Agency (internal) Enforcement rule change (internal to Agency)
claude-custom <code>agents/*</code> Agency (internal) Agent definition change (internal to Agency)
pal-e-docs <code>src/*/models.py</code> Agency Schema change may affect conventions
pal-e-docs <code>src/*/routes/*.py</code> Agency API change may affect MCP tools and conventions

The Feedback Arrow

This convention adds the missing arrows to the three-pillar diagram:
The TRIGGERS arrow closes the loop: when Platform ships a change, Agency reviews whether the process still matches the reality. Convention-to-hook feedback (e.g., new SOP → hook should enforce X) is an internal Agency concern, not a cross-pillar trigger. Without the TRIGGERS arrow, every platform improvement is a potential SOP drift.
  • project-pal-e-agency — architecture section (three-pillar diagram with feedback arrows)
  • sop-post-merge-docs — Level 1 implementation lives here as a checklist item
  • convention-apply-before-merge — the first convention created by this pattern
  • agent-workflow — the operating model that cross-pillar triggers keep in sync
  • phase-pal-e-agency-9-ci-driven-operating-model — parent phase
  • dora-framework — DORA metrics that prove the feedback loop is working