docs(governance): propose forensic output conventions (produced_by + process_breakpoint)

[jordyamoedo]

Summary

This proposes two small forensic output conventions — submitted through the project's own governance/evolution-pipeline.md as an AuditFinding + FrameworkProposal (both PENDING your approval). Two governance YAML files; no code paths touched.

The gap

The framework has an evolution pipeline that wants to know who/which model produced an artifact and which findings recur — but there's no mechanism that captures either. Today:

• agent-produced artifacts (stories, gates, reports) carry no authorship metadata, and
• failed gates record the symptom, not where in the process the error was born — so the same root cause gets re-patched at the symptom.

The proposal

Two additive, advisory-by-default conventions:

1. produced_by — every agent-generated artifact carries produced_by: { agent, model, date } in its frontmatter. Forensic provenance.
2. process_breakpoint — every gate with a non-PASS verdict tags, per issue, where the error was born (incomplete story? context-less handoff? unvalidated input? environment?). Closing principle: fix the process, not the symptom.

Why it's good for the project

• It directly feeds the framework's own evolution pipeline: produced_by is the provenance the pipeline needs (input to model-tiering / validation sampling), and process_breakpoint surfaces the recurring failure points that become promotion candidates.
• The predicate is presence-of-a-frontmatter-field — 100% machine-checkable, no judgement, so it mechanizes cleanly as advisory.
• Additive and low-risk — no existing behavior changes; both conventions are report-only by default.
• Battle-tested in a production consumer fork, then generalized here (no project-specific content).

Submitted in the spirit of the framework's own evolution pipeline. Happy to follow up with the implementation PR (.claude/rules/output-conventions.md + template frontmatter) once approved — or to adjust scope per your guidance.

Summary by CodeRabbit

• Documentation
  • Added audit findings identifying gaps in authorship and provenance tracking for generated artifacts.
  • Established governance proposal to implement metadata standards for tracking output creators and process steps, enabling enhanced traceability of generated content.

[vercel]

@jordyamoedo is attempting to deploy a commit to the SINKRA - AIOX Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Welcome to aiox-core! Thanks for your first pull request.

What happens next?

1. Automated checks will run on your PR
2. A maintainer will review your changes
3. Once approved, we'll merge your contribution!

PR Checklist:

• Tests pass (npm test)
• Linting passes (npm run lint)
• Commit messages follow Conventional Commits

Thanks for contributing!

[coderabbitai]

Walkthrough

Two new YAML documents are added: a promoted audit finding (AF-20260614-forensic-output-authorship) identifying missing authorship and process-step breakpoint metadata on agent-produced artifacts, and a governance proposal (PROP-20260614-forensic-output-authorship) formalizing produced_by and process_breakpoint as additive, report-only advisory conventions with an associated rule artifact target.

Changes

Forensic Output Authorship Audit and Governance Proposal

Layer / File(s)	Summary
Promoted audit finding audits/promoted/AF-20260614-forensic-output-authorship.yaml	Defines the promoted audit finding with context (anonymized consumer project, learning-loop audit), the finding that agent-produced artifacts and gate failures lack authorship/provenance and process-step breakpoint metadata, observed impact, framework-candidate rationale, and proposed disposition steps for produced_by frontmatter and process_breakpoint tagging.
Governance framework proposal governance/proposals/PROP-20260614-forensic-output-authorship.yaml	Defines the framework proposal linking back to the audit finding, specifying the rule artifact path, produced_by and process_breakpoint advisory convention details, additive/no-breaking-change migration plan, cost/benefit fields, and approval/implementation placeholders including PR URL and distributed_to.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

area: docs, area: core, area: workflows

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and concisely summarizes the main change: proposing forensic output conventions with produced_by and process_breakpoint metadata for governance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

governance/proposals/PROP-20260614-forensic-output-authorship.yaml (1)

14-28: ⚖️ Poor tradeoff

Specify the formal schema and data structure for produced_by and process_breakpoint conventions.

The generalization section describes the two conventions in prose, but lacks the formal schema that downstream adopters will need to implement consistently:

produced_by (lines 20-21): Shown as { agent, model, date } but missing:

• YAML field names and structure (is it produced_by: { agent: "...", model: "...", date: "..." }? Or produced_by: "agent@model:date"?)
• Data type constraints (are model and agent strings? enum values? Is date ISO 8601?)
• Required vs. optional fields (must all three be present, or only some?)
• An example frontmatter snippet

process_breakpoint (lines 22-24): Shown with parenthetical examples (incomplete story, context-less handoff, unvalidated input, environment) but missing:

• Enumerated allowed values (is this an open set, or a fixed enum?)
• Whether a single finding can have multiple breakpoints (array or scalar?)
• YAML format (string? array of strings? object?)
• Guidance on when to assign multiple vs. one value

Recommend adding a "Schema" subsection to generalization or deferring formal schema to the rule doc output-conventions.md. Without this, implementations risk inconsistent tagging.

🤖 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 `@governance/proposals/PROP-20260614-forensic-output-authorship.yaml` around
lines 14 - 28, The generalization section describes the produced_by and
process_breakpoint conventions in prose but lacks formal schema definitions
needed for implementation. Add a "Schema" subsection under generalization that
specifies for produced_by: the exact YAML field names, data types (e.g., whether
agent and model are strings or enums, whether date is ISO 8601), which fields
are required versus optional, and a concrete example showing the frontmatter
structure. For process_breakpoint, specify whether it is an enumerated set of
allowed values or an open set, whether it accepts a single value or an array of
multiple breakpoints, the exact YAML type and format, and explicit guidance on
when to assign one value versus multiple. This formal schema should enable
downstream adopters to implement the conventions consistently without ambiguity.

🤖 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.

Nitpick comments:
In `@governance/proposals/PROP-20260614-forensic-output-authorship.yaml`:
- Around line 14-28: The generalization section describes the produced_by and
process_breakpoint conventions in prose but lacks formal schema definitions
needed for implementation. Add a "Schema" subsection under generalization that
specifies for produced_by: the exact YAML field names, data types (e.g., whether
agent and model are strings or enums, whether date is ISO 8601), which fields
are required versus optional, and a concrete example showing the frontmatter
structure. For process_breakpoint, specify whether it is an enumerated set of
allowed values or an open set, whether it accepts a single value or an array of
multiple breakpoints, the exact YAML type and format, and explicit guidance on
when to assign one value versus multiple. This formal schema should enable
downstream adopters to implement the conventions consistently without ambiguity.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f4182d64-1d48-4285-9baa-51bdb5ee87e7

📥 Commits

Reviewing files that changed from the base of the PR and between 77265d5 and 1ed52c0.

📒 Files selected for processing (2)

• audits/promoted/AF-20260614-forensic-output-authorship.yaml
• governance/proposals/PROP-20260614-forensic-output-authorship.yaml