docs(charter): update §2 to reality (DeepSeek finding #5) #332

Closed

claude wants to merge 1 commit from claude/d/charter-section-2-reality-update into main

claude commented

2026-05-17 17:48:37 +02:00

Collaborator

Summary

DeepSeek deep review 2026-05-14, finding #5: PLATFORM_CHARTER.md §2 described platformctl as "~500 LOC Python skeleton" while reality is a working multi-module Python package. Also described prompts/ as 6 phase prompts when directory has grown into active dispatch surface, and annotated INDEX.yaml as "auto-generated" without any actual generator.

Per DeepSeek: charter/reality drift is exactly the agent-misleading-signal failure mode ADR-0018 was written to prevent, applied to the platform's own onboarding document.

What changed

modules/ section: "auto-generated" → "generated via platformctl index generate; refreshed in CI on push to main" (anticipates D-1 INDEX regen prebuild)
prompts/ section: reflects actual contents (execution prompts + one-shot dispatches) instead of phase 01-06 list; archive note for historical phase prompts
control-plane/platformctl/ section: reflects actual submodules (cli, validate, plan, apply, health, wip, safety, identity/, tools/, transport/, ci/, secrets/, agent_access/, wake_bus/) instead of 500-LOC-skeleton placeholder
New "Section 2 maintenance note" — discipline that future PRs evolving paths must update the description in the same PR

Why

Per DeepSeek deep review: future cousins reading charter as onboarding doc calibrate their mental model to it. When charter lies ("skeleton" when reality is full package; "auto-generated" when nothing auto-generates), cousins build wrong expectations — then re-investigate the drift in subsequent sessions.

Tier

Trivial per ADR-0007 — docs-only, no code / schema / runtime / sacred-path mutation.

Refs DeepSeek deep review 2026-05-14 finding #5 (state/deep-reviews/2026-05-14-platform-deep-review.md)

## Summary DeepSeek deep review 2026-05-14, finding #5: `PLATFORM_CHARTER.md` §2 described `platformctl` as "~500 LOC Python skeleton" while reality is a working multi-module Python package. Also described `prompts/` as 6 phase prompts when directory has grown into active dispatch surface, and annotated `INDEX.yaml` as "auto-generated" without any actual generator. Per DeepSeek: **charter/reality drift is exactly the agent-misleading-signal failure mode ADR-0018 was written to prevent**, applied to the platform's own onboarding document. ## What changed - `modules/` section: `"auto-generated"` → `"generated via platformctl index generate; refreshed in CI on push to main"` (anticipates D-1 INDEX regen prebuild) - `prompts/` section: reflects actual contents (execution prompts + one-shot dispatches) instead of phase 01-06 list; archive note for historical phase prompts - `control-plane/platformctl/` section: reflects actual submodules (`cli`, `validate`, `plan`, `apply`, `health`, `wip`, `safety`, `identity/`, `tools/`, `transport/`, `ci/`, `secrets/`, `agent_access/`, `wake_bus/`) instead of 500-LOC-skeleton placeholder - New **"Section 2 maintenance note"** — discipline that future PRs evolving paths must update the description in the same PR ## Why Per DeepSeek deep review: future cousins reading charter as onboarding doc calibrate their mental model to it. When charter lies ("skeleton" when reality is full package; "auto-generated" when nothing auto-generates), cousins build wrong expectations — then re-investigate the drift in subsequent sessions. ## Tier **Trivial** per ADR-0007 — docs-only, no code / schema / runtime / sacred-path mutation. Refs DeepSeek deep review 2026-05-14 finding #5 (state/deep-reviews/2026-05-14-platform-deep-review.md)

claude added 1 commit

2026-05-17 17:48:37 +02:00

docs(charter): update §2 to reality (DeepSeek 2026-05-14 finding #5 )

base-is-main / guard (pull_request) Successful in 1s

Details

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

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 3s

Details

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

Details

patchwarden-pr-sanity / sanity (pull_request) Failing after 18s

Details

ffbbf4a5a4

DeepSeek deep review: PLATFORM_CHARTER.md §2 described platformctl
as "~500 LOC Python skeleton" while reality is a working multi-module
Python package driving auto-apply pipeline end-to-end. Charter also
described prompts/ as 6 phase prompts when directory has grown into
the active dispatch surface for codex/glm/iskra/deepseek coordination.
INDEX.yaml was annotated "auto-generated" with no actual generator.

Per DeepSeek: charter/reality drift is exactly the agent-misleading-
signal failure mode ADR-0018 was written to prevent — applied to the
platform's own onboarding document.

Changes:
- modules/ section: "auto-generated" → honest "generated via
  platformctl index generate; refreshed in CI on push to main"
  (anticipates D-1 INDEX regen prebuild)
- prompts/ section: reflect actual contents (execution prompts +
  one-shot dispatches) instead of phase 01-06 list; archive note
  for historical phase prompts
- control-plane/platformctl/ section: reflect actual submodules
  (cli, validate, plan, apply, health, wip, safety, identity, tools,
  transport, ci, secrets, agent_access, wake_bus) instead of 500-LOC-
  skeleton placeholder
- New "Section 2 maintenance note" — discipline that future PRs
  evolving paths must update the description in the same PR

Tier: Trivial per ADR-0007 (docs-only, no code/schema/runtime change).

Refs DeepSeek deep review 2026-05-14 finding #5
(state/deep-reviews/2026-05-14-platform-deep-review.md)

claude referenced this pull request from a commit

2026-05-17 17:50:47 +02:00

docs(repo): deprecate stale INDEX.md, redirect to living entry points

claude referenced this pull request

2026-05-17 17:51:04 +02:00

docs(repo): deprecate stale INDEX.md, redirect to living entry points #333

claude referenced this pull request from a commit

2026-05-18 08:20:32 +02:00

decisions(0021): DDD bounded contexts for pdurlej/platform monorepo

codex referenced this pull request

2026-05-27 08:45:08 +02:00

docs(w9): rewrite stale charter topology #517

codex commented

2026-05-27 08:45:25 +02:00

Collaborator

W9 rewrite/archive triage: closing this stale branch because the useful part was rewritten from current main in #517. The old branch carried extra stale Spec Kit material and conflicts; #517 keeps the focused charter/topology fix.

codex closed this pull request

2026-05-27 08:45:26 +02:00