Sync repo-template contract with current upstream wording

LPFchan · LPFchan · commit 74ab5893a4bf · 2026-04-12T09:23:58.000+09:00
timestamp: 2026-04-12 09-23-10 KST
changes:
- restored the governed repo-template surfaces to the current upstream wording
- kept Markfops-only material in explicit local-divergence sections and local enforcement extensions
- synchronized the commit standards hook, range checker, hook installer, and CI workflow with the current template contract
rationale:
- the repo should match the upstream contract verbatim where the template governs the wording
- explicit local divergence keeps Markfops-specific commands and stronger checks visible without rewriting the template text
checks:
- git diff --check
- sh -n .githooks/commit-msg scripts/check-commit-standards.sh scripts/check-commit-range.sh scripts/install-hooks.sh
- ruby -e 'require "yaml"; YAML.load_file(".github/workflows/commit-standards.yml")'
notes:
- commit history remains the canonical execution record via commit-backed LOG ids

project: markfops
agent: codex-markfops-upsync
role: orchestrator
commit: LOG-20260412-092310-upsync
artifacts: DEC-20260412-001
diff --git a/.github/workflows/commit-standards.yml b/.github/workflows/commit-standards.yml
@@ -3,8 +3,6 @@ name: Commit Standards
 on:
   pull_request:
   push:
-    branches:
-      - "**"
 
 jobs:
   commit-standards:
@@ -16,7 +14,7 @@ jobs:
           fetch-depth: 0
 
       - name: Make scripts executable
-        run: chmod +x .githooks/commit-msg scripts/check-commit-standards.sh scripts/check-commit-range.sh scripts/install-hooks.sh
+        run: chmod +x scripts/check-commit-standards.sh scripts/check-commit-range.sh
 
       - name: Validate pull request commits
         if: github.event_name == 'pull_request'
diff --git a/AGENTS.md b/AGENTS.md
@@ -18,15 +18,6 @@ Before running a repeatable repo workflow, read the relevant `skills/<name>/SKIL
 
 When writing into an artifact directory, read that directory's `README.md` first. If it includes a prescriptive shape, follow it. If it is intentionally lightweight, keep the output lightweight too.
 
-## Repo-Specific Notes
-
-- `docs/` is for Sparkle and GitHub Pages assets, not canonical project truth.
-- `ref/` contains research specimens and reference repos, not production dependencies.
-- Generate the Xcode project with `xcodegen generate` when needed.
-- Preferred local verification commands:
-  - `xcodebuild build -project Markfops.xcodeproj -scheme Markfops -destination 'platform=macOS' CODE_SIGN_IDENTITY='' CODE_SIGNING_REQUIRED=NO`
-  - `xcodebuild test -project Markfops.xcodeproj -scheme MarkfopsTests -destination 'platform=macOS' CODE_SIGN_IDENTITY='' CODE_SIGNING_REQUIRED=NO`
-
 ## Operating Rules
 
 - Keep durable truth in repo files, not only in external tools.
@@ -35,10 +26,11 @@ When writing into an artifact directory, read that directory's `README.md` first
 - Worker agents should prefer evidence, proposals, and compliant commit-backed execution records. The orchestrator or operator owns truth-doc updates unless the operator explicitly allows a different flow.
 - Treat `INBOX.md` as pressure, not a backlog. During inbox review, cluster capture and promote only survived triage.
 - Promote sparsely. Do not mirror one evolving thought into research, decisions, plans, spec, status, upstream records, and execution records.
+- If the repo tracks upstream on a cadence, use `upstream-intake/` instead of inventing a parallel workflow.
 - When creating artifacts or commits, follow the stable-ID and provenance rules in `REPO.md`.
 - Prefer the local `README.md` shape over ad hoc formatting when it defines one.
-- If hooks are installed with `scripts/install-hooks.sh`, your commit message must satisfy the local provenance check before the commit is allowed.
-- If CI commit checks are enabled, your pushed commits must satisfy the same provenance rules remotely.
+- Your commit message must satisfy the local repo provenance check before the commit is allowed.
+- Your pushed commits must satisfy the same provenance rules remotely in CI.
 - Treat each committed change as a canonical execution record through `commit: LOG-*`.
 - Normal commits must use the structured body keys `timestamp:`, `changes:`, `rationale:`, and `checks:` with `notes:` optional.
 
@@ -52,15 +44,25 @@ When you write or update repo artifacts, adherence to the repo's ruleset is requ
 - Do not turn an inbox review into a giant digest of every low-confidence idea. Report counts or clusters when full detail does not protect focus.
 - Do not write chatty transcripts where the repo expects normalized records.
 - If an artifact guide is intentionally lightweight, do not over-structure the document just to make it look uniform.
+- If the repo guidance and the requested output appear to conflict, follow the repo rules and explain the tension in the artifact or handoff.
 - Do not bypass commit provenance checks by omitting required trailers unless the commit is an explicit bootstrap or migration exception.
 - Do not put `LOG-*` ids inside `artifacts:`.
-- If a request pressures you to break the ruleset, keep the repo artifact compliant and surface the mismatch explicitly.
 
 ## Skills
 
 `skills/<name>/SKILL.md` files are reusable procedures for bounded workflows.
 
-- Read `skills/README.md` and the relevant skill before executing a repeatable repo workflow.
-- Keep skills procedural.
+- Keep them procedural.
 - Do not duplicate canonical repo policy inside them.
 - Use them to standardize repeatable tasks, escalation triggers, and output shape.
+
+## Local Divergence
+
+Markfops-specific repo notes:
+
+- `docs/` is for Sparkle and GitHub Pages assets, not canonical project truth.
+- `ref/` contains research specimens and reference repos, not production dependencies.
+- Generate the Xcode project with `xcodegen generate` when needed.
+- Preferred local verification commands:
+  - `xcodebuild build -project Markfops.xcodeproj -scheme Markfops -destination 'platform=macOS' CODE_SIGN_IDENTITY='' CODE_SIGNING_REQUIRED=NO`
+  - `xcodebuild test -project Markfops.xcodeproj -scheme MarkfopsTests -destination 'platform=macOS' CODE_SIGN_IDENTITY='' CODE_SIGNING_REQUIRED=NO`
diff --git a/REPO.md b/REPO.md
@@ -1,63 +1,58 @@
-# REPO
+# Repo Operating Model
 
-This file is the canonical repo contract for Markfops.
-
-This document is the instruction layer for Markfops.
+This document is the canonical repo contract for repo-template-style repos.
 
 ## Purpose
 
-Use this model to keep Markfops legible as a repo managed through durable product docs, research artifacts, decisions, and implementation history.
+Use this model when a repo is managed by one operator plus many agents and you want the repo itself to remain legible over time.
 
-Markfops is a native macOS Markdown app with an active research and implementation program around a future native WYSIWYG engine. This repo uses a repo-native operating model so that product truth, accepted future direction, reusable research, and execution history do not collapse into external transcripts or one-off notes.
+The goal is simple:
 
-The goals are:
+- keep canonical truth in-repo
+- keep noisy activity out of truth docs
+- keep provenance explicit
+- let the orchestrator route work without inventing new storage rules each time
 
-- keep canonical truth in repo-root documents
-- keep research reusable and separate from commit-backed execution records
-- keep decisions durable and append-only
-- make provenance visible through stable artifact ids and commit trailers
-- reserve `docs/` for Sparkle and GitHub Pages assets rather than canonical project truth
+This file is part of the ready-to-copy scaffold for adopted repos.
 
 ## Core Surfaces
 
+Every repo using this system should separate these surfaces:
+
 | Surface | Role | Mutability |
 | --- | --- | --- |
-| `SPEC.md` | Durable statement of what Markfops is supposed to be. | rewritten |
-| `STATUS.md` | Current accepted operational truth. | rewritten |
-| `PLANS.md` | Accepted future direction that is not true yet. | rewritten |
+| `SPEC.md` | Durable statement of what the project is supposed to be. | rewritten |
+| `STATUS.md` | What is true right now operationally. | rewritten |
+| `PLANS.md` | Accepted future direction that is not current truth yet. | rewritten |
 | `INBOX.md` | Ephemeral capture waiting for triage. | append then purge |
 | `research/` | Curated research memos worth keeping. | append by new file |
 | `records/decisions/` | Durable decision records with rationale. | append-only by new file |
 | `git commit history` | Canonical execution history through structured commit-backed `LOG-*` records. | append-only by new commit |
 | `skills/` | Required procedural workflows for repeatable agent tasks. | edit by skill |
-| `upstream-intake/` | Optional upstream review subsystem if Markfops later needs recurring upstream intake. | append by cadence |
-
-Markfops-specific repo notes:
-
-- `docs/` is for Sparkle appcast, release notes publishing, and GitHub Pages assets.
-- `ref/` is for reference repositories and local specimens used for research.
-- `upstream-intake/` is intentionally omitted until Markfops has a real upstream-review cadence to manage.
+| `upstream-intake/` | Optional upstream review subsystem for repos that track an upstream. | append by cadence |
 
 ## Agent Compatibility Files
 
 Some coding agents look for repo-root instruction files such as `AGENTS.md` or `CLAUDE.md`.
 
-When this repo includes them:
+When a repo using this model includes them:
 
-- they act as entrypoints into the canonical rules, not competing policy documents
-- they stay short enough that they do not drift from `REPO.md`
-- they point writers to the correct canonical surface and local `README.md` guide before drafting
-- `skills/<name>/SKILL.md` stays separate because it defines a bounded reusable procedure, not repo-wide policy
-- `skills/` ships with Markfops as repo-native procedural documentation, even when the agent runtime does not auto-load skills
+- they should act as entrypoints into the canonical rules, not competing policy documents
+- they should stay short enough that they do not drift from `REPO.md`
+- `AGENTS.md` should be the main editable agent-instructions file when both files exist
+- `CLAUDE.md` should be a thin shim that points to `AGENTS.md` when the tool supports it
+- `SKILL.md` stays separate because it defines a bounded reusable procedure, not repo-wide policy
+- `skills/` should ship with adopted repos as repo-native procedural documentation, even when the agent runtime does not auto-load skills
+- optional repo subsystems may have optional companion skills
 
 Recommended split:
 
 - `REPO.md`
   - canonical rules
 - `AGENTS.md`
-  - tool-facing summary plus read order
+  - canonical editable agent-instructions file
 - `CLAUDE.md`
-  - Claude-facing shim into the same rules
+  - Claude Code shim that points to `AGENTS.md`
 - `skills/<name>/SKILL.md`
   - procedure for one repeatable workflow
 
@@ -67,13 +62,20 @@ Macro structure is not enough on its own. Agents should not improvise document s
 
 When writing repo files or commit-backed execution records:
 
-- read the nearest canonical surface, local directory `README.md`, and any explicit template before drafting
+- read the nearest canonical surface, directory `README.md`, and any explicit template before drafting
 - if the local `README.md` includes a default shape or canonical example, follow it by default
 - use the established section order only when the surface actually defines one and it helps the repo stay legible
 - write normalized repo records, not external transcripts or stream-of-consciousness notes
 - keep facts, decisions, open questions, and next steps clearly separated
 - summarize evidence and outcomes instead of pasting raw command output unless the literal output is the artifact
-- prefer short declarative bullets or paragraphs over filler
+- prefer short declarative bullets or paragraphs over vague filler
+
+When a directory exists to store a durable artifact type, it should ideally include:
+
+- a `README.md` that explains what belongs there
+- a default shape or canonical example inside that same `README.md` when that artifact type benefits from it
+
+That single guide helps future agents copy a house style instead of inventing one.
 
 ## Separation Rules
 
@@ -85,13 +87,13 @@ These boundaries are mandatory:
 - `INBOX.md` is not durable truth.
 - `research/` is not raw execution history.
 - `records/decisions/` is not the same as commit-backed execution history.
-- `docs/` is not a substitute for the canonical repo operating surfaces.
+- Off-Git memory is not a substitute for repo-local canonical docs.
 
-That separation keeps common questions fast to answer:
+That separation gives future operators and future agents fast answers to different questions:
 
-- What is the product supposed to be? -> `SPEC.md`
+- What is the project? -> `SPEC.md`
 - What is true right now? -> `STATUS.md`
-- What future direction is already accepted? -> `PLANS.md`
+- What future work is actually accepted? -> `PLANS.md`
 - What did we learn from exploration? -> `research/`
 - What did we decide and why? -> `records/decisions/`
 - What actually happened during execution? -> git commit history via `commit: LOG-*`
@@ -100,7 +102,7 @@ That separation keeps common questions fast to answer:
 
 ### Operator
 
-The operator is the final authority for product direction, architecture acceptance, workflow changes, and truth updates.
+The operator is the final authority for product direction, escalation outcomes, and acceptance of truth changes.
 
 ### Orchestrator Agent
 
@@ -128,7 +130,7 @@ They may:
 - create compliant commit-backed execution records when granted commit authority
 - propose truth changes through the orchestrator
 
-They should not update `SPEC.md`, `STATUS.md`, or `PLANS.md` directly unless the operator explicitly chooses that flow.
+They should not update `SPEC.md`, `STATUS.md`, or `PLANS.md` directly unless the operator explicitly allows that flow.
 
 ### External Capture Surfaces
 
@@ -244,7 +246,7 @@ One task may legitimately touch multiple layers. For example:
 - a product choice can create `DEC-*` and update `PLANS.md`
 - implementation progress can create a committed `LOG-*` and update `STATUS.md`
 
-Touch multiple layers only when each touched layer has a distinct job.
+Touch multiple layers only when each layer receives distinct information.
 Do not copy the same evolving thought into research, decision, plan, spec, status, upstream, and execution surfaces.
 
 ## Write Rules
@@ -358,9 +360,9 @@ Body rules:
 
 ## Commit-Time Enforcement
 
-If the repo enables commit hooks, every attempted commit should be checked against these provenance rules.
+Repos using this system must enforce these provenance rules both locally and remotely.
 
-Recommended minimum enforcement:
+Required minimum enforcement:
 
 - reject commits that do not include `project:`, `agent:`, `role:`, and `commit:`
 - reject roles outside `orchestrator|worker|subagent|operator`
@@ -373,7 +375,7 @@ Recommended minimum enforcement:
 
 The goal is not perfect policy automation. The goal is to stop obviously non-compliant commits before they land.
 
-Best practice is to use both:
+Required enforcement layers:
 
 - local git hooks for fast feedback before the commit is created
 - CI for remote re-validation on push or pull request
@@ -400,10 +402,21 @@ The Off-Git runtime should answer:
 - which source events produced the artifact
 - how execution lineage maps across rebases, cherry-picks, merges, and absorbed `LOG-*` ids
 
-## Markfops Notes
+## Scaffold Rule
+
+`scaffold/` is a ready-to-copy repo skeleton, not a loose library of files to cherry-pick casually.
+
+Use it when you want a managed repo to share one canonical layout so humans and agents know exactly where work belongs.
+
+In this template, scaffold files live under `scaffold/`.
+After adoption, the scaffold contents belong at the target repo root.
+For example, `scaffold/skills/repo-orchestrator/SKILL.md` becomes `skills/repo-orchestrator/SKILL.md` in the adopted repo.
 
+## Local Divergence
+
+Markfops-specific repo notes:
+
+- `project-id` is `markfops`.
 - `docs/` is for Sparkle appcast, release notes publishing, and GitHub Pages assets.
 - `ref/` is for reference repositories and local specimens used for research.
 - `upstream-intake/` is intentionally omitted until Markfops has a real upstream-review cadence to manage.
-
-Keep skills lightweight and procedural. They should point back to this operating model rather than duplicating all of its rules.
diff --git a/records/decisions/DEC-20260412-001-upstream-repo-template-contract-sync.md b/records/decisions/DEC-20260412-001-upstream-repo-template-contract-sync.md
@@ -0,0 +1,38 @@
+# DEC-20260412-001: Current Upstream Repo-Template Contract Sync
+Opened: 2026-04-12 09-23-10 KST
+Recorded by agent: codex-markfops-upsync
+
+## Metadata
+
+- Status: accepted
+- Scope: repo contract, local divergence handling, and commit provenance enforcement
+- Related artifacts: `REPO.md`, `AGENTS.md`, `skills/README.md`, `skills/repo-orchestrator/SKILL.md`, `.github/workflows/commit-standards.yml`
+
+## Decision
+
+Markfops will keep the current upstream repo-template contract verbatim in the governed surfaces and keep repo-specific material only in explicit local-divergence sections or local extensions.
+
+## Context
+
+The repo already adopted repo-template, but the governed contract files and enforcement helpers had accumulated local wording and a few local conveniences. The repo needed a clean sync to the current upstream contract without losing the Markfops-specific commands, paths, and project notes that still matter locally.
+
+## Options Considered
+
+- Keep the existing local wording and mixed contract surfaces
+- Replace the governed surfaces with the current upstream repo-template wording and isolate local details separately
+- Rebuild the repo contract around a new Markfops-only policy layer
+
+## Rationale
+
+Keeping the upstream contract verbatim reduces drift and makes future migrations easier to compare against the source template. Isolating local notes and stronger local checks in explicit divergence sections keeps the repo-specific behavior visible without rewriting the upstream rules in Markfops phrasing.
+
+- governed docs stay aligned with the current template source
+- local commands and project notes remain available where they are useful
+- stronger local enforcement can remain explicit instead of hidden inside rewritten policy prose
+
+## Consequences
+
+- `REPO.md`, `AGENTS.md`, and the skills layer track the current upstream wording
+- Markfops-specific notes live in labeled local-divergence sections
+- the commit standards hook and range checker remain active locally
+- remote enforcement stays on the same upstream contract through CI
diff --git a/scripts/check-commit-range.sh b/scripts/check-commit-range.sh
@@ -9,6 +9,7 @@ fi
 
 base=$1
 head=$2
+# Local extension: keep zero-SHA handling and duplicate LOG-id scanning for pushed ranges.
 zero=0000000000000000000000000000000000000000
 
 repo_root=$(cd "$(dirname "$0")/.." && pwd)
diff --git a/scripts/check-commit-standards.sh b/scripts/check-commit-standards.sh
@@ -248,7 +248,7 @@ check_primary_id_uniqueness() {
         if [ -n "$head_sha" ] && [ "$sha" = "$head_sha" ]; then
           continue
         fi
-        fail "primary `commit:` id already exists in history: $primary_id"
+        fail "primary \`commit:\` id already exists in history: $primary_id"
       fi
     done
   done
@@ -275,6 +275,7 @@ commit_value=$(trailer_value "commit")
 artifacts_value=$(trailer_value "artifacts" || true)
 
 [ -n "$project" ] || fail "project trailer is empty"
+# Local extension: Markfops keeps project-id enforcement pinned to markfops.
 [ "$project" = "markfops" ] || fail "project trailer must be markfops"
 [ -n "$agent" ] || fail "agent trailer is empty"
 
@@ -329,7 +330,7 @@ if [ -n "$artifacts_value" ]; then
     esac
 
     printf '%s\n' "$artifact_id" | grep -Eq '^[A-Z]{3}-[0-9]{8}-[0-9]{3}$' ||
-      fail "artifacts trailer must contain only stable ids like DEC-YYYYMMDD-NNN"
+      fail "artifacts trailer must contain only file-backed ids like DEC-YYYYMMDD-NNN"
 
     case " $seen_artifacts " in
       *" $artifact_id "*) fail "duplicate artifact id inside artifacts trailer: $artifact_id" ;;
diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh
@@ -4,17 +4,7 @@ set -eu
 
 repo_root=$(cd "$(dirname "$0")/.." && pwd)
 git -C "$repo_root" config core.hooksPath .githooks
-chmod +x \
-  "$repo_root/.githooks/commit-msg" \
-  "$repo_root/scripts/check-commit-standards.sh" \
-  "$repo_root/scripts/check-commit-range.sh" \
-  "$repo_root/scripts/install-hooks.sh"
+chmod +x "$repo_root/.githooks/commit-msg" "$repo_root/scripts/check-commit-standards.sh"
 
 echo "Configured git hooks for $repo_root"
 echo "Active hooks path: .githooks"
-
-if [ -f "$repo_root/.gitmessage.markfops" ]; then
-  echo "Optional helper available: .gitmessage.markfops"
-  echo "Set it manually if desired:"
-  echo "  git config commit.template .gitmessage.markfops"
-fi
diff --git a/skills/README.md b/skills/README.md
@@ -1,7 +1,8 @@
 # Skills
 
-This directory is Markfops' repo-native procedure layer.
+This directory is part of the repo-template scaffold.
 
+Use it as repo-native procedural documentation.
 Agents should read the relevant workflow even when their runtime does not auto-load skills.
 
 Each reusable workflow should live at `skills/<name>/SKILL.md`.
diff --git a/skills/repo-orchestrator/SKILL.md b/skills/repo-orchestrator/SKILL.md
