shared/conventions

Universal conventions

Conventions that apply to every petrova-line repo. Project-specific conventions live in each repo’s CLAUDE.md § “Conventions specific to this repo”.

1. Dates are absolute (MR-4).

ISO format (YYYY-MM-DD) in filenames and bodies. Decision docs: YYYY-MM-DD-<slug>.md. Findings: YYYYMMDD-HHMM-<slug>.md. Convert “Thursday” / “next week” / “yesterday” to ISO at write time. Relative dates rot.

2. Sibling files stay sibling (MR-3).

Paired files (e.g. forward-migration + rollback, two emitters in lockstep, request + response schemas) are not collapsed without a justifying decision doc. Merging conflates concerns and re-introduces drift the pair was created to prevent.

3. Direct push to main is OK for small fixes.

CSS tweaks, test patches, doc typos, single-file bug fixes. Use a PR when the change deserves a checkpoint — multi-file features, architectural shifts, anything that wants operator sanity-check before landing. PR ceremony for two-line fixes is exactly the friction the verification rounds flag as waste.

This convention can be overridden per-repo. Repos with branch protection (production-shape, multi-author) MUST use PRs; repos with permissive profile MAY use direct-push for the cases above. The repo’s registry.yaml profile (strict / standard / permissive) is the authority.

4. Verification round is mandatory at phase close (MR-10).

See phase-discipline.md rule 2. Restated here because it bites at every phase boundary and is the single most-skipped rule.

5. Subagent delegation reads AGENTS.xml (MR-6).

See agent-fleet-methodology.md rule 1. Restated because improvised delegation is the most common drift vector.

6. CLAUDE.md is a projection, not a source (MR-12).

Content in CLAUDE.md references material that lives in docs/north-star/, docs/spec/, MILESTONES.md, or this shared/ namespace. CLAUDE.md does not introduce facts of its own. If a CLAUDE.md line cannot be traced to a grounded source, it is wrong — fix the source, not the projection.

7. Decision docs are append-only (MR-7).

Closed decision docs are not edited. Supersession is via a new dated doc with Supersedes: in the front-matter and a Superseded-by: line added to the original (this is the only permitted edit to a closed doc — adding the back-reference). Editing rationale is itself an event; new event, new doc.

8. Templates use <<PLACEHOLDER>> tokens.

Bootstrap-time substitution. <<PROJECT_NAME>>, <<ISO_DATE>>, etc. Examples in templates go in <!-- example: ... --> HTML comments that the bootstrap pass strips. Hardcoded example values inside placeholders leak project specifics into shared templates.