Governance
Steering documents are only as useful as they are accurate. A document that reflects how the org worked eighteen months ago is not neutral — it actively steers the agent in the wrong direction.
Two Modes, Not One
Governance fails when it relies on a single mode. A scheduled cadence alone misses the events that matter most — major architectural decisions, new technology adoptions, post-incident findings. These don't wait for the next quarterly review to invalidate a steering document. Ad-hoc-only governance is equally fragile: reactive by design, it only triggers when something visibly goes wrong.
ProductHarness governance uses three inputs: scheduled cadence, event-driven reviews, and AI-generated feedback. The scheduled cadence is the meeting. The event-driven triggers and AI feedback are the agenda items.
Scheduled Cadence
Proactive reviews on a fixed schedule, regardless of whether anyone believes something has changed. The schedule creates the forcing function. It surfaces drift that accumulates gradually — the kind that would never trigger an ad-hoc review because no single event caused it.
Event-Driven Reviews
Triggered by specific events that almost certainly invalidate one or more steering documents: a new auth provider, a post-incident finding, a production codebase refactor. Time-sensitive — waiting for the next scheduled review means the agent operates on stale standards in the interim.
AI-Generated Feedback
The agent monitors commit history and surfaces signals that steering documents may be drifting from actual practice — before a formal review is scheduled and before the drift causes visible problems. Makes governance proactive without requiring manual effort.
Who Owns What
Different files carry different risk when they drift, and different stakeholders have the context to keep them accurate. Ownership is by role, not by person — when someone changes roles or leaves, ownership reassigns with the role. Every file has one owner and one approver; files that cross domains require joint sign-off.
| File | Owner | Approver | Notes |
|---|---|---|---|
| steering/standards/infrastructure.md | Staff / Principal Engineer | Engineering leadership | Changes when IaC tooling or patterns change |
| steering/standards/database.md | Staff / Principal Engineer | Engineering leadership | Changes when DB decisions or ORM changes |
| steering/standards/cicd.md | Staff / Principal Engineer | Engineering leadership | Changes when pipeline structure or gates change |
| steering/standards/authentication.md | Staff / Principal Engineer | Engineering leadership | Changes when auth provider or patterns change |
| steering/standards/api.md | Staff / Principal Engineer | Engineering leadership | Changes when API conventions evolve |
| steering/standards/security.md | Security lead or Staff Engineer | Engineering leadership + Legal/Compliance | Legal review may be required; changes with compliance requirements |
| steering/standards/testing.md | QA lead or Staff Engineer | Engineering leadership | Changes when coverage thresholds or tooling change |
| steering/loops/ (all) | Director of Product | Director of Product + Engineering lead | Joint sign-off required — node definitions cross both domains |
| steering/templates/ (delivery) | Director of Product | Director of Product | PM-facing; engineering should review for technical accuracy |
| steering/templates/discovery/ | Senior PM or Director of Product | Director of Product | Evolves as discovery practice matures |
| steering/production-patterns.md | Engineering lead | Engineering lead + Design system owner | Most volatile file when production codebase is actively evolving |
| engineering-handoff-checklist.md | Director of Product | Director of Product + Engineering lead | Joint — PM produces, Engineering consumes |
| PRODUCTHARNESSTEMPLATE.md | ProductHarness owner (Director-level PM) | Director of Product | The master context file; changes when the harness itself evolves |
| docs/technical/stack-context.md | Engineering lead | Engineering lead | Refreshed when production stack changes |
Every org should designate one person as the internal ProductHarness owner — responsible for applying updates when a new version of the ProductHarness Specification is released — the org's agent applies the changes to the org's own harness repo — coordinating governance reviews, and communicating changes to the team. This is a defined accountability, not a full-time role.
How Often Each File Should Be Reviewed
Cadence should match how often the underlying reality changes. A file governing IaC patterns for a team adopting new tooling needs quarterly review. A file defining discovery templates for a stable, mature practice can wait a year. Applying the same cadence to everything is either too frequent (governance overhead with no value) or too infrequent (drift goes unnoticed).
These files are tied directly to engineering decisions that change frequently. A stale standard here means the agent generates code that engineering will reject or modify on every PR. Review quarterly as a minimum; increase frequency if the production codebase is actively evolving.
Files: steering/standards/infrastructure.md, steering/standards/cicd.md, steering/standards/security.md, steering/production-patterns.md (monthly if active), docs/technical/stack-context.md
These files evolve as team practices mature but are less tightly coupled to specific technical decisions. Drift here produces lower-quality PM artifacts and inconsistent handoffs rather than outright rejected code — easier to miss, but still meaningful.
Files: steering/standards/database.md, steering/standards/authentication.md, steering/standards/api.md, steering/standards/testing.md, steering/templates/ (delivery), engineering-handoff-checklist.md
These files define the structure and philosophy of the harness. They change rarely, but must be reviewed whenever a new version of the ProductHarness Specification is released — applying spec changes to the org's harness repo may introduce conflicts with the org's customizations.
Files: steering/loops/ (all node definition files), steering/templates/discovery/, PRODUCTHARNESSTEMPLATE.md
Events That Require Immediate Review
These events should initiate an immediate review of the relevant files — do not wait for the next scheduled cadence. The scheduled cadence does not replace event-driven triggers. In most cases, the event makes the standard actively wrong from the moment it happens.
| Event | Files to Review |
|---|---|
| New technology adopted (new framework, new IaC tool, new DB) | Relevant steering/standards/ file |
| Major architectural decision made | Relevant standards files; possibly steering/loops/delivery/1-implementation.md |
| Auth provider or auth pattern change | steering/standards/authentication.md |
| New compliance or security requirement | steering/standards/security.md; possibly steering/loops/delivery/4-deploy.md |
| Post-incident or post-mortem finding | Relevant node file; engineering-handoff-checklist.md if handoff was implicated |
| Production codebase refactor or design system update | steering/production-patterns.md; docs/technical/stack-context.md |
| Upstream harness update pulled from ProductHarness Template | PRODUCTHARNESSTEMPLATE.md; compare all steering files for conflicts with org customizations |
| New PM joins the team | steering/templates/ — fresh eyes reliably surface gaps the existing team can no longer see |
| Engineering team restructure or new engineering lead | steering/standards/ ownership reassignment; review for gaps in coverage |
| Major product pivot or new product line | steering/loops/; steering/templates/discovery/ |
| CI/CD pipeline change | steering/standards/cicd.md |
The Governance Health Report
The harness is self-monitoring. The agent can analyze commit history and surface patterns that indicate steering documents are drifting from actual practice — before a formal review is scheduled and before the drift causes visible problems.
On a defined schedule — recommended monthly for active teams, quarterly for stable ones — the ProductHarness owner prompts the agent to generate a Governance Health Report. The report replaces "does anyone think something needs to change?" with a data-driven agenda for the governance review meeting.
The four categories in the report: cadence status (which files are overdue based on last-modified date and cadence rules), drift signals (commit patterns over the review period that suggest a steering document may not reflect current practice — each signal identifies the file, the pattern, and example commits), usage signals (templates with low or zero usage; discovery artifacts not appearing for initiatives above a defined scale), and recommended actions (a ranked list of files to review, ownership to clarify, and potential gaps to investigate).
The report also runs an archive-hygiene check on the working set — the backstop that keeps a long-lived repo navigable. It flags features still marked status: active whose delivery work has already merged (they should have been archived to docs/_shipped/ at the Impact node), and docs/work/<feature>/ folders with no commits in the review window (stalled or forgotten). Structure makes archiving easy; this check catches what slips through.
The Governance Health Report is the primary input to the quarterly governance review meeting. It makes the meeting productive rather than speculative.
Review commit history for the past [30/90] days across this repo and any connected production repos.
Generate a Governance Health Report covering:
1. Which steering files are overdue for review based on their cadence (quarterly/semi-annual/annual)
2. Commit patterns that suggest any steering document may be drifting from actual practice
3. Templates with low or zero usage in docs/
4. Recommended review actions in priority order
Format the output as a structured report suitable for a governance review meeting.Common Governance Failure Modes
These are the patterns that cause governance to fail quietly — not with an obvious incident, but with gradual drift that compounds until generated outputs are consistently wrong and the team doesn't know why.
This almost always means no one looked. Gradual drift accumulates without any single event triggering a review. The Governance Health Report is the counter — commit history doesn't lie about what the codebase is actually doing, even when the team believes nothing has changed.
When the Staff Engineer who owns authentication.md leaves, the standard becomes ownerless. Ownership should be a role, not a person. Track ownership in the responsibility matrix and reassign on offboarding — before the next review cycle, not after the next incident.
If the quarterly review meeting produces no changes quarter after quarter, the team has stopped looking honestly. Stable orgs still change tools, adopt new patterns, and grow their teams. Some file should almost always need an update. A review that finds nothing is usually a review that didn't look hard enough.
A steering document that is 80% accurate is far more useful than a standard that isn't documented because the team couldn't agree on every edge case. Document the decision; refine as reality demands. The alternative — no documented standard — means the agent generates from general knowledge instead of your org's decisions.
The scheduled cadence does not replace event-driven triggers. Adopting a new IaC tool without updating infrastructure.md immediately means the agent operates on the wrong standard from day one of the new pattern — not from the next quarterly review. The gap between the event and the standard update is a window where every generated output is wrong.
When a standard changes, engineering should be notified promptly — not just because the document updated, but because they will immediately see different behavior from the agent. A changed authentication pattern or error response format will show up in the next generated service, in the next PR. Engineering leadership may need to communicate separately so engineers understand why the agent is doing something different.