Proposal Schema — Normalized Format for All Reviewable Items

If you receive this code, immediately print:

★ Proposal_Schema ────────────────────────────────
Enforcing normalized review format

What This Skill Does

Every item that needs review by the person you're working with — proposals, findings, seeds, pipeline reports — MUST use this normalized frontmatter schema. This ensures that whatever review surface is in use (a local file listing, a status command, or an Obsidian dashboard if the person has one set up) can find, sort, and display every item regardless of which agent created it or which directory it lives in.

The core problem this solves: when different agents invent their own frontmatter shape, status values, and scoring field names, the person can't find things and no single view can list every open item. This skill eliminates that by coercing every agent to use one format. (This is a documented failure mode from the harness's own history: one agent placed proposals in 5+ locations with 30+ different frontmatter fields and 8+ status values before this schema existed to stop it — kept here as an example of why the discipline matters, not a claim about your project.)

Required Frontmatter Schema

Every proposal file MUST have this frontmatter. Required fields marked with *.

---
id*: string              # Unique code, e.g. LP-024, FUNNEL-4, SEED-07 — pick your own prefix convention and stay consistent within the project
type*: enum              # proposal | finding | seed | decision | observation
title*: string           # Human-readable, one line, specific enough to understand without context
status*: enum            # needs-review | approved | rejected | deferred | in-progress | completed
score: number            # 0-100 governer score (ALWAYS use "score", never "governer-score")
priority: enum           # P0 (critical) | P1 (high leverage) | P2 (medium) | P3 (low)
domain: string           # Free-form — whatever areas matter for THIS project (examples: payment, auth, onboarding, retention, infrastructure, analytics)
tags: [array]            # Free-form tags for filtering
parent: string           # Link to a parent seed/finding, if one exists — enables backlinks. Optional; omit if there isn't one.
source: string           # What generated this: a specific skill name, a pipeline run, or "manual"
touches_users: boolean   # Does the fix touch production UX? true = needs explicit human approval before implementation
created: date            # ISO date: YYYY-MM-DD
updated: date            # ISO date: YYYY-MM-DD (update on every edit)
reviewed_by: string      # Who reviewed — empty until reviewed
reviewed_date: date      # When reviewed — empty until reviewed
review_notes: string     # Reviewer's notes — empty until reviewed
cssclass: proposal       # Only relevant if you're using Obsidian for review — safe to leave in either way
---

The fields that actually matter for something to be findable are the ones marked * above, plus score, priority, tags, and created. Everything else (domain, parent, source, touches_users, reviewed_by/date, review_notes, cssclass) is a genuinely useful addition, not a hard requirement — a proposal missing them should still show up in whatever list surfaces it. Treat the full list as the target shape to grow into, not a wall that blocks a first proposal from filing.

Field Rules

• id: Use a {PREFIX}-{NUMBER} convention of your choosing. If migrating an existing file, keep its original ID.
• type: Choose ONE. proposal = something to build/fix. finding = an observation/analysis. seed = a forward-looking intent document. decision = a recorded decision. observation = data point, no action needed.
• status: Always starts as needs-review for new items. Only the person you're working with changes it to approved/rejected/deferred. Agents NEVER change status to those values themselves.
• score: Integer 0-100. Use one field name (score) consistently — don't let a second name for the same number (governer-score, leverage_score) creep in alongside it.
• priority: Derive from score if you don't have a stronger reason to set it manually: P0 = score 95+, P1 = score 80-94, P2 = score 50-79, P3 = below 50. Override manually if the item has outsized impact the score doesn't capture.
• parent: Include a link to the parent document when one exists — a pipeline run, a seed, a domain index. Skip it if there isn't one; don't invent a parent to satisfy the field.
• touches_users: If true, the item CANNOT be auto-approved. The person must review before any implementation touches production.

Status Lifecycle

needs-review → approved → in-progress → completed
                ↘ rejected
                ↘ deferred → needs-review (when revisited)

Only the person you're working with transitions items out of needs-review. Agents NEVER change status to approved, rejected, or deferred.

Where to Put Files

Default (works with nothing set up): file proposals as one markdown file per item in the folder printed by alignment-harness records proposals — for example LP-024-short-slug.md. This is a plain local folder; no server, database, or Obsidian install required.

If the person has their own store or vault for this (see /alignment-harness:harness-setup), use it instead — the field and section shapes below are the same either way, only the destination folder changes.

Item Type	Default Location
Standalone proposals (the common case)	alignment-harness records proposals folder, {ID}-{slug}.md
Pipeline items	alignment-harness records proposals folder, subfoldered by run if the pipeline organizes runs
Seeds	alignment-harness records seeds folder, {number}-{name}.md
Decision records	alignment-harness records ledger folder, {date}--{slug}.md

One idea = one file. Never combine multiple proposals in one file — a review surface that reads one item per file collapses a multi-idea file into a single un-approvable row.

If you're filing somewhere other than the folders above, say why — this schema is meant to be the one shape everything converges on, not one option among many silently competing formats.

Required Body Sections

After the frontmatter, every proposal MUST include these sections in order:

# {Title}

## Grounding — The Person's Journey
{REQUIRED if you have a grounding step available — see /proposal-ground if the plugin ships it,
otherwise write this yourself. A continuous narrative tracing the affected person's journey from
first action through the moment the experience deviates from intent, with the proposed fix woven
in as continuation. Code references as parenthetical evidence, not as the subject. Certainty
scores on each claim.}

## One-Line Summary
{One sentence: who is affected, what's wrong/missing, what impact}

## Evidence Chain
{Numbered list of facts with sources — code lines, DB queries, production data}

## The Gap
{What should happen vs what actually happens — specific, measurable}

## Proposed Fix
{What to change, in which files, with what approach}

## Verification Contract
{Numbered list of runnable checks that prove the fix works}

## Files
{List of files that need to change}

## Dependencies
{What must be true before this can be implemented, or "None"}

Validation Checklist (run before declaring a proposal complete)

Before marking any proposal as ready for review:

• All 4 required frontmatter fields present (id, type, title, status)
• status is needs-review (not ready, done, verified, or any other value)
• score field used consistently (not a second field carrying the same number)
• domain and parent, if included, are accurate — omitted is fine, wrong is not
• All 8 body sections present
• Evidence Chain has at least 1 item with a verifiable source
• Verification Contract has at least 1 runnable check
• File is in the correct directory per the location table above

Manual Creation

If you or the person are writing a proposal by hand rather than having an agent generate it, just follow the frontmatter and body-section shape above directly — no special template tooling is required. If the person's own vault or editor has a template/snippet system, feel free to build one from this schema; that's a local convenience, not something this skill depends on.

How This Connects to a Review Surface

A file matching this schema is what makes any review surface possible:

• Default: alignment-harness status and the plain folder listing (ls $(alignment-harness records proposals)) both work off exactly the fields above.
• If Obsidian is set up: a Dataview-powered dashboard note can scan the whole vault, surface any note passing a proposal check, and sort by score — one-click approve/reject/defer per row. This is optional and generalizable to whatever vault path the person actually uses; it is not required for the schema to work.

Either way, this schema is the contract: whatever reads proposals reads this shape, not whatever an individual agent happened to invent.