pdurlej/platform

Fork 0

governance: ADR-0006 cousin role taxonomy + ADR-0007 domain promotion policy #168

Closed

pdurlej wants to merge 1 commit from claude-orchestrator/governance-cousin-taxonomy-domain-promotion into main

pdurlej commented

2026-05-11 01:52:34 +02:00

Owner

What

Two governance ADRs that fold cleanly per GPT-5.5 Pro oracle review (2026-05-11) without adding runtime weight. Lands as Phase 03-compatible (no module changes, no runtime mutation, pure spec/charter/docs).

ADR-0006 — Cousin Role Taxonomy (extends ADR-0005)

Formalizes the seven canonical cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity) with one-sentence triggers, memory persistence model, and Forgejo-write authority.

Key decision: role attribution via metadata field (**Role:**), NOT separate git identities per role. Rejected GPT's proposed claude-orchestrator / claude-reviewer-tech separate-identity model because 9 identities × 9 PATs × 9 BW entries × rotation overhead exceeds the audit-clarity benefit in a single-operator homelab.

New named cousins: Iskra (vps1000 runtime; read-only to Forgejo) and Hermes Upstream Agency (rs2000 product discovery; outputs under /hermes/<slug>/). Both surface in operator workflows but cannot author PRs autonomously.

Identity collision rule: two roles, one cousin → disambiguate via the **Role:** field in coordination-lane comments (already required by ADR-0005), audit-log entries, and 3+3 review artifacts.

ADR-0007 — Domain Promotion Policy (path-default, subdomain-as-promotion)

Closes the operator-bandwidth sink of DNS-registrar friction per new project. GPT flagged this as one of the bandwidth-sinks ("subdomain-as-default optimizes for elegance at the cost of operator bandwidth").

Rule: new services live under pdurlej.com/projects/<slug> (experimental) or pdurlej.com/products/<slug> (post-validation) or tailnet.ts.net/<service> (Tailnet-only). Subdomain <service>.pdurlej.com granted only when one of: public identity, auth boundary, cookie boundary, product surface, or operator preference (with justification).

Schema change (separate PR follows to keep this review-clean): module.yaml adds exposure.path_or_subdomain with conditional subdomain + subdomain_justification requirements.

Grandfathered: existing subdomains as of 2026-05-11 (git, kan, honcho, umami) stay as-is; each adds subdomain_justification opportunistically.

Files

File	Change	Purpose
`decisions/0006-cousin-role-taxonomy.md`	NEW	The ADR itself
`decisions/0007-domain-promotion-policy.md`	NEW	The ADR itself
`AGENTS.md`	EDIT	New `## Cousins` section before `## Joining as a new agent`
`PLATFORM_CHARTER.md`	EDIT	New `§3.5 Domain promotion policy` sub-section before `## 4. Observability stack`
`docs/agents/cousin-roles.md`	NEW	Operator-facing glossary; companion to ADR-0006

5 files changed, +533 / -0.

What this PR DOES

✅ Formalizes Iskra and Hermes as named cousins with documented scope.
✅ Resolves identity-collision ambiguity via metadata convention (no new git identities).
✅ Eliminates DNS-registrar friction for short-lived experiments via path-default.
✅ Codifies subdomain promotion criteria in writing for audit.
✅ Stays compatible with Phase 03 platformctl work (no module-level changes; only spec/docs).

What this PR DOES NOT

Does NOT modify schema/module.schema.json (separate PR for the path_or_subdomain field; ADR-0007 just specifies the contract).
Does NOT retroactively migrate grandfathered subdomains.
Does NOT add a platformctl lint check for missing **Role:** fields (deferred follow-up).
Does NOT promote Iskra or Hermes to Forgejo write authority (requires separate ADR if needed).
Does NOT touch any runtime path, sacred path, or module manifest.
Does NOT introduce Phase 07 runtime work (that ships as separate PRs as design docs only).

Acceptance criteria

Two ADRs exist with Status: Proposed.
AGENTS.md has new ## Cousins section with canonical enumeration table.
PLATFORM_CHARTER.md has §3.5 Domain promotion policy with summary + ADR reference.
docs/agents/cousin-roles.md exists as operator-facing glossary.
3+3 canary review passes (will fire on risk/process label — this PR touches decisions/ per §Security-Sensitive Class Of Service trigger).
Operator approves; Status: line in both ADRs flips to Accepted.

Rollback

git revert 28e0de5   # single squashable commit
git push origin main

No runtime state touched. Reverting deletes 3 net-new files + reverts AGENTS.md + PLATFORM_CHARTER.md additions. No DNS, no Traefik, no module change. Safe to revert at any point pre- or post-merge.

Refs

Closes (conceptual): part of the operator's 2026-05-10 vision-session asks; GPT-5.5 Pro oracle review 2026-05-11 §1 "DELTA INTEGRATION" + §2 "CONFLICTS WITH EXISTING CHARTER" + §4 OVER-ENGINEERING audit (path-vs-subdomain row).
Companion ADRs: ADR-0001 (canary cadence), ADR-0003 (Agent Access Plane), ADR-0005 (Forgejo coordination lanes).
Related future work: separate schema PR for module.yaml exposure.path_or_subdomain field; deferred platformctl lint check; Phase 07 design docs (separate PRs).

Codex effort needed

Review + merge. No runtime change. Acceptance is documentation-verifiable. After merge, the cousin language is part of the canonical spec and future PRs can reference these ADRs.

Role: advisor / drafter (claude-orchestrator)
Lane: governance, ADR drafting
Next: operator review + 3+3 canary + merge → unblock subsequent PRs in this overnight session.

## What Two governance ADRs that fold cleanly per GPT-5.5 Pro oracle review (2026-05-11) without adding runtime weight. Lands as Phase 03-compatible (no module changes, no runtime mutation, pure spec/charter/docs). ## ADR-0006 — Cousin Role Taxonomy (extends ADR-0005) Formalizes the seven canonical cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity) with one-sentence triggers, memory persistence model, and Forgejo-write authority. **Key decision**: role attribution via **metadata field** (`**Role:**`), NOT separate git identities per role. Rejected GPT's proposed `claude-orchestrator` / `claude-reviewer-tech` separate-identity model because 9 identities × 9 PATs × 9 BW entries × rotation overhead exceeds the audit-clarity benefit in a single-operator homelab. **New named cousins**: Iskra (vps1000 runtime; read-only to Forgejo) and Hermes Upstream Agency (rs2000 product discovery; outputs under `/hermes/<slug>/`). Both surface in operator workflows but cannot author PRs autonomously. **Identity collision rule**: two roles, one cousin → disambiguate via the `**Role:**` field in coordination-lane comments (already required by ADR-0005), audit-log entries, and 3+3 review artifacts. ## ADR-0007 — Domain Promotion Policy (path-default, subdomain-as-promotion) Closes the operator-bandwidth sink of DNS-registrar friction per new project. GPT flagged this as one of the bandwidth-sinks ("subdomain-as-default optimizes for elegance at the cost of operator bandwidth"). **Rule**: new services live under `pdurlej.com/projects/<slug>` (experimental) or `pdurlej.com/products/<slug>` (post-validation) or `tailnet.ts.net/<service>` (Tailnet-only). Subdomain `<service>.pdurlej.com` granted only when one of: public identity, auth boundary, cookie boundary, product surface, or operator preference (with justification). **Schema change** (separate PR follows to keep this review-clean): `module.yaml` adds `exposure.path_or_subdomain` with conditional `subdomain` + `subdomain_justification` requirements. **Grandfathered**: existing subdomains as of 2026-05-11 (`git`, `kan`, `honcho`, `umami`) stay as-is; each adds `subdomain_justification` opportunistically. ## Files | File | Change | Purpose | |------|--------|---------| | `decisions/0006-cousin-role-taxonomy.md` | NEW | The ADR itself | | `decisions/0007-domain-promotion-policy.md` | NEW | The ADR itself | | `AGENTS.md` | EDIT | New `## Cousins` section before `## Joining as a new agent` | | `PLATFORM_CHARTER.md` | EDIT | New `§3.5 Domain promotion policy` sub-section before `## 4. Observability stack` | | `docs/agents/cousin-roles.md` | NEW | Operator-facing glossary; companion to ADR-0006 | 5 files changed, +533 / -0. ## What this PR DOES - ✅ Formalizes Iskra and Hermes as named cousins with documented scope. - ✅ Resolves identity-collision ambiguity via metadata convention (no new git identities). - ✅ Eliminates DNS-registrar friction for short-lived experiments via path-default. - ✅ Codifies subdomain promotion criteria in writing for audit. - ✅ Stays compatible with Phase 03 platformctl work (no module-level changes; only spec/docs). ## What this PR DOES NOT - Does NOT modify `schema/module.schema.json` (separate PR for the `path_or_subdomain` field; ADR-0007 just specifies the contract). - Does NOT retroactively migrate grandfathered subdomains. - Does NOT add a `platformctl` lint check for missing `**Role:**` fields (deferred follow-up). - Does NOT promote Iskra or Hermes to Forgejo write authority (requires separate ADR if needed). - Does NOT touch any runtime path, sacred path, or module manifest. - Does NOT introduce Phase 07 runtime work (that ships as separate PRs as design docs only). ## Acceptance criteria - [x] Two ADRs exist with Status: Proposed. - [x] AGENTS.md has new `## Cousins` section with canonical enumeration table. - [x] PLATFORM_CHARTER.md has `§3.5 Domain promotion policy` with summary + ADR reference. - [x] `docs/agents/cousin-roles.md` exists as operator-facing glossary. - [ ] 3+3 canary review passes (will fire on `risk/process` label — this PR touches `decisions/` per §Security-Sensitive Class Of Service trigger). - [ ] Operator approves; `Status:` line in both ADRs flips to `Accepted`. ## Rollback ``` git revert 28e0de5 # single squashable commit git push origin main ``` No runtime state touched. Reverting deletes 3 net-new files + reverts AGENTS.md + PLATFORM_CHARTER.md additions. No DNS, no Traefik, no module change. Safe to revert at any point pre- or post-merge. ## Refs - Closes (conceptual): part of the operator's 2026-05-10 vision-session asks; GPT-5.5 Pro oracle review 2026-05-11 §1 "DELTA INTEGRATION" + §2 "CONFLICTS WITH EXISTING CHARTER" + §4 OVER-ENGINEERING audit (path-vs-subdomain row). - Companion ADRs: ADR-0001 (canary cadence), ADR-0003 (Agent Access Plane), ADR-0005 (Forgejo coordination lanes). - Related future work: separate schema PR for `module.yaml exposure.path_or_subdomain` field; deferred `platformctl` lint check; Phase 07 design docs (separate PRs). ## Codex effort needed **Review + merge.** No runtime change. Acceptance is documentation-verifiable. After merge, the cousin language is part of the canonical spec and future PRs can reference these ADRs. --- **Role:** advisor / drafter (claude-orchestrator) **Lane:** governance, ADR drafting **Next:** operator review + 3+3 canary + merge → unblock subsequent PRs in this overnight session.

pdurlej added 1 commit

2026-05-11 01:52:34 +02:00

governance: ADR-0006 cousin role taxonomy + ADR-0007 domain promotion policy

canary-required / collect-diff (pull_request) Successful in 3s

Details

canary-required / canary (pull_request) Successful in 12s

Details

28e0de5f38

Two ADRs + AGENTS.md §Cousins amendment + PLATFORM_CHARTER.md §3.5 amendment
+ operator-facing glossary docs/agents/cousin-roles.md.

ADR-0006 — Cousin Role Taxonomy (extends ADR-0005)

Formalizes the seven canonical cousins (operator, Iskra, Hermes, claude,
codex, glm, antigravity) with one-sentence triggers, memory persistence
model, and Forgejo-write authority. Adopts role-metadata attribution (not
separate git identities per role) to avoid the 9-identity x 9-PAT x 9-BW
operational overhead while still disambiguating "claude said X" between
orchestrator/advisor/reviewer-tech/reviewer-product lanes.

Iskra and Hermes added as named cousins. Both are read-only to Forgejo
(cannot author PRs); their outputs land under their respective surfaces
(Signal/Matrix for Iskra; /hermes/<slug>/ for Hermes) and get promoted to
issues/PRs by operator or claude-orchestrator.

Role attribution via mandatory **Role:** field in coordination-lane comments
(per ADR-0005), recommended in PR descriptions, mandatory in
state/AUDIT_LOG.jsonl entries written after this ADR merges. Co-Role: commit
footer is RECOMMENDED when tooling distinguishes lanes (e.g.
platformctl.tools.run_review writes commits with Co-Role: reviewer-tech).

ADR-0007 — Domain Promotion Policy (path-default, subdomain-as-promotion)

Closes the operator-bandwidth sink of DNS-registrar friction per new project.

Rule: new services live under pdurlej.com/projects/<slug> (experimental) or
pdurlej.com/products/<slug> (post-validation) or tailnet.ts.net/<service>
(Tailnet-only). Subdomain (<service>.pdurlej.com) granted only on explicit
criteria: public identity, auth boundary, cookie boundary, product surface,
or operator preference with runbook justification.

Schema change: module.yaml adds exposure.path_or_subdomain field with
conditional subdomain + subdomain_justification (schema PR follows
separately to keep this PR review-clean).

Grandfathered subdomains as of 2026-05-11 (git/kan/honcho/umami) remain
as-is; each must add subdomain_justification opportunistically (follow-up
issue, low priority).

Promotion procedure: Forgejo issue using subdomain_promotion template,
operator-approved, PR amends manifest + Traefik router, operator manually
adds DNS record at the registrar (deliberate manual gate), operator
verifies via iskra-canary.

Companion files

- AGENTS.md adds §Cousins section before §Joining as a new agent.
- PLATFORM_CHARTER.md §3.5 adds Domain promotion policy sub-section
  referencing ADR-0007.
- docs/agents/cousin-roles.md is the operator-facing glossary (read when
  forgetting which cousin owns what; companion to ADR-0006).

Refs

- ADR-0005 (Forgejo coordination lanes) — extended by ADR-0006
- ADR-0001 (canary cadence) — referenced for PR size class via antigravity
- GPT-5.5 Pro oracle review 2026-05-11 — flagged identity collision and
  subdomain bandwidth sink as gaps
- vision session 2026-05-10 — surfaced cousin language (Iskra/Hermes named)

**Role:** advisor / drafter (claude-orchestrator)

claude commented

2026-05-11 01:54:30 +02:00

Collaborator

Role: orchestrator
Intent: checkpoint
Needs owner: no (transparency note)

Self-correction: this PR (#168) was opened via the Forgejo MCP, which currently uses the operator PAT (per AGENTS.md §Step 6 + Issue #56 reference). The PR user.login therefore shows as pdurlej rather than claude. The commits within were authored as claude-orchestrator@noreply.git.pdurlej.com which is a separate identity-drift (ADR-0006 actually rejects per-role git identities; canonical is claude@noreply.git.pdurlej.com).

Two slips, both caught by me in the next PR setup. For the remainder of this overnight session:

git config user is reset to canonical claude (per AGENTS.md §Identity-isolation)
PR openings use direct curl API with claude PAT (per AGENTS.md §Step 6 explicit guidance)

Options for operator:

A (recommended): merge this PR as-is. The slip is documented; the ADRs themselves are correct; force-pushing to fix commit authorship would lose review history.
B: I close + reopen via API with claude PAT (commits stay claude-orchestrator since git history is immutable without force-push).
C: I rebase the branch with --author="claude <claude@noreply.git.pdurlej.com>" and force-push, then close+reopen the PR. Clean but destructive to any existing review trail.

Default if no response: A. Will note in WAKEUP_BRIEF.md.

Next: operator decision (Y/N/A) on which option, OR silent default = A.

**Role:** orchestrator **Intent:** checkpoint **Needs owner:** no (transparency note) **Self-correction**: this PR (#168) was opened via the Forgejo MCP, which currently uses the operator PAT (per AGENTS.md §Step 6 + Issue #56 reference). The PR `user.login` therefore shows as `pdurlej` rather than `claude`. The commits within were authored as `claude-orchestrator@noreply.git.pdurlej.com` which is a separate identity-drift (ADR-0006 actually rejects per-role git identities; canonical is `claude@noreply.git.pdurlej.com`). Two slips, both caught by me in the next PR setup. For the remainder of this overnight session: - git config user is reset to canonical `claude` (per AGENTS.md §Identity-isolation) - PR openings use direct curl API with `claude` PAT (per AGENTS.md §Step 6 explicit guidance) Options for operator: - **A (recommended)**: merge this PR as-is. The slip is documented; the ADRs themselves are correct; force-pushing to fix commit authorship would lose review history. - **B**: I close + reopen via API with claude PAT (commits stay claude-orchestrator since git history is immutable without force-push). - **C**: I rebase the branch with `--author="claude <claude@noreply.git.pdurlej.com>"` and force-push, then close+reopen the PR. Clean but destructive to any existing review trail. Default if no response: **A**. Will note in WAKEUP_BRIEF.md. **Next:** operator decision (Y/N/A) on which option, OR silent default = A.

claude referenced this pull request

2026-05-11 01:59:09 +02:00

feat(contracts): durable job bundle as central coordination substrate (ADR-0008) #169

claude referenced this pull request

2026-05-11 02:02:39 +02:00

ops: ADR-0009 bounded L-1.5 baseline closure via 7-point spot-check #170

claude referenced this pull request

2026-05-11 02:10:47 +02:00

feat(phase-07): scope-lock Cousin Layer + Local Admin + Attention Dispatcher (design only) #171

claude referenced this pull request

2026-05-11 02:15:26 +02:00

ops: ADR-0013 4th replica = Synology + encrypted Dropbox combo (closes BLOCKERS §2) #172

claude referenced this pull request

2026-05-11 02:19:14 +02:00

ops: ADR-0014 Phase 06 prune Q2-2026 additional sunset candidates + silverbullet migration spec #173

claude referenced this pull request

2026-05-11 02:23:14 +02:00

docs(hermes): canonical 7-deliverable bundle templates (Phase 07 §G + GPT §7) #174

claude referenced this pull request from a commit

2026-05-11 02:24:55 +02:00

state/reports: WAKEUP_BRIEF for operator after overnight session 2026-05-11

claude referenced this pull request

2026-05-11 02:25:31 +02:00

state/reports: WAKEUP_BRIEF for operator after overnight session 2026-05-11 #175

codex referenced this pull request from a commit

2026-05-12 00:18:14 +02:00

chore(prompts): Codex RS2000 migration close-out dispatch for 2026-05-12

claude referenced this pull request

2026-05-12 00:18:33 +02:00

chore(prompts): Codex RS2000 close-out dispatch (P0 phase3 apply chain + P1 recovery batch + P2 prune) #186

codex referenced this pull request from a commit

2026-05-12 00:26:19 +02:00

governance: renumber Prof Kong ADRs 0006/0007 → 0010/0011 (collision fix, supersedes PR #168)

claude referenced this pull request

2026-05-12 00:26:40 +02:00

governance: renumber Prof Kong ADRs 0006/0007 → 0010/0011 (collision fix, supersedes PR #168) #187

claude commented

2026-05-12 00:26:49 +02:00

Collaborator

Superseded by PR #187 (renumeration)

Role: orchestrator (Pan Herbatka, claude-thread for pdurlej/platform)

Operator's decision 2026-05-12: ADR numbers in this PR (0006 + 0007) collide with merged PR #184 (single-operator-status-file + risk-proportional-canary). Resolution:

Files renamed decisions/0006-cousin-role-taxonomy.md → decisions/0010-cousin-role-taxonomy.md
Files renamed decisions/0007-domain-promotion-policy.md → decisions/0011-domain-promotion-policy.md
All cross-references updated
Renumeration trace added to each ADR header + AGENTS.md / PLATFORM_CHARTER.md / docs/agents/cousin-roles.md inline notes
Substantive content from this PR preserved unchanged

This PR can be closed in favor of #187. The original drafter's work (claude-orchestrator thread) is fully preserved with attribution; only ADR numbers shift to free up 0006/0007 for the merged ADRs.

Flagged in PR #186 by Pan Herbatka; resolved by operator + Pan Herbatka in PR #187.

Refs: PR #184 (collision source), PR #186 (flag origin), PR #187 (replacement, opened 2026-05-12)

🍵

## Superseded by PR #187 (renumeration) **Role:** orchestrator (Pan Herbatka, claude-thread for `pdurlej/platform`) Operator's decision 2026-05-12: ADR numbers in this PR (0006 + 0007) collide with merged PR #184 (single-operator-status-file + risk-proportional-canary). Resolution: - Files renamed `decisions/0006-cousin-role-taxonomy.md` → `decisions/0010-cousin-role-taxonomy.md` - Files renamed `decisions/0007-domain-promotion-policy.md` → `decisions/0011-domain-promotion-policy.md` - All cross-references updated - Renumeration trace added to each ADR header + AGENTS.md / PLATFORM_CHARTER.md / docs/agents/cousin-roles.md inline notes - Substantive content from this PR preserved unchanged **This PR can be closed** in favor of #187. The original drafter's work (claude-orchestrator thread) is fully preserved with attribution; only ADR numbers shift to free up 0006/0007 for the merged ADRs. Flagged in PR #186 by Pan Herbatka; resolved by operator + Pan Herbatka in PR #187. Refs: PR #184 (collision source), PR #186 (flag origin), PR #187 (replacement, opened 2026-05-12) 🍵

claude commented

2026-05-12 00:36:54 +02:00

Collaborator

Closing — PR #187 merged. ADR-0010/0011 + cross-refs live in main. Renumeration trace preserved in ADR headers + AGENTS.md / PLATFORM_CHARTER.md / docs/agents/cousin-roles.md.

Thanks to original drafter (claude-orchestrator thread) — content preserved verbatim, only numbers shifted.

🍵

Closing — PR #187 merged. ADR-0010/0011 + cross-refs live in main. Renumeration trace preserved in ADR headers + AGENTS.md / PLATFORM_CHARTER.md / docs/agents/cousin-roles.md. Thanks to original drafter (claude-orchestrator thread) — content preserved verbatim, only numbers shifted. 🍵

claude closed this pull request

2026-05-12 00:36:54 +02:00

codex referenced this pull request

2026-05-12 01:09:37 +02:00

[coordination-lane] Cutover Flight Phase 2: v2 catalog to gate #142

pdurlej referenced this pull request from a commit

2026-05-12 01:51:22 +02:00

Merge pull request 'governance: renumber Prof Kong ADRs 0006/0007 → 0010/0011 (collision fix, supersedes PR #168)' (#187) from claude/orders/adr-renumber-0010-0011-from-pr168 into main

codex referenced this pull request from a commit

2026-05-12 01:56:39 +02:00

governance: ADR-0017 — no stacked PRs to main + 4-layer guard (pre/post-merge + cousin + operator)