FREEZE — musehub#216 BranchMeta created_by/created_at provenance (Thinking)

id: muse-216-branchmeta-created-by
model: Thinking
frozen: true
status: freeze-review-pass
date: 2026-09-17
author: aaronrene
repo: gabriel/muse
ticket: https://staging.musehub.ai/gabriel/musehub/issues/216
consumes:
  - gabriel comment sha256:d3640c5d4e7ebf437dc9862e46af3cd96d687a4a9b5ec7e558502c077cb4e8fc
  - docs/MUSE-215-CREATED-BY-FALLBACK-FREEZE.md (out_of_scope for #216; do not redesign)
escalation: none
tier3_gates:
  - merge to gabriel/muse main (Gabriel review)
blocked_by: freeze review must be pass before {step}b Auto
out_of_scope:
  - "changing _BranchEntryJson.created_by type or meaning (stays tip-authorship str | None per #215)"
  - "changing _created_by_from_record or the list-JSON tip assignment"
  - "changing committed_at (stays the tip timestamp)"
  - "writing inferred creation records into TOML (no backfill writes)"
  - "muse push / fetch / clone / MuseHub wire types"
  - "shelf _resolve_created_by / shelf handle+kind JSON"
  - "adding --agent-id to muse branch / switch / checkout"
  - "git-import / update-ref / rebase / migrate plumbing"
  - "muse init initial main (no create-site stamp; list keys stay JSON null)"
  - "human (non --json) muse branch listing text"
  - "task/video-timeline-vid1 and untracked timeline trees"

1. WHAT is frozen

Statement of truth {step}b Auto consumes without re-deriving:

muse branch --json's created_by field is tip-commit authorship (#215). There is no persisted branch-creation record. BranchMeta (muse/cli/config.py:121–139) stores only intent, resumable, remote, merge. _load_config (config.py:269–288) and _dump_toml (config.py:431–452) round-trip those four keys only — any other TOML key under [branch."<name>"] is dropped on the next write.

write_branch_meta (config.py:1002–1033) is called only when --intent or --resumable is supplied (branch.py:800–807, checkout.py:1026–1031). A plain muse branch feat/x / muse switch -c feat/x / muse checkout -b writes a ref and a reflog line and does not write BranchMeta.

Gabriel's live reproduction (issue #216 comment sha256:d3640c5d…): create as human → later agent commit on the same branch → list created_by flips. After #215 the human tip is no longer JSON null, but the value is still whoever authored the current tip, not who created the branch. committed_at is the same class of fact (tip time, not create time).

Reflog (muse/core/reflog.py:19–32) records ref motion with a free-form author label (often "user" at checkout.py:1023) and is not a durable identity record. Do not treat reflog as the source of truth.

Frozen distinction (two facts)

#215 JSON type is not redesigned. The shelf object shape (shelf.py:124–128) is used for the new branch_created_by field only.

Frozen persistence (TOML)

Under [branch."<name>"] in .muse/config.toml, three new optional scalars:

[branch."feat/example"]
created_by      = "aaronrene"          # sanitized handle
created_by_kind = "human"              # "human" | "agent"
created_at      = "2026-09-17T10:54:10.123456+00:00"

TOML uses scalars because _dump_toml has no nested-table writer (config.py:341–454). JSON maps created_by + created_by_kind → {"handle", "kind"}. The TOML key created_by is not the list-JSON key created_by.

created_at is now_utc_iso() (muse/core/types.py:309–319) at the moment of first create. Timezone-aware UTC required.

Frozen identity at create

_resolve_branch_creator(root) -> tuple[str, Literal["human","agent"]] | None lives next to write_branch_meta in muse/cli/config.py (not in shelf.py).

1. raw = os.environ.get("MUSE_AGENT_ID", "")
   if str(raw).strip():
       handle = sanitize_provenance(raw.strip()[:256])
       if handle: return (handle, "agent")
2. raw = get_config_value("user.handle", root)   # same source muse commit uses
   if raw and str(raw).strip():
       handle = sanitize_provenance(str(raw).strip()[:256])
       if handle: return (handle, "human")
3. return None

Do not invent the sentinel handle "human" (shelf does that at shelf.py:489; branch provenance must not).

When the helper returns None, still write created_at. Omit created_by / created_by_kind rather than storing an empty handle.

Frozen write-once

If the existing BranchMeta entry already has a non-empty created_at, ignore new created_by / created_by_kind / created_at kwargs. Intent / resumable / remote / merge updates must preserve the creation triple. muse switch -C on an existing branch (switch.py:554 branch_existed is True) is a reset, not a create — do not restamp. muse checkout -b refuses if the ref exists (checkout.py:995–1001); there is no checkout -B.

Frozen create sites (must stamp on first ref create)

Frozen rename

muse branch -m/-M (branch.py:634–685) currently moves the ref and does not move BranchMeta (intent is already orphaned). {step}b must move the entire BranchMeta dict from the old key to the new key and delete the old key. Force-rename onto a name that already has meta: source identity wins (the dest branch is destroyed). This is the same branch's write-once record moving with the name.

Frozen delete / prune

delete_branch_meta (config.py:1035–1051) already drops the section. Keep that on -d/-D and --prune-config. No extra work.

Frozen list JSON (additive keys only)

_BranchEntryJson (branch.py:97–105) keeps created_by: str | None. Add a list-local TypedDict matching shelf's shape (shelf.py:124–128) without importing shelf:

class _BranchCreatedBy(TypedDict):
    handle: str
    kind: str  # "human" | "agent"

# on _BranchEntryJson:
branch_created_by: _BranchCreatedBy | None
branch_created_at: str | None

Read path: meta = read_branch_meta(...).

• branch_created_at: if TOML created_at is a non-empty str, parse with datetime.fromisoformat (accept the +00:00 form now_utc_iso writes). Require tzinfo is not None. On ValueError, missing tz, or empty → JSON null.
• branch_created_by: emit {"handle", "kind"} only when both (a) TOML created_by sanitizes to a non-empty handle and (b) created_by_kind is exactly "human" or "agent". Empty handle, missing kind, or invalid kind → JSON null even if the other half is present.

Do not call _created_by_from_record for these keys.

Legacy branches with no creation triple: both new keys are JSON null. created_by (tip) continues to follow #215. That is the read-side legacy shim. Do not write tip authorship into TOML.

Add branch_created_by and branch_created_at to _LIST_REQUIRED_KEYS in tests/test_branch_json_schema.py (today :40–43).

Human listing (branch.py:921+) is unchanged.

Frozen backfill decision

No TOML backfill in {step}b. Inferring creator from tip or reflog and persisting it would write a lie (Gabriel's own reproduction: tip ≠ creator). A one-shot inferred write is irreversible pollution of a write-once field. Existing branches stay branch_created_* = null until a future, separately frozen, operator-gated backfill exists. {step}b does not add muse branch --backfill-created-meta.

Frozen hub-wire decision

Local-only, matching intent / resumable. Evidence:

• .muse/config.toml is repo metadata, not snapshot content. muse clone writes _DEFAULT_CONFIG (clone.py:170) and does not copy the source repo's [branch.*] table.
• No push/fetch path serializes BranchMeta.

{step}b does not change muse push, fetch, clone, or MuseHub wire types. Hub-visible creation provenance is a follow-on ticket, not this phase. Creation metadata therefore does not survive clone today — same as intent. Document that in the {step}b helper docstring so Auto does not "fix" it by inventing a wire field.

2. HOW is frozen

Allowed files:

• muse/cli/config.py — BranchMeta fields; _load_config parse; _dump_toml emit; write_branch_meta kwargs + write-once; _resolve_branch_creator; stamp_branch_created; move_branch_meta.
• muse/cli/commands/branch.py — stamp on create; stamp dest on copy; move meta on rename; list JSON additive keys. Do not change _created_by_from_record (branch.py:144–174) or the tip assignment (branch.py:906).
• muse/cli/commands/checkout.py — stamp on -b create path.
• muse/cli/commands/switch.py — stamp on -C only when not branch_existed.
• muse/cli/commands/worktree.py — stamp on -b.
• Tests: tests/test_cmd_branch.py, tests/test_branch_json_schema.py, tests/test_branch_intent_created_by.py, and/or a new tests/test_branch_created_meta.py.
• This freeze + docs/MUSE-ROADMAP.md + docs/MUSE-OVERSEER-HANDOVER.md.

Forbidden:

• Changing _BranchEntryJson.created_by from str | None to an object.
• Calling shelf._resolve_created_by.
• Writing created_* into TOML from tip CommitRecord or reflog.
• Touching push/clone/wire/transport.
• Touching task/video-timeline-vid1 or untracked timeline trees.

Helpers {step}b should extract (names may vary; behavior may not):

• stamp_branch_created(root, name) → resolve creator, now_utc_iso(), write_branch_meta with write-once. Call after the ref file exists (post-write_branch_ref or empty-ref write). Skip on --dry-run. If the TOML write raises, propagate — do not swallow, do not invent a handle, do not delete the ref.
• move_branch_meta(root, old, new) → copy dict, delete old key.
• _branch_created_from_meta(meta) -> tuple[dict|None, str|None] for list JSON.

3. Fail-closed rules

No new network calls. No new top-level config keys outside [branch."<name>"].

4. Security

• Display + local TOML only. Source is env MUSE_AGENT_ID (already used by muse commit at commit.py:437–438) or user.handle via get_config_value (config.py:701–714).
• sanitize_provenance (validation.py:402–428) on every handle before TOML write and JSON emit. Cap 256 chars (commit.py:136).
• created_by_kind allowlist "human"|"agent" — no free-form kind.
• _escape + _validate_toml_key already on branch names (config.py:321–339). Handles go through _escape as values.
• Do not log MUSE_AGENT_KEY, MUSE_AGENT_HD_SEED, identity.toml, or full config.toml in tests or CLI output.
• No auth change, no wire change. Escalation: none.
• Write-once prevents a later compromised MUSE_AGENT_ID from rewriting historical creator on an existing branch.

5. Seven-tier test matrix

Existing TestListSchemaI and TestCreatedByAuthorFallback215 must keep passing. Adding the two new keys to _LIST_REQUIRED_KEYS is required so a future regression cannot drop them.

6. Definition of Done (for {step}b, not this freeze)

• All seven tiers green locally.
• /build-verification-review → pass.
• #215 tip-authorship JSON unchanged (type and helper).
• No push/clone/wire edits.
• Living docs updated together.
• Feature-branch commit on feat/216-branchmeta-created-by.
• No main merge.

7. Review discipline (file+line citations)

ok review --freeze docs/MUSE-216-BRANCHMETA-CREATED-BY-FREEZE.md must return pass before any BranchMeta write in product code.

Review record

review_stamp:
  gate: mechanical
  reviewed_at: '2026-09-17T11:02:53Z'
  mechanical_verdict: pass
  produced_by: checklist_engine
  provider_kind: rule_engine
  reviewer_mode: agent
  reviewer_model: null
  reviewer_provider: local
  checklist_ids:
  - C1
  - C2
  - C3
  - C4
  - C5
  - C6
  - C7
  - C8
  checklist_source: builtin
  findings_count: 0
  override_applied: false
  kit_version: 0.1.0
  artifact_digest: sha256:ee01f104b71e4636d1f5ffc063553ad4c00c5be39a204a6fc52ffb518c6a845b