Add workplans for the arc42 collection and ADR review
WP-0002 names the first-wave architecture documents and the markitect/infospace split. WP-0003 reviews the inventoried ADRs for conflicts, then publishes what still governs.
This commit is contained in:
parent
45c464e1bc
commit
7a24e9107f
3 changed files with 594 additions and 0 deletions
|
|
@ -9,9 +9,25 @@
|
|||
| Kind | ID | Status | Lane | Source |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| workplan | POLICY-NEXUS-WP-0001 | finished | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| workplan | POLICY-NEXUS-WP-0002 | proposed | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| workplan | POLICY-NEXUS-WP-0003 | proposed | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T01 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T02 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T03 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T04 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T05 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0001-T06 | done | — | workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T01 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T02 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T03 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T04 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T05 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T06 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0002-T07 | todo | — | workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T01 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T02 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T03 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T04 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T05 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T06 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
| task | POLICY-NEXUS-WP-0003-T07 | todo | — | workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md |
|
||||
|
|
|
|||
290
workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md
Normal file
290
workplans/POLICY-NEXUS-WP-0002-arc42-architecture-collection.md
Normal file
|
|
@ -0,0 +1,290 @@
|
|||
---
|
||||
id: POLICY-NEXUS-WP-0002
|
||||
type: workplan
|
||||
title: "Publish an arc42 architecture collection from owning repos"
|
||||
domain: infotech
|
||||
repo: policy-nexus
|
||||
status: proposed
|
||||
owner: the-custodian
|
||||
topic_slug: policy-nexus
|
||||
created: "2026-08-18"
|
||||
updated: "2026-08-18"
|
||||
depends_on_workplans:
|
||||
- POLICY-NEXUS-WP-0001
|
||||
---
|
||||
|
||||
# POLICY-NEXUS-WP-0002 — arc42 architecture collection
|
||||
|
||||
## Goal
|
||||
|
||||
Give the estate a countable set of **arc42 architecture documents** — one
|
||||
document per system — authored where the system is owned, checked by the
|
||||
markdown tooling we already have, retrievable as an infospace, and published
|
||||
at permanent addresses on `policy.coulomb.social`.
|
||||
|
||||
Done means: a reader can open the estate map and the first-wave system
|
||||
documents, see which ADRs belong to each, tell whether a document is current,
|
||||
and validate a new architecture page the same way as the existing ones.
|
||||
|
||||
## Why this workplan exists
|
||||
|
||||
WP-0001 made the publication surface. The inventory behind it is almost all
|
||||
**decisions** (ADRs) and almost no **architecture**. A decision log without a
|
||||
system description is a pile of answers with no question. The ADRs that
|
||||
WP-0003 will keep need something to be consistent *with*.
|
||||
|
||||
The tooling is already here. Do not start a new documentation stack.
|
||||
|
||||
- `markitect-main/examples/templates/TEMPLATE-ARC42.md` is a complete 12-chapter
|
||||
arc42 template plus a quality checklist.
|
||||
- `markitect validate` already checks a markdown file against a schema.
|
||||
- `markitect infospace` already init/check/entities/graph an infospace.
|
||||
- `info-tech-canon` owns the *information-space model*, not estate
|
||||
architecture (ADR-006).
|
||||
- `the-custodian/canon/architecture/` currently holds estate ADRs only.
|
||||
|
||||
The `arc42-v1` entry in Markitect's schema catalog is still a comment. That
|
||||
is a handoff to `markitect-main`, not a reason to invent another format.
|
||||
|
||||
## The collection (first wave)
|
||||
|
||||
One markdown document per system, not twelve files per system. Chapter 9 is
|
||||
the ADR index for that system; the ADRs themselves stay in `docs/adr/` and
|
||||
are published separately.
|
||||
|
||||
| id | System | Owning repo | Path | Why first |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `coulomb-estate-architecture` | Coulomb estate | `the-custodian` | `canon/architecture/coulomb-estate_v0.1.md` | The map. Canons, hubs, rails, publication. Chapter 9 indexes custodian ADR-001–011. |
|
||||
| `railiance-architecture` | Railiance | `railiance-master` | `docs/architecture/railiance_v0.1.md` | Runtime substrate. Eight ADRs there already have publication-grade front-matter. |
|
||||
| `net-kingdom-architecture` | NetKingdom | `net-kingdom` | `docs/architecture/net-kingdom_v0.1.md` | Identity and tenancy. Tenancy Posture is already published; this is the system around it. |
|
||||
| `state-hub-architecture` | State Hub | `state-hub` | `docs/architecture/state-hub_v0.1.md` | Coordination read-model. ADR-001 lives here in spirit. |
|
||||
| `policy-nexus-architecture` | Policy Nexus | `policy-nexus` | `docs/architecture/policy-nexus_v0.1.md` | This surface. The only first-wave document this repo may author. |
|
||||
|
||||
Later systems (Markitect, activity-core, flex-auth, artifact-store) join the
|
||||
same way: owning repo writes the document, this repo adds a manifest entry.
|
||||
They are out of this workplan.
|
||||
|
||||
## Tooling split (resolved)
|
||||
|
||||
Use **both**, with a hard split. "Markdown tooling or infospace" is not a
|
||||
choice between two products; they already compose.
|
||||
|
||||
| Concern | Tool | What it does |
|
||||
| --- | --- | --- |
|
||||
| Shape and compliance | Markitect `TEMPLATE-ARC42.md` + `arc42-v1` schema | A document is valid arc42 or it is not. `markitect validate` is the gate. |
|
||||
| Retrieval of the collection | An infospace index | `infospace.yaml` binds the five documents as entities so an agent can list systems, open a chapter, and follow relations. |
|
||||
| Publication | This repo | `publication.json` entries under `architecture/<system>/v0.1/`. |
|
||||
|
||||
The infospace index lives in `the-custodian/canon/architecture/infospace/`
|
||||
because the-custodian owns estate architecture. It **points at** the owning
|
||||
repos; it does not copy them. InfoTechCanon is not the host — it owns the
|
||||
model (`ITC-INFOSPACE`), not this estate's building-block view.
|
||||
|
||||
This repo still does not write other repos. Content PRs land in the owning
|
||||
repo. This workplan coordinates and then publishes.
|
||||
|
||||
## Addressing
|
||||
|
||||
Follow ADR-0001:
|
||||
|
||||
```text
|
||||
/architecture/<system>/v0.1/
|
||||
/architecture/<system>/v0.1/revisions/<revision>/
|
||||
```
|
||||
|
||||
`<system>` is the kebab slug from the table (`coulomb-estate`, `railiance`,
|
||||
`net-kingdom`, `state-hub`, `policy-nexus`). A new major version is a new
|
||||
document id and a new current address; the old current address becomes a
|
||||
superseded banner, not a delete.
|
||||
|
||||
Required publication front-matter is the same contract as for ADRs: `id`,
|
||||
`title`, `status`, `owner`, `revision` or `version`, `last_reviewed` or
|
||||
`updated`, and `review_interval`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No CMS, no generated-from-code architecture that diverges from the source
|
||||
markdown.
|
||||
- No twelve-file-per-system split in this workplan. If a chapter later needs
|
||||
its own page, that is a new addressing decision.
|
||||
- No attempt to finish every chapter to production depth. A first-wave
|
||||
document is useful when chapters 1, 3, 4, 5.1, 9 and 12 are real, and
|
||||
every other chapter is either real or explicitly `N/A` with a reason.
|
||||
- No rewrite of InfoTechCanon's landscape model into arc42. Landscape
|
||||
concepts stay in `info-tech-canon`; these documents describe *our*
|
||||
systems.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 — Collection contract
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Write the contract this workplan just stated so a source owner can comply
|
||||
without reading the builder.
|
||||
|
||||
- Address shape, id scheme, front-matter fields, review interval default
|
||||
(`6m` unless the owner declares otherwise).
|
||||
- One document per system; chapter 9 lists ADRs, it does not inline them.
|
||||
- Infospace index location and the rule that it references, never copies.
|
||||
- What "first-wave complete" means (chapters 1, 3, 4, 5.1, 9, 12 real;
|
||||
others real or N/A).
|
||||
|
||||
**Output:** a short owner-facing note in this repo (publication contract,
|
||||
not a second architecture). Fold the addressing into ADR-0001 only if the
|
||||
`architecture` kind needs an amendment; otherwise keep it here.
|
||||
|
||||
**Why first:** WP-0003's relevance and conflict checks need to know what an
|
||||
architecture document is.
|
||||
|
||||
### T02 — Markitect arc42 schema handoff
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Make `markitect validate doc.md --schema arc42-v1` work against
|
||||
`TEMPLATE-ARC42.md`.
|
||||
|
||||
- Promote the commented `arc42-v1` catalog entry in
|
||||
`markitect-main/markitect/schemas/schema-catalog.yaml`.
|
||||
- Derive the schema from the existing template (12 required chapters;
|
||||
checklist chapter 13 recommended).
|
||||
- Record the command a source owner runs before asking this repo to
|
||||
publish.
|
||||
|
||||
Implementation lands in `markitect-main`. If that is more than a small PR,
|
||||
spawn a Markitect workplan and depend on it. Do not reimplement validation
|
||||
here.
|
||||
|
||||
### T03 — Infospace index
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T03
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Stand up `the-custodian/canon/architecture/infospace/` with `infospace.yaml`
|
||||
that binds the first-wave documents as the topic "Coulomb estate
|
||||
architecture", using arc42 as the discipline.
|
||||
|
||||
- `markitect infospace init` then `check` must pass once at least the
|
||||
estate document exists.
|
||||
- Entities are systems (and, if cheap, chapters). Relations are
|
||||
`described-by` / `decided-in` toward published ADRs, not a second copy
|
||||
of ADR text.
|
||||
- This repo adds the infospace only as a *source to publish* if the
|
||||
custodian owner marks the index itself as governing. The five system
|
||||
documents are the publication corpus; the index is navigation.
|
||||
|
||||
Depends on T01. Can start as soon as the estate document path is fixed,
|
||||
even as a stub.
|
||||
|
||||
### T04 — First document: Coulomb estate
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T04
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Author `the-custodian/canon/architecture/coulomb-estate_v0.1.md` in
|
||||
the-custodian.
|
||||
|
||||
Chapters 1, 3, 4, 5.1, 9 and 12 must be real. Chapter 9 lists the estate
|
||||
ADRs already in `canon/architecture/` with status and a pointer, not a
|
||||
paste. Remaining chapters are real or N/A with a reason. Front-matter must
|
||||
satisfy T01 so this repo can publish it.
|
||||
|
||||
This is the document WP-0003 checks other ADRs against when the conflict
|
||||
is "this decision does not fit the estate".
|
||||
|
||||
### T05 — Remaining first-wave stubs in owning repos
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Open the four remaining documents in their owning repos, each valid against
|
||||
`arc42-v1` and carrying publication front-matter.
|
||||
|
||||
A stub that has a real chapter 1 (why the system exists), chapter 3 (scope
|
||||
and neighbours), and chapter 9 (ADR index, even if short) is enough to
|
||||
publish. Deeper chapters are the owning repo's follow-on, not a gate here.
|
||||
|
||||
This repo authors only `docs/architecture/policy-nexus_v0.1.md`.
|
||||
|
||||
### T06 — Register and publish
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T06
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
- Extend `source-inventory.config.json` selectors so
|
||||
`canon/architecture/*.md` and `docs/architecture/*.md` in the first-wave
|
||||
repos are inventoried (ADRs stay on their existing selectors).
|
||||
- Add explicit `publication.json` entries for every first-wave document
|
||||
that meets T01.
|
||||
- Add the owning repos to `publication.json` `repositories` as needed.
|
||||
- Refresh `source-inventory.json` dispositions.
|
||||
- `make check` and `make build` pass; currency is declared.
|
||||
|
||||
Do not glob the new trees into publication. Inventory is discovered;
|
||||
publication stays explicit.
|
||||
|
||||
### T07 — Smoke the published collection
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0002-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
After promotion (same paired digest review as WP-0001): the index lists
|
||||
every first-wave architecture document; each current URL resolves; each
|
||||
revision URL is write-once; a `markitect validate` failure in a source repo
|
||||
is visible as a missing or stale publication, not as a silently old page.
|
||||
|
||||
## Sequencing
|
||||
|
||||
T01 gates everything. T02 and T04 can proceed in parallel once T01 is
|
||||
written. T03 needs T01 and becomes useful once T04 exists. T05 can proceed
|
||||
per repo as soon as T02 has a schema to validate against. T06 needs at
|
||||
least T04 (estate document) to be worth running; it may publish the others
|
||||
as they land. T07 is last.
|
||||
|
||||
WP-0003 may start its corpus inventory immediately. Its conflict-against-
|
||||
architecture pass waits on T04. Linking published ADRs into chapter 9 waits
|
||||
on T05/T06.
|
||||
|
||||
## Risks
|
||||
|
||||
**This repo authors the estate.** Mitigation: only `policy-nexus`'s own
|
||||
arc42 is written here. Everything else is a PR in the owning repo.
|
||||
|
||||
**The infospace becomes a second copy.** Mitigation: the index stores
|
||||
references and slugs, not document bodies.
|
||||
|
||||
**arc42 becomes a novel.** Mitigation: first-wave complete is six real
|
||||
chapters, not twelve essays.
|
||||
|
||||
**Schema work stalls in markitect.** Mitigation: T04 can be authored
|
||||
against the template before `arc42-v1` is registered; T06 will not publish
|
||||
a document that cannot be validated once T02 is done.
|
||||
|
||||
## Residuals
|
||||
|
||||
- Later-wave systems get their own owning-repo work, then a publication
|
||||
entry here. Not a third policy-nexus workplan until there is a batch.
|
||||
- WP-0003 owns ADR cleanup and ADR publication.
|
||||
288
workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md
Normal file
288
workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md
Normal file
|
|
@ -0,0 +1,288 @@
|
|||
---
|
||||
id: POLICY-NEXUS-WP-0003
|
||||
type: workplan
|
||||
title: "Review ADRs for conflict, keep what governs, publish the rest properly"
|
||||
domain: infotech
|
||||
repo: policy-nexus
|
||||
status: proposed
|
||||
owner: the-custodian
|
||||
topic_slug: policy-nexus
|
||||
created: "2026-08-18"
|
||||
updated: "2026-08-18"
|
||||
depends_on_workplans:
|
||||
- POLICY-NEXUS-WP-0001
|
||||
- POLICY-NEXUS-WP-0002
|
||||
---
|
||||
|
||||
# POLICY-NEXUS-WP-0003 — ADR review, cleanup, publish
|
||||
|
||||
## Goal
|
||||
|
||||
Walk the inventoried ADR corpus, find conflicts and inconsistencies, drop
|
||||
what no longer governs, and give every remaining ADR the metadata and
|
||||
address it needs to be published on `policy.coulomb.social`.
|
||||
|
||||
Done means: every inventoried ADR has a reviewed disposition; the ones
|
||||
that still govern have publication-grade front-matter in their owning
|
||||
repo, a `publication.json` entry here, a current URL, an immutable
|
||||
revision URL, and a pointer from the matching first-wave arc42 chapter 9.
|
||||
|
||||
## Why this workplan exists
|
||||
|
||||
WP-0001 inventoried 124 sources and published one. Of the rest, **113
|
||||
ADRs and canon files sit at `metadata-pending`**. A first pass over that
|
||||
inventory (2026-08-18) found:
|
||||
|
||||
| State | Count |
|
||||
| --- | --- |
|
||||
| Already published | 1 (Tenancy Posture) |
|
||||
| Publication-ready front-matter, not yet registered | 8 (all `railiance-master`) |
|
||||
| YAML front-matter but missing owner / revision / review | ~56 |
|
||||
| No front-matter | 49 |
|
||||
| Directory indexes, excluded | 2 |
|
||||
| Non-Markdown, unsupported | 8 |
|
||||
|
||||
This repo's own ADR-0001 is in the "no front-matter" pile. Ids collide
|
||||
across repos (`ADR-001` means different decisions in coulomb-loop,
|
||||
flex-auth, activity-core, the-custodian). Some estate ADRs are already
|
||||
marked superseded in place (custodian ADR-008 → Tenancy Posture) while
|
||||
siblings still read as current.
|
||||
|
||||
Publishing that pile as-is would freeze the conflicts. Cleaning without a
|
||||
protocol would invent authority this repo does not have.
|
||||
|
||||
## Authority
|
||||
|
||||
Unchanged from WP-0001.
|
||||
|
||||
- **Owning repo** decides whether an ADR still governs, and writes the
|
||||
cleanup (front-matter, successor links, status).
|
||||
- **the-custodian** decides what counts as estate-level canon.
|
||||
- **This repo** reviews, records the review, and publishes. It does not
|
||||
edit another repo's ADR body.
|
||||
|
||||
A "cleanup packet" is a per-repo note this workplan produces. The owning
|
||||
repo applies it.
|
||||
|
||||
## Review protocol
|
||||
|
||||
Every inventoried ADR (and every in-scope canon file that is not already
|
||||
`published`) gets exactly one of:
|
||||
|
||||
| Disposition | Meaning | Publication |
|
||||
| --- | --- | --- |
|
||||
| `publish` | Still governs. Front-matter complete. Register it. | `publication.json` entry |
|
||||
| `superseded` | Replaced. Keep the source, point at the successor, publish *as superseded* so the old URL never 404s once it has been public. Unpublished superseded ADRs stay in the inventory as `excluded` with that reason until someone needs the historical URL. | only if a public URL already exists or the successor needs the pointer live |
|
||||
| `withdrawn` | No longer governs, no successor. Same retention rule as ADR-0001. | same as superseded |
|
||||
| `local` | Useful in its repo, not governing for anyone else. Out of this site. | inventory `excluded` |
|
||||
| `conflict` | Contradicts another ADR or the estate arc42, and the owner has not ruled. Stays `metadata-pending` with the conflict recorded. Not published. | no |
|
||||
|
||||
Conflict kinds this pass must look for:
|
||||
|
||||
1. **Identifier collision** — same `id` or same `ADR-NNNN` in two repos.
|
||||
Publication ids must be globally unique (repo-prefixed, as
|
||||
`RMASTER-ADR-0001` already is).
|
||||
2. **Status lie** — body says superseded/relocated, front-matter still
|
||||
`accepted` (or the reverse).
|
||||
3. **Missing successor** — status `superseded` with no target.
|
||||
4. **Contradicting decisions** — two accepted ADRs that cannot both be
|
||||
true (example class: "hub is source of truth" vs custodian ADR-001).
|
||||
5. **Architecture miss** — an accepted ADR that the matching first-wave
|
||||
arc42 does not mention in chapter 9, or that chapter 9 lists with the
|
||||
wrong status. This check waits on WP-0002-T04 (estate) and T05 (other
|
||||
systems).
|
||||
6. **Duplicate claim** — two documents claiming to be the current
|
||||
decision on the same question (custodian ADR-008 vs Tenancy Posture is
|
||||
the known case; treat it as the template).
|
||||
|
||||
Evidence for each review is a row in a review ledger this repo owns
|
||||
(`docs/adr-review/` or equivalent). The ledger is a work artefact, not a
|
||||
published policy document.
|
||||
|
||||
## First publish set (already ready or nearly so)
|
||||
|
||||
Do these as soon as T01 exists; do not wait for the full corpus pass.
|
||||
|
||||
1. **policy-nexus ADR-0001** — add front-matter here, then register it.
|
||||
This repo eating its own contract is the rehearsal for everyone else.
|
||||
2. **railiance-master ADR-0001–0008** — already have `id`, `title`,
|
||||
`status`, `owner`, `revision`, `last_reviewed`, `review_interval`.
|
||||
Register them once T01's id/address scheme is applied.
|
||||
|
||||
Everything else waits on the review row.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No silent rewrite of other repos.
|
||||
- No State Hub `/decisions` registration. That API is for open work
|
||||
choices; these files are architecture records.
|
||||
- No requirement that every remaining ADR become an essay. Cleanup is
|
||||
metadata, status honesty, and successor links. Content rewrites stay
|
||||
with the owner.
|
||||
- No publication of `local` ADRs "for completeness".
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 — Review protocol and ledger
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Write the protocol above into a working ledger format: one row per
|
||||
inventory source, with proposed disposition, conflict kind (if any),
|
||||
successor, required front-matter gaps, and owning repo.
|
||||
|
||||
Use `source-inventory.json` as the input set. Do not rediscover by glob.
|
||||
|
||||
**Output:** `docs/adr-review/` (ledger + protocol). Not published.
|
||||
|
||||
### T02 — Corpus map
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Fill the ledger from the files as they are, without yet ruling
|
||||
relevance.
|
||||
|
||||
- Group by owning repo.
|
||||
- Record existing front-matter vs the publication contract from
|
||||
WP-0002-T01 / ADR-0001.
|
||||
- Flag identifier collisions and missing files.
|
||||
- Note already-known specials: this repo's ADR-0001; the eight
|
||||
railiance-master ADRs; custodian ADR-008 relocated to Tenancy Posture.
|
||||
|
||||
Depends on T01. Does not depend on WP-0002.
|
||||
|
||||
### T03 — Conflict and inconsistency pass
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T03
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Apply conflict kinds 1–4 (and 6) to the corpus map. Kind 5 waits on
|
||||
WP-0002-T04.
|
||||
|
||||
For each hit: record both sides, the contradiction in one sentence, and
|
||||
who must rule (owning repo, or the-custodian if the clash is
|
||||
estate-level). Do not resolve a custodian-level clash in this repo.
|
||||
|
||||
**Acceptance:** every `conflict` row is readable by the owning-repo
|
||||
agent that will have to act on it.
|
||||
|
||||
### T04 — Relevance filter
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T04
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Propose `publish` / `superseded` / `withdrawn` / `local` for every
|
||||
non-conflict row.
|
||||
|
||||
A `publish` ADR is one that still constrains at least one other repo, or
|
||||
that the matching first-wave arc42 needs in chapter 9. A `local` ADR is
|
||||
one whose audience is the producing repo only (implementation notes,
|
||||
tooling preferences with no cross-repo effect).
|
||||
|
||||
the-custodian reviews the estate-level proposals before this repo
|
||||
publishes them. Per-repo proposals go out in T05 packets.
|
||||
|
||||
Kind-5 (architecture miss) runs here once WP-0002-T04 exists, and again
|
||||
when T05 of that workplan lands a system document.
|
||||
|
||||
### T05 — Cleanup packets
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T05
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
For each owning repo with remaining work, write a packet: required
|
||||
front-matter, status/successor fixes, identifier prefix if the current
|
||||
`id` would collide on the site, and the list of ADRs this repo is
|
||||
prepared to publish once those land.
|
||||
|
||||
Deliver the packet as a message or a PR *checklist* in the owning repo,
|
||||
not as an edit of the ADR bodies. This repo applies the packet only for
|
||||
`policy-nexus` itself.
|
||||
|
||||
### T06 — Register the ready set
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T06
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
- Add publication front-matter to `docs/adr/ADR-0001-addressing-and-permanence.md`
|
||||
and a `publication.json` entry under
|
||||
`adr/addressing-and-permanence/v1/`.
|
||||
- Register the eight railiance-master ADRs (and any others that become
|
||||
ready during T05) with globally unique ids and ADR-0001 addresses
|
||||
(`/adr/<document>/<version>/`).
|
||||
- Add missing `publication.json` `repositories` entries.
|
||||
- Refresh inventory dispositions.
|
||||
- `make check` and `make build` pass.
|
||||
|
||||
Further registrations happen as packets return, still under this task
|
||||
until the ledger has no `publish` row left unpublished.
|
||||
|
||||
### T07 — Point the architecture documents at what remains
|
||||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Once WP-0002 has first-wave arc42 documents, chapter 9 of each must list
|
||||
every `publish` ADR for that system and must not list `local` or
|
||||
unresolved `conflict` rows as current.
|
||||
|
||||
This is a PR in the owning repo of the arc42 document, same as T05.
|
||||
Depends on WP-0002-T04/T05 and on this workplan's T04.
|
||||
|
||||
## Sequencing
|
||||
|
||||
T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).
|
||||
T06's first two bullets (this repo's ADR-0001, railiance-master) can
|
||||
run as soon as T01 has the address/id rule — they are already
|
||||
relevance-obvious.
|
||||
T05 follows T04. T07 is last.
|
||||
|
||||
Do not block the first publish set on finishing the 113-row pass.
|
||||
|
||||
## Risks
|
||||
|
||||
**The review becomes a rewrite of the estate.** Mitigation: dispositions
|
||||
and metadata, not new architecture. New architecture is WP-0002.
|
||||
|
||||
**Conflicts linger unpublished and unread.** Mitigation: `conflict` rows
|
||||
are a first-class ledger state and a cleanup-packet item, not a silent
|
||||
`metadata-pending`.
|
||||
|
||||
**Identifier prefixes paint over history.** Mitigation: the source
|
||||
filename does not have to change; only the publication `id` and URL
|
||||
slug must be unique. Record the original filename in the ledger.
|
||||
|
||||
**This repo publishes a local ADR because the filter is timid.**
|
||||
Mitigation: T04's default for "no cross-repo effect" is `local`, not
|
||||
`publish`.
|
||||
|
||||
## Residuals
|
||||
|
||||
- Unresolved `conflict` rows after owner silence become an intake on
|
||||
the-custodian, not a third policy-nexus workplan, unless a new batch
|
||||
of publications is ready.
|
||||
- Later-wave architecture documents (WP-0002 residual) pick up new ADR
|
||||
indexes under the same protocol.
|
||||
Loading…
Add table
Add a link
Reference in a new issue