---
title: "ADR-0004: Mandatory Git publication of verified work units"
---

> Documentation Index
> Fetch the complete documentation index at: https://nclsppr.github.io/project-foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0004: Mandatory Git publication of verified work units

- Status: accepted
- Implementation status: delivered
- Date: 2026-07-30
- Last verification: 2026-07-30, pack tests and complete local verification
- Owner: Nicolas Pieper
- Supersedes: none
- Superseded by: none

## Context

Default `D02` recommended small, coherent commits and then a conditional push
when a repository published or backed up the work. The definition of done only
required a required push to succeed. Therefore, a project or agent could
consider a work unit complete while it remained in a worktree or local history.

This ambiguity occurred during Parkventory development. The product,
documentation, and validation were complete locally, but no commit or push was
made because there was no sufficiently explicit universal rule.

## Decision problem

How can authorized, coherent, and verified work quickly become remotely
visible, recoverable, and verifiable without bypassing branch protection or
mixing unrelated changes?

## Considered options

### Keep publication as a default

Advantage: Each project selects its Git practices.

Limitation: Work that is declared complete can remain fragile and invisible on
the local machine, without CI or a shared recovery point.

### Always require a direct push to `main`

Advantage: The path is simple for personal repositories.

Limitations: This option is incompatible with branch protection, mandatory
reviews, and some team repositories.

### Require publication and let the policy select the branch

Advantages: No completed work unit remains only local. `main` remains the short
path when it is accessible. A dedicated branch complies with protection and
review requirements.

Limitation: Each project must still specify its canonical branch and review
policy.

## Decision

The canonical rule is principle `P18` in `PRINCIPLES.md`. Each task that permits
modification of a Git repository with a remote must deliver each coherent and
verified work unit with a commit followed by an immediate push.

The push goes directly to the canonical branch if its policy permits this
action. If the branch is protected or requires review, create or reuse a
dedicated branch for the task scope. Never bypass protection.

A local convenience deviation cannot disable `P18`. Exceptions are limited by
the principle: explicitly read-only or local-only work, a higher-level
restriction, no remote, or an external blocker. A blocker records a local SHA,
remote target, and explicit resume condition. It does not change the delivery
result to success.

## Consequences

### Positive

- Completed work is visible and recoverable quickly.
- CI and reviews can start without waiting for a large delivery.
- Commits remain smaller, and rollbacks are more precise.
- Protected branches remain protected.
- Delivery evidence can identify a remote SHA.

### Negative

- The process can produce more pushes and CI runs.
- A work unit must have a correct scope before the commit.
- A network or authentication incident becomes an explicit delivery blocker instead of a hidden local success.

## Implementation

1. Add `P18` to the invariants.
2. Remove commit and push frequency from `D02`. It retains only the default destination and review method.
3. Add `P18` to the `AGENTS.md` adapters of all packs.
4. Align the definition of done, bootstrap, adoption, versioning, and delivery evidence.
5. Test that the principle and its adapter text are present in generated projects.

## Verification

- `./scripts/verify.sh` passes.
- Each generated pack contains `P18` in its snapshot.
- The Minimal and Standard or higher adapters require a commit and push.
- The release commit exists on the remote.
- The annotated tag points to the verified commit.
- Parkventory then adopts the release and publishes its first commit.

## Review

Review this decision only if several projects demonstrate that this frequency
has a disproportionate CI cost and does not improve recovery or review. The
review can adjust the size of a coherent work unit or the CI strategy. It must
not permit work that exists only locally to be declared complete.

Source: https://nclsppr.github.io/project-foundation/docs/decisions/adr-0004-mandatory-git-publication/index.mdx