diff --git a/.forgejo/workflows/publish-image.yaml b/.forgejo/workflows/publish-image.yaml index 9b572cf..4011105 100644 --- a/.forgejo/workflows/publish-image.yaml +++ b/.forgejo/workflows/publish-image.yaml @@ -1,5 +1,5 @@ -# Uses the estate's tier-2 container-build runner and organization-scoped -# REGISTRY_USER / REGISTRY_TOKEN secrets. +# Uses the estate's tier-2 container-build runner, a dedicated repository-read +# FORGEJO_SOURCE_TOKEN, and package-write REGISTRY_USER / REGISTRY_TOKEN. name: Build and publish policy-nexus image on: @@ -25,8 +25,12 @@ concurrency: group: policy-nexus-publication cancel-in-progress: false +permissions: + contents: read + env: REGISTRY: forgejo.coulomb.social + FORGEJO_ORIGIN: https://forgejo.coulomb.social IMAGE_NAME: coulomb/policy-nexus DOCKER_HOST: tcp://127.0.0.1:2375 @@ -36,12 +40,17 @@ jobs: steps: - name: Build, verify, and publish immutable policy artifact env: + FORGEJO_SOURCE_TOKEN: ${{ secrets.FORGEJO_SOURCE_TOKEN }} REGISTRY_USER: ${{ secrets.REGISTRY_USER }} REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }} run: | set -eu REF="${GITHUB_SHA:-}" test "${#REF}" -eq 40 + if [ -z "${FORGEJO_SOURCE_TOKEN:-}" ]; then + echo "FORGEJO_SOURCE_TOKEN is required for private source repositories" >&2 + exit 2 + fi SHORT="${REF:0:7}" BUILD_ROOT="$(mktemp -d)" PYTHON_CONTAINER="" @@ -56,7 +65,8 @@ jobs: mkdir -p "${BUILD_CONTEXT}" "${HOME}/bin" wget -qO "${BUILD_ROOT}/policy-nexus.tar.gz" \ - "https://forgejo.coulomb.social/${GITHUB_REPOSITORY}/archive/${SHORT}.tar.gz" + --header="Authorization: token ${FORGEJO_SOURCE_TOKEN}" \ + "${FORGEJO_ORIGIN}/${GITHUB_REPOSITORY}/archive/${REF}.tar.gz" tar xzf "${BUILD_ROOT}/policy-nexus.tar.gz" \ -C "${BUILD_CONTEXT}" --strip-components=1 @@ -69,11 +79,14 @@ jobs: docker create --name "${PYTHON_CONTAINER}" "${PYTHON_IMAGE}" sleep 300 docker cp "${BUILD_CONTEXT}/." "${PYTHON_CONTAINER}:/workspace" docker start "${PYTHON_CONTAINER}" - docker exec --workdir /workspace "${PYTHON_CONTAINER}" \ + docker exec --workdir /workspace \ + --env FORGEJO_SOURCE_TOKEN "${PYTHON_CONTAINER}" \ python3 tools/fetch_sources.py \ --config source-inventory.config.json \ --destination _sources \ - --policy-revision "${REF}" + --policy-revision "${REF}" \ + --token-env FORGEJO_SOURCE_TOKEN \ + --token-origin "${FORGEJO_ORIGIN}" NETKINGDOM_REVISION="$(docker exec "${PYTHON_CONTAINER}" python3 -c 'import json; print(json.load(open("/workspace/_sources/source-lock.json"))["repositories"]["net-kingdom"]["revision"])')" SOURCE_SET_DIGEST="$(docker exec "${PYTHON_CONTAINER}" python3 -c 'import json; print(json.load(open("/workspace/_sources/source-lock.json"))["source_set_digest"])')" docker cp "${PYTHON_CONTAINER}:/workspace/_sources" "${BUILD_CONTEXT}/" diff --git a/build/adr/addressing-and-permanence/v1/index.html b/build/adr/addressing-and-permanence/v1/index.html index 25607cc..ac3df5e 100644 --- a/build/adr/addressing-and-permanence/v1/index.html +++ b/build/adr/addressing-and-permanence/v1/index.html @@ -1,6 +1,6 @@ - + Policy addressing and permanence -
policy-nexus-adr-0001 accepted · accepted-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy addressing and permanence

Source: policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599

Review due: 2027-02-18

  • Status: accepted
  • Date: 2026-08-18
  • Owner: the-custodian
+
policy-nexus-adr-0001 accepted · accepted-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy addressing and permanence

Source: policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 885c6bb1cb805b64cbcfa99dd2c5817f6d4a1373

Review due: 2027-02-18

  • Status: accepted
  • Date: 2026-08-18
  • Owner: the-custodian

Decision

A document has one stable current address and immutable revision addresses:

/<kind>/<document>/<version>/
@@ -211,4 +211,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • Builds fail if a source disappears, an id differs, a path collides, or an immutable revision would change; stale output is not silently called fresh.
  • Pages show status, revision, owner, last review and exact source revision.
  • Availability remains restart recovery on the single-node rail. This contract promises stable addressing, not a high-availability SLA.
-
policy-nexus-adr-0001 · accepted-1 · acceptedpolicy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599
+
diff --git a/build/adr/custodian-agent-runtime/v1/index.html b/build/adr/custodian-agent-runtime/v1/index.html index c98596f..40ca7c5 100644 --- a/build/adr/custodian-agent-runtime/v1/index.html +++ b/build/adr/custodian-agent-runtime/v1/index.html @@ -1,6 +1,6 @@ - + Custodian Agent Runtime — v0.1 Bootstrap Design -
CUST-ADR-002 accepted · accepted-1 the-custodian reviewed 2026-03-12generated from canonical source — do not edit

Custodian Agent Runtime — v0.1 Bootstrap Design

Source: the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2026-09-12

Status

+
CUST-ADR-002 accepted · accepted-1 the-custodian reviewed 2026-03-12generated from canonical source — do not edit

Custodian Agent Runtime — v0.1 Bootstrap Design

Source: the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2026-09-12

Status

Accepted.

Context

@@ -239,4 +239,4 @@ Act — Execute only sanctioned write operations from the plan

Deferred

  • Async event loop / daemon mode (Phase 2)
  • RAG over canon (Phase 1 roadmap item)
  • Tool adapters beyond state-hub HTTP (planned in runtime/tool_adapters/)
  • Deployment on Railiance k3s as a scheduled CronJob
-
CUST-ADR-002 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-canon-federation/v1/index.html b/build/adr/custodian-canon-federation/v1/index.html index 3ae319d..4bc6a00 100644 --- a/build/adr/custodian-canon-federation/v1/index.html +++ b/build/adr/custodian-canon-federation/v1/index.html @@ -1,6 +1,6 @@ - + Canon Federation and Concept Ownership Across InfoTech and Commerce -
CUST-ADR-006 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Canon Federation and Concept Ownership Across InfoTech and Commerce

Source: the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-17

Status

+
CUST-ADR-006 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Canon Federation and Concept Ownership Across InfoTech and Commerce

Source: the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-17

Status

Accepted 2026-08-17. All seven ownership questions are resolved (see Resolutions); content may now move under CFED-WP-0001.

Context

@@ -250,4 +250,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

References

  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-005 — cross-repo workplans live in dedicated project repos
  • info-tech-canon/infospace/models/organization/InfoTechCanonOrganizationModel.md:55
  • info-tech-canon/infospace/models/access-control/InfoTechCanonAccessControlModel.md:106, :214
  • info-tech-canon/infospace/models/governance/InfoTechCanonGovernanceModel.md:107
  • info-tech-canon/demand/CapabilityProvisionEconomics.md
  • identity-canon/canon/CanonicalGlossary.md, canon/DesignPrinciples.md
-
CUST-ADR-006 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-connectivity-first/v1/index.html b/build/adr/custodian-connectivity-first/v1/index.html index 520b81a..29979dd 100644 --- a/build/adr/custodian-connectivity-first/v1/index.html +++ b/build/adr/custodian-connectivity-first/v1/index.html @@ -1,6 +1,6 @@ - + Connectivity-First Network Posture for Custodian Infrastructure -
CUST-ADR-004 accepted · accepted-1 the-custodian reviewed 2026-03-26generated from canonical source — do not edit

Connectivity-First Network Posture for Custodian Infrastructure

Source: the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2026-09-26

Status

+
CUST-ADR-004 accepted · accepted-1 the-custodian reviewed 2026-03-26generated from canonical source — do not edit

Connectivity-First Network Posture for Custodian Infrastructure

Source: the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2026-09-26

Status

Accepted.

Context

@@ -233,4 +233,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Considered briefly. VPN would solve the connectivity problem but introduces a persistent network layer that all traffic traverses, reducing the explicitness of individual access paths. ops-bridge tunnels are per-service and per-actor, which gives better observability and blast-radius control. VPN is not ruled out as a future complement but is not the primary approach.

Ad-hoc SSH (no ops-bridge)

The pre-ops-bridge approach. Rejected because it has no health checks, no actor attribution, no audit log, and requires manual intervention to restore. ops-bridge formalises the same SSH tunnel pattern with operational discipline.

-
CUST-ADR-004 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-cross-repo-workplans/v1/index.html b/build/adr/custodian-cross-repo-workplans/v1/index.html index a019840..e59f533 100644 --- a/build/adr/custodian-cross-repo-workplans/v1/index.html +++ b/build/adr/custodian-cross-repo-workplans/v1/index.html @@ -1,6 +1,6 @@ - + Cross-Repo Workplans Live in Dedicated Project Repos -
CUST-ADR-005 accepted · accepted-1 the-custodian reviewed 2026-06-22generated from canonical source — do not edit

Cross-Repo Workplans Live in Dedicated Project Repos

Source: the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2026-12-22

Status

+
CUST-ADR-005 accepted · accepted-1 the-custodian reviewed 2026-06-22generated from canonical source — do not edit

Cross-Repo Workplans Live in Dedicated Project Repos

Source: the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2026-12-22

Status

Accepted.

Context

@@ -222,4 +222,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
CUST-ADR-005 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-federated-namespaces/v1/index.html b/build/adr/custodian-federated-namespaces/v1/index.html index cd6cb05..83be492 100644 --- a/build/adr/custodian-federated-namespaces/v1/index.html +++ b/build/adr/custodian-federated-namespaces/v1/index.html @@ -1,6 +1,6 @@ - + Federated Namespaces -
CUST-ADR-011 proposed · draft-2 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Federated Namespaces

Source: the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-17

Status

+
CUST-ADR-011 proposed · draft-2 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Federated Namespaces

Source: the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-17

Status

Proposed, draft-2. Amends ADR-007 decisions 1 and 2; extends ADR-010 decision 4; adopts the plane/ladder/posture form and the accuracy-not-altitude conformance rule from ADR-008 (Multi-Tenancy Framework).

Context

@@ -281,4 +281,4 @@ any participant below R2 -> T1 at best; manual thereafter

References

  • canon/standards/federated-organization-standard_v1.0.md — bounded autonomy, escalation, sovereignty by default, rebuildability
  • ADR-001 — workplans originate as repo files
  • ADR-007 — identifier uniqueness and derived identifiers (amended here)
  • ADR-008 — Multi-Tenancy Framework; source of the plane/ladder/posture form and the accuracy-not-altitude conformance rule
  • ADR-010 — hub authority, local cache, and the two kinds of hub data
  • CUST-WP-0058 — instance-per-client tenancy
  • SHR-INV-0001 — 425-item disposition inventory, T3 cost evidence
  • RMGR-WP-0004-T02 — rmgr conform, the guard machinery
-
CUST-ADR-011 · draft-2 · proposedthe-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-hub-authority/v1/index.html b/build/adr/custodian-hub-authority/v1/index.html index 1a241b5..3ac2bc3 100644 --- a/build/adr/custodian-hub-authority/v1/index.html +++ b/build/adr/custodian-hub-authority/v1/index.html @@ -1,6 +1,6 @@ - + Hub Authority, Local Cache, and the Two Kinds of Hub Data -
CUST-ADR-010 proposed · draft-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Hub Authority, Local Cache, and the Two Kinds of Hub Data

Source: the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-28

Status

+
CUST-ADR-010 proposed · draft-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Hub Authority, Local Cache, and the Two Kinds of Hub Data

Source: the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Status

Proposed, and partially superseded by ADR-012 (accepted 2026-08-25). Decisions 1, 5 and 6 are sharpened or given a mechanism there; see the notes on each below. Everything else in this ADR remains in force.

Context

@@ -250,4 +250,4 @@ same filename, different UUID 4 duplicate registration

Outcome (2026-08-28)

Added by CUST-WP-0068. The 2026-08-24 outcome closed the repository divergence. The work-record divergence this ADR originally measured — 955 local / 649 primary — remained, because the retired instance's database was still load-bearing. That is now closed.

  • Central holds 1167 workplans. Records that existed only in the cache were re-derived from their files, renamed onto the canonical scheme, or given a written disposition (docs/recovery/cache-only-disposition-2026-08-28.md).
  • No open work record exists only in the cache. Remaining cache-only slugs are aliases of recovered records, clay-borg product files (not workplans), or prefix-migration residue.
  • The cache database is discarded. Final dump ~/backups/state-hub-cache-2026-08-28.dump. Container infra-postgres-1 and volume infra_pg_data removed. Port 5432 is free.
  • The local instance is no longer load-bearing for any record type. Decision 3 is now true in operation, not only in argument.
-
CUST-ADR-010 · draft-2 · proposedthe-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-materialized-derived-state/v1/index.html b/build/adr/custodian-materialized-derived-state/v1/index.html index 633c164..7c6ff55 100644 --- a/build/adr/custodian-materialized-derived-state/v1/index.html +++ b/build/adr/custodian-materialized-derived-state/v1/index.html @@ -1,6 +1,6 @@ - + Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data -
CUST-ADR-003 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data

Source: the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-28

Status

+
CUST-ADR-003 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data

Source: the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Status

Accepted, and partially superseded by ADR-012 (accepted 2026-08-25). Decision 2's fingerprint composition is invalidated in part; decision 5's rebuild principle is given a concrete source and a required operation. See the notes on each.

Context

@@ -245,4 +245,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
CUST-ADR-003 · accepted-2 · acceptedthe-custodian · canon/architecture/adr-003-materialized-derived-state.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-projection-source-overlay/v1/index.html b/build/adr/custodian-projection-source-overlay/v1/index.html index 945ff34..aaa371b 100644 --- a/build/adr/custodian-projection-source-overlay/v1/index.html +++ b/build/adr/custodian-projection-source-overlay/v1/index.html @@ -1,6 +1,6 @@ - + What the Hub Projects -
CUST-ADR-012 accepted · 1.0 the-custodian reviewed 2026-08-25generated from canonical source — do not edit

What the Hub Projects

Source: the-custodian · canon/architecture/adr-012-projection-source-and-preliminary-overlay.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-25

Status

+
CUST-ADR-012 accepted · 1.0 the-custodian reviewed 2026-08-25generated from canonical source — do not edit

What the Hub Projects

Source: the-custodian · canon/architecture/adr-012-projection-source-and-preliminary-overlay.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-25

Status

Accepted 2026-08-25 by Bernd Worsch. Supersedes ADR-010 decision 1's phrase "authoritative as a reading of the repositories" by making the reading concrete, and implements decision 6's unbuilt notion of "preliminary".

Context

@@ -245,4 +245,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

References

  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-010 — hub authority, local cache, and the two kinds of hub data
  • ADR-007 — identifier uniqueness and derived identifiers
  • CUST-WP-0067 — hub target resolution; retired the impersonating local instance
  • CUST-WP-0068 — cache-only work-record recovery; surfaced the stale git_fingerprint and the duplicate registrations
  • Verification, 2026-08-25: central pod holds no repository files; sweep disabled; 117 repositories record a laptop path; the-custodian git_fingerprint is the initial commit while last_state_synced_at is current
-
CUST-ADR-012 · 1.0 · acceptedthe-custodian · canon/architecture/adr-012-projection-source-and-preliminary-overlay.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/adr/custodian-workplan-identity/v1/index.html b/build/adr/custodian-workplan-identity/v1/index.html index c86559b..80d32aa 100644 --- a/build/adr/custodian-workplan-identity/v1/index.html +++ b/build/adr/custodian-workplan-identity/v1/index.html @@ -1,6 +1,6 @@ - + Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology -
CUST-ADR-007 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology

Source: the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-28

Status

+
CUST-ADR-007 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology

Source: the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Status

Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle protection, and worker topology are settled.

Remediation of existing collisions (§ Migration) remains an open ruling. It is disruptive, touches six repositories, and no active work depends on it — all five duplicated identifiers are finished.

@@ -276,4 +276,4 @@ CUST-WP- the-custodian 50 plans

References

  • Decision 747011c6 — repository standards belong to Repo Manager
  • ADR-001 — workplans originate as repo files; hub is a read model
  • RMGR-WP-0004 — repository standards conformance and governed scaffolding
  • STATE-WP-0080 — register scaffolding handoff
  • Fleet scan 2026-08-16: 955 hub workplans, 525 parseable identifiers, 3 reused prefixes, 5 reused identifiers
-
+ diff --git a/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html b/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html index 6e3d524..77a778d 100644 --- a/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html +++ b/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html @@ -1,6 +1,6 @@ - + Workplans and Work Items Are Repository Artefacts -
CUST-ADR-001 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplans and Work Items Are Repository Artefacts

Source: the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-28

Status

+
CUST-ADR-001 accepted · accepted-2 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplans and Work Items Are Repository Artefacts

Source: the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Status

Accepted 2026-02-28.

Amended 2026-08-31 to distinguish file-backed work records from hub-native records, identify the Forge default branch as the central projection baseline, and align identity, lifecycle, reconciliation, and closure with ADR-007, ADR-010, ADR-011, ADR-012, and the work-record standards. The central decision is unchanged.

@@ -254,4 +254,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
+ diff --git a/build/architecture/coulomb-estate/v0.1/index.html b/build/architecture/coulomb-estate/v0.1/index.html index 67d9351..4e18fd1 100644 --- a/build/architecture/coulomb-estate/v0.1/index.html +++ b/build/architecture/coulomb-estate/v0.1/index.html @@ -1,6 +1,6 @@ - + Coulomb estate architecture -
coulomb-estate-architecture proposed · draft-3 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Coulomb estate architecture

Source: the-custodian · canon/architecture/coulomb-estate_v0.1.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b

Review due: 2027-02-28

About this document

+
coulomb-estate-architecture proposed · draft-3 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Coulomb estate architecture

Source: the-custodian · canon/architecture/coulomb-estate_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

About this document

This is the first-wave estate map. It describes how the Coulomb / Custodian estate is put together: canons, hubs, rails, and publication. System-level arc42 documents (Railiance, NetKingdom, State Hub, Policy Nexus) live in their owning repos. Chapter 9 lists estate ADRs; it does not paste them.

01Introduction and Goals

@@ -271,4 +271,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
EstateThe set of Coulomb / Custodian repos, canons, hubs, and rails.
CanonGoverning documents owned by one of the three federated canons.
Read modelA derived index. Never the origin of work or decisions.
Publication entryOne explicit object in policy-nexus publication.json.
First-wave completeChapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.
Project repoA prj-* repo that coordinates cross-repo work (ADR-005).
-
coulomb-estate-architecture · draft-3 · proposedthe-custodian · canon/architecture/coulomb-estate_v0.1.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b
+
diff --git a/build/architecture/policy-nexus/v0.1/index.html b/build/architecture/policy-nexus/v0.1/index.html index d141975..91b66d5 100644 --- a/build/architecture/policy-nexus/v0.1/index.html +++ b/build/architecture/policy-nexus/v0.1/index.html @@ -1,6 +1,6 @@ - + Policy Nexus architecture -
policy-nexus-architecture proposed · draft-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy Nexus architecture

Source: policy-nexus · docs/architecture/policy-nexus_v0.1.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599

Review due: 2027-02-18

About this document

+
policy-nexus-architecture proposed · draft-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy Nexus architecture

Source: policy-nexus · docs/architecture/policy-nexus_v0.1.md · 885c6bb1cb805b64cbcfa99dd2c5817f6d4a1373

Review due: 2027-02-18

About this document

This document follows the arc42 template for the publication surface at policy.coulomb.social. It is the first-wave architecture document this repository is allowed to author. Other first-wave systems are written in their owning repos.

01Introduction and Goals

@@ -245,4 +245,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
Current addressThe stable URL for the document as it now stands.
Revision addressWrite-once URL for one source digest.
Publication entryOne object in publication.json. Discovery is not publication.
First-wave completeChapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.
-
policy-nexus-architecture · draft-1 · proposedpolicy-nexus · docs/architecture/policy-nexus_v0.1.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599
+
diff --git a/build/architecture/state-hub/v0.1/index.html b/build/architecture/state-hub/v0.1/index.html index f450685..2d30d8f 100644 --- a/build/architecture/state-hub/v0.1/index.html +++ b/build/architecture/state-hub/v0.1/index.html @@ -1,6 +1,6 @@ - + State Hub architecture -
state-hub-architecture proposed · draft-3 state-hub reviewed 2026-08-31generated from canonical source — do not edit

State Hub architecture

Source: state-hub · docs/architecture/state-hub_v0.1.md · da30ce6723f9c5e6fdd994c78bb646986e819d3f

Review due: 2027-02-28

About this document

+
state-hub-architecture proposed · draft-3 state-hub reviewed 2026-08-31generated from canonical source — do not edit

State Hub architecture

Source: state-hub · docs/architecture/state-hub_v0.1.md · 0e35f84ad5f2f9397d76ffacb99f9973544f08ac

Review due: 2027-02-28

About this document

First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.

01Introduction and Goals

@@ -244,4 +244,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
Read modelDerived index; never the origin.
RegistrarThe single instance allowed to mint workplan UUIDs.
RetirementCoordinated move of capabilities out of this repo.
-
state-hub-architecture · draft-3 · proposedstate-hub · docs/architecture/state-hub_v0.1.md · da30ce6723f9c5e6fdd994c78bb646986e819d3f
+
diff --git a/build/index.html b/build/index.html index 5facc6c..ef95de9 100644 --- a/build/index.html +++ b/build/index.html @@ -183,4 +183,4 @@ footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-fam .route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px} a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px} @media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}} -
policy surfacegenerated from canonical sources — do not edit

Coulomb Policy Nexus

Canon and architecture decisions at stable addresses, with visible currency.

DocumentStatusLifecycleRevisionOwnerReviewedReview dueCurrency
NetKingdom Tenancy Posture v0.1proposedactivedraft-14net-kingdom2026-08-232027-02-23current
Coulomb estate architectureproposedactivedraft-3the-custodian2026-08-312027-02-28current
Railiance architectureproposedactivedraft-3railiance-master2026-08-312027-02-28current
NetKingdom architectureproposedactivedraft-3net-kingdom2026-08-312027-02-28current
State Hub architectureproposedactivedraft-3state-hub2026-08-312027-02-28current
Policy Nexus architectureproposedactivedraft-1the-custodian2026-08-182027-02-18current
Policy addressing and permanenceacceptedactiveaccepted-1the-custodian2026-08-182027-02-18current
Repository Prefix Architectureacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
Wave 1 rail-kubernetes Boundaryacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave rapp Selectionacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave reef Rolloutacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Derived Rail Compositionacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Reef Production Admissionacceptedactiveaccepted-2railiance-master2026-08-292027-02-28current
Rapp Declaration Contractacceptedactiveaccepted-2railiance-master2026-08-232027-02-23current
Private-by-default Exposureacceptedactiveaccepted-2railiance-master2026-08-292027-02-28current
Activity-Core as Coulomb Org Event Bridgeacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
Markdown-as-Definition Format for Event Types and ActivityDefinitionsacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
Rule vs. Instruction Model and Expression DSLacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Outputacceptedactiveaccepted-2activity-core2026-06-262026-12-26current
Ops runs vs development work records — claim queue and plane splitacceptedactiveaccepted-2activity-core2026-08-032027-02-03current
ADR-0001 — The routing catalog is a pointer layer, never a second copyacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0002 — ops-warden is a transparent conduit, never a secret brokeracceptedactive1ops-warden2026-08-182027-02-18current
ADR-0003 — Cover gaps, but never silently own themacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0004 — High-risk lanes refuse raw value streaming to agent sessionsacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0005 — Implement one lane narrowly, route everything elseacceptedactive1ops-warden2026-08-182027-02-18current
Workplans and Work Items Are Repository Artefactsacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Custodian Agent Runtime — v0.1 Bootstrap Designacceptedactiveaccepted-1the-custodian2026-03-122026-09-12current
Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Dataacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Connectivity-First Network Posture for Custodian Infrastructureacceptedactiveaccepted-1the-custodian2026-03-262026-09-26current
Cross-Repo Workplans Live in Dedicated Project Reposacceptedactiveaccepted-1the-custodian2026-06-222026-12-22current
Canon Federation and Concept Ownership Across InfoTech and Commerceacceptedactiveaccepted-1the-custodian2026-08-172027-02-17current
Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topologyacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Hub Authority, Local Cache, and the Two Kinds of Hub Dataproposedactivedraft-2the-custodian2026-08-312027-02-28current
Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliationproposedactivedraft-2the-custodian2026-08-172027-02-17current
ADR-0001 — S3 owns platform services, not the substrate beneath themacceptedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0002 — S3 owns the placement rule; the package repo owns the numberproposedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hubacceptedactive1.0railiance-platform2026-08-172027-02-17current
NetKingdom IAM Profile v0.3acceptedactiveaccepted-1net-kingdom2026-08-222027-02-22current
Recursive Multi-Tenant Identity and Authorization Architectureacceptedactive1net-kingdom2026-08-222027-02-22current
Security Orchestration Boundaryacceptedactive1net-kingdom2026-08-222027-02-22current
Object Storage STS Credential Vending Boundaryacceptedactive1net-kingdom2026-08-222027-02-22current
Orchestration vs Dependency, and Self-Coherent Intentacceptedactive1net-kingdom2026-08-222027-02-22current
NetKingdom IAM Profile Ownership And Version Governanceacceptedactive1net-kingdom2026-08-222027-02-22current
Playbook Capability Contract Ownershipacceptedactive1net-kingdom2026-08-222027-02-22current
Tenant Onboarding Grouping Taxonomyacceptedactive2net-kingdom2026-08-222027-02-22current
Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownershipacceptedactive1net-kingdom2026-08-222027-02-22current
NetKingdom Railiance Workload Packaging and Relational Platformacceptedactive1net-kingdom2026-08-222027-02-22current
k3s API is tunnel-onlyacceptedactiveaccepted-1railiance-infra2026-08-222027-02-22current
Profile-driven execution selection over the ops_run pull queueacceptedactiveaccepted-1activity-core2026-08-212027-02-21current
Code-registered bounded operations are the only local mutation exceptionacceptedactiveaccepted-1activity-core2026-08-232027-02-23current
ADR-0007 — Build-stage permissiveness stops at credential disclosureacceptedactive1ops-warden2026-08-192027-02-19current
ADR-0008 — A lane's risk grade covers every field its path disclosesacceptedactive1ops-warden2026-08-212027-02-21current
ADR-0009 — Adopt security-zones v0.1 as a consumeracceptedactive1ops-warden2026-08-222026-11-22current
ADR-0010 — ops-warden is Staff: lanes, not rules, and one declared engine gapacceptedactive1ops-warden2026-08-282026-11-28current
NetKingdom Security-Layer Interaction Boundaryacceptedactiveaccepted-1railiance-master2026-08-292027-02-28current
What the Hub Projects: Forge as Projection Source, Working Copies as Preliminary Overlayacceptedactive1.0the-custodian2026-08-252027-02-25current
NetKingdom Posture Feedback v0.1proposedactive0.1net-kingdom2026-08-232026-11-23current
NetKingdom Security Layer Model v0.7acceptedactive0.7gate-house2026-08-282026-11-28current
NetKingdom Security Scenario Composition v0.1proposedactive0.1net-kingdom2026-08-232026-11-23current
NetKingdom Security Zones v0.1proposedactive0.1zone-engine2026-08-222026-11-22current
+
policy surfacegenerated from canonical sources — do not edit

Coulomb Policy Nexus

Canon and architecture decisions at stable addresses, with visible currency.

DocumentStatusLifecycleRevisionOwnerReviewedReview dueCurrency
NetKingdom Tenancy Posture v0.1proposedactivedraft-14net-kingdom2026-08-232027-02-23current
Autonomy Lanes (Fleet) v0.1acceptedactiveaccepted-1the-custodian2026-08-312027-02-28current
Contribution Convention v0.1acceptedactiveaccepted-1the-custodian2026-08-312027-02-28current
Project Repository Flavor (prj-) v0.1acceptedactiveaccepted-1the-custodian2026-08-312027-02-28current
Work Record Types & Identity (Fleet) v0.1acceptedactiveaccepted-1the-custodian2026-08-312027-02-28current
Workplan Terminology (Fleet) v0.1acceptedactiveaccepted-1the-custodian2026-08-312027-02-28current
Coulomb estate architectureproposedactivedraft-3the-custodian2026-08-312027-02-28current
Railiance architectureproposedactivedraft-3railiance-master2026-08-312027-02-28current
NetKingdom architectureproposedactivedraft-3net-kingdom2026-08-312027-02-28current
State Hub architectureproposedactivedraft-3state-hub2026-08-312027-02-28current
Policy Nexus architectureproposedactivedraft-1the-custodian2026-08-182027-02-18current
Policy addressing and permanenceacceptedactiveaccepted-1the-custodian2026-08-182027-02-18current
Repository Prefix Architectureacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
Wave 1 rail-kubernetes Boundaryacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave rapp Selectionacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave reef Rolloutacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Derived Rail Compositionacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Reef Production Admissionacceptedactiveaccepted-2railiance-master2026-08-292027-02-28current
Rapp Declaration Contractacceptedactiveaccepted-2railiance-master2026-08-232027-02-23current
Private-by-default Exposureacceptedactiveaccepted-2railiance-master2026-08-292027-02-28current
Activity-Core as Coulomb Org Event Bridgeacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
Markdown-as-Definition Format for Event Types and ActivityDefinitionsacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
Rule vs. Instruction Model and Expression DSLacceptedactiveaccepted-2activity-core2026-05-142026-11-14current
The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Outputacceptedactiveaccepted-2activity-core2026-06-262026-12-26current
Ops runs vs development work records — claim queue and plane splitacceptedactiveaccepted-2activity-core2026-08-032027-02-03current
ADR-0001 — The routing catalog is a pointer layer, never a second copyacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0002 — ops-warden is a transparent conduit, never a secret brokeracceptedactive1ops-warden2026-08-182027-02-18current
ADR-0003 — Cover gaps, but never silently own themacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0004 — High-risk lanes refuse raw value streaming to agent sessionsacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0005 — Implement one lane narrowly, route everything elseacceptedactive1ops-warden2026-08-182027-02-18current
Workplans and Work Items Are Repository Artefactsacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Custodian Agent Runtime — v0.1 Bootstrap Designacceptedactiveaccepted-1the-custodian2026-03-122026-09-12current
Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Dataacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Connectivity-First Network Posture for Custodian Infrastructureacceptedactiveaccepted-1the-custodian2026-03-262026-09-26current
Cross-Repo Workplans Live in Dedicated Project Reposacceptedactiveaccepted-1the-custodian2026-06-222026-12-22current
Canon Federation and Concept Ownership Across InfoTech and Commerceacceptedactiveaccepted-1the-custodian2026-08-172027-02-17current
Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topologyacceptedactiveaccepted-2the-custodian2026-08-312027-02-28current
Hub Authority, Local Cache, and the Two Kinds of Hub Dataproposedactivedraft-2the-custodian2026-08-312027-02-28current
Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliationproposedactivedraft-2the-custodian2026-08-172027-02-17current
ADR-0001 — S3 owns platform services, not the substrate beneath themacceptedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0002 — S3 owns the placement rule; the package repo owns the numberproposedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hubacceptedactive1.0railiance-platform2026-08-172027-02-17current
NetKingdom IAM Profile v0.3acceptedactiveaccepted-1net-kingdom2026-08-222027-02-22current
Recursive Multi-Tenant Identity and Authorization Architectureacceptedactive1net-kingdom2026-08-222027-02-22current
Security Orchestration Boundaryacceptedactive1net-kingdom2026-08-222027-02-22current
Object Storage STS Credential Vending Boundaryacceptedactive1net-kingdom2026-08-222027-02-22current
Orchestration vs Dependency, and Self-Coherent Intentacceptedactive1net-kingdom2026-08-222027-02-22current
NetKingdom IAM Profile Ownership And Version Governanceacceptedactive1net-kingdom2026-08-222027-02-22current
Playbook Capability Contract Ownershipacceptedactive1net-kingdom2026-08-222027-02-22current
Tenant Onboarding Grouping Taxonomyacceptedactive2net-kingdom2026-08-222027-02-22current
Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownershipacceptedactive1net-kingdom2026-08-222027-02-22current
NetKingdom Railiance Workload Packaging and Relational Platformacceptedactive1net-kingdom2026-08-222027-02-22current
k3s API is tunnel-onlyacceptedactiveaccepted-1railiance-infra2026-08-222027-02-22current
Profile-driven execution selection over the ops_run pull queueacceptedactiveaccepted-1activity-core2026-08-212027-02-21current
Code-registered bounded operations are the only local mutation exceptionacceptedactiveaccepted-1activity-core2026-08-232027-02-23current
ADR-0007 — Build-stage permissiveness stops at credential disclosureacceptedactive1ops-warden2026-08-192027-02-19current
ADR-0008 — A lane's risk grade covers every field its path disclosesacceptedactive1ops-warden2026-08-212027-02-21current
ADR-0009 — Adopt security-zones v0.1 as a consumeracceptedactive1ops-warden2026-08-222026-11-22current
ADR-0010 — ops-warden is Staff: lanes, not rules, and one declared engine gapacceptedactive1ops-warden2026-08-282026-11-28current
NetKingdom Security-Layer Interaction Boundaryacceptedactiveaccepted-1railiance-master2026-08-292027-02-28current
What the Hub Projects: Forge as Projection Source, Working Copies as Preliminary Overlayacceptedactive1.0the-custodian2026-08-252027-02-25current
NetKingdom Posture Feedback v0.1proposedactive0.1net-kingdom2026-08-232026-11-23current
NetKingdom Security Layer Model v0.7acceptedactive0.7gate-house2026-08-282026-11-28current
NetKingdom Security Scenario Composition v0.1proposedactive0.1net-kingdom2026-08-232026-11-23current
NetKingdom Security Zones v0.1proposedactive0.1zone-engine2026-08-222026-11-22current
diff --git a/build/publication-manifest.json b/build/publication-manifest.json index e6d4d75..2c36b0c 100644 --- a/build/publication-manifest.json +++ b/build/publication-manifest.json @@ -17,6 +17,91 @@ "status": "proposed", "title": "NetKingdom Tenancy Posture v0.1" }, + { + "canonical_path": "standards/autonomy-lanes/v0.1/index.html", + "currency": "current", + "id": "canon-autonomy-lanes", + "last_reviewed": "2026-08-31", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-28", + "revision": "accepted-1", + "revision_path": "standards/autonomy-lanes/v0.1/revisions/accepted-1/index.html", + "source_digest": "106cb0c99f73983199c9f1d8491143aa2a2eb41ee450a02ec7968d3763f30399", + "source_path": "canon/standards/autonomy-lanes_v0.1.md", + "source_repo": "the-custodian", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", + "status": "accepted", + "title": "Autonomy Lanes (Fleet) v0.1" + }, + { + "canonical_path": "standards/contribution-convention/v0.1/index.html", + "currency": "current", + "id": "canon-contrib-convention", + "last_reviewed": "2026-08-31", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-28", + "revision": "accepted-1", + "revision_path": "standards/contribution-convention/v0.1/revisions/accepted-1/index.html", + "source_digest": "6dfc1d7b2b82ab18228a84660c1c7dff607aad1d9da37ac12084cdd2ab8ae112", + "source_path": "canon/standards/contribution-convention_v0.1.md", + "source_repo": "the-custodian", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", + "status": "accepted", + "title": "Contribution Convention v0.1" + }, + { + "canonical_path": "standards/project-repository-flavor/v0.1/index.html", + "currency": "current", + "id": "canon-project-repository-flavor", + "last_reviewed": "2026-08-31", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-28", + "revision": "accepted-1", + "revision_path": "standards/project-repository-flavor/v0.1/revisions/accepted-1/index.html", + "source_digest": "61889b2f18a82a08b66ef90d758efe5c028a4f52aced1721a23e69c6f24a8224", + "source_path": "canon/standards/project-repository-flavor_v0.1.md", + "source_repo": "the-custodian", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", + "status": "accepted", + "title": "Project Repository Flavor (prj-) v0.1" + }, + { + "canonical_path": "standards/work-record-types/v0.1/index.html", + "currency": "current", + "id": "canon-work-record-types", + "last_reviewed": "2026-08-31", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-28", + "revision": "accepted-1", + "revision_path": "standards/work-record-types/v0.1/revisions/accepted-1/index.html", + "source_digest": "1a40de294be332ee713cdaab532a32a83718f3952c339fbff835ecee899a8dbc", + "source_path": "canon/standards/work-record-types_v0.1.md", + "source_repo": "the-custodian", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", + "status": "accepted", + "title": "Work Record Types & Identity (Fleet) v0.1" + }, + { + "canonical_path": "standards/workplan-terminology/v0.1/index.html", + "currency": "current", + "id": "canon-workplan-terminology-fleet", + "last_reviewed": "2026-08-31", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-28", + "revision": "accepted-1", + "revision_path": "standards/workplan-terminology/v0.1/revisions/accepted-1/index.html", + "source_digest": "199812632ac342ca3231498e545e3701e10c191ca144035b36a23c1a0b717712", + "source_path": "canon/standards/workplan-terminology-fleet_v0.1.md", + "source_repo": "the-custodian", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", + "status": "accepted", + "title": "Workplan Terminology (Fleet) v0.1" + }, { "canonical_path": "architecture/coulomb-estate/v0.1/index.html", "currency": "current", @@ -30,7 +115,7 @@ "source_digest": "3b4f93acdedc6f6d1a1c737c3327d9d55061506c5a879be09e6b0a2ea7f5f9bc", "source_path": "canon/architecture/coulomb-estate_v0.1.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "proposed", "title": "Coulomb estate architecture" }, @@ -81,7 +166,7 @@ "source_digest": "e7104b2182612efe90c9a12168757506402490229814d454e94917ae62d2bfac", "source_path": "docs/architecture/state-hub_v0.1.md", "source_repo": "state-hub", - "source_revision": "da30ce6723f9c5e6fdd994c78bb646986e819d3f", + "source_revision": "0e35f84ad5f2f9397d76ffacb99f9973544f08ac", "status": "proposed", "title": "State Hub architecture" }, @@ -98,7 +183,7 @@ "source_digest": "179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480", "source_path": "docs/architecture/policy-nexus_v0.1.md", "source_repo": "policy-nexus", - "source_revision": "6515ed9ef8499cb3de3397f0ae3993cc71440599", + "source_revision": "885c6bb1cb805b64cbcfa99dd2c5817f6d4a1373", "status": "proposed", "title": "Policy Nexus architecture" }, @@ -115,7 +200,7 @@ "source_digest": "a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be", "source_path": "docs/adr/ADR-0001-addressing-and-permanence.md", "source_repo": "policy-nexus", - "source_revision": "6515ed9ef8499cb3de3397f0ae3993cc71440599", + "source_revision": "885c6bb1cb805b64cbcfa99dd2c5817f6d4a1373", "status": "accepted", "title": "Policy addressing and permanence" }, @@ -438,7 +523,7 @@ "source_digest": "183023ee57bae9c29e726fec5ee0361633fe3a2b182436a57869ae4b2a27af24", "source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Workplans and Work Items Are Repository Artefacts" }, @@ -455,7 +540,7 @@ "source_digest": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec", "source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Custodian Agent Runtime \u2014 v0.1 Bootstrap Design" }, @@ -472,7 +557,7 @@ "source_digest": "fcb49719e2b85b9120c0bd5bebd5e82748ca713f16b44951c028b60205514e2b", "source_path": "canon/architecture/adr-003-materialized-derived-state.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data" }, @@ -489,7 +574,7 @@ "source_digest": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557", "source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Connectivity-First Network Posture for Custodian Infrastructure" }, @@ -506,7 +591,7 @@ "source_digest": "13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f", "source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Cross-Repo Workplans Live in Dedicated Project Repos" }, @@ -523,7 +608,7 @@ "source_digest": "a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823", "source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Canon Federation and Concept Ownership Across InfoTech and Commerce" }, @@ -540,7 +625,7 @@ "source_digest": "1169f0c1f485a2bb7241a8f64f3167c060c04f83341b12586fd9be5c2b3693f8", "source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology" }, @@ -557,7 +642,7 @@ "source_digest": "5979da20799118259fc19246f51e8cc8f2c0c1be3d414318bd51d5a27d9ad565", "source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "proposed", "title": "Hub Authority, Local Cache, and the Two Kinds of Hub Data" }, @@ -574,7 +659,7 @@ "source_digest": "f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0", "source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "proposed", "title": "Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliation" }, @@ -948,7 +1033,7 @@ "source_digest": "b5e8582459f546ae789ad5fd62f458454aa19997b520e32b6b9f792d6af55987", "source_path": "canon/architecture/adr-012-projection-source-and-preliminary-overlay.md", "source_repo": "the-custodian", - "source_revision": "44500fc85cf29d8e9b2ee5c91994032ed3d04e5b", + "source_revision": "4b951be3947f9457cc091a7d359d9232646b4c93", "status": "accepted", "title": "What the Hub Projects: Forge as Projection Source, Working Copies as Preliminary Overlay" }, diff --git a/build/standards/autonomy-lanes/v0.1/index.html b/build/standards/autonomy-lanes/v0.1/index.html new file mode 100644 index 0000000..c59a452 --- /dev/null +++ b/build/standards/autonomy-lanes/v0.1/index.html @@ -0,0 +1,222 @@ + + + + +Autonomy Lanes (Fleet) v0.1 + +
canon-autonomy-lanes accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Autonomy Lanes (Fleet) v0.1

Source: the-custodian · canon/standards/autonomy-lanes_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Promotes the binky-control AutonomyPolicy lane model to fleet canon, unchanged in substance. binky-control's AutonomyPolicy.md remains the company-level policy instance; this standard makes the lane vocabulary and enforcement rules fleet-wide.

+

The rule

+

If the responsible human is unavailable, the system must either continue safely, prepare the next decision, or explicitly defer with evidence. It must not silently idle.

+

Valid states: proceeding | prepared for review | deferred by policy. Invalid state: waiting because unsure. Uncertainty triggers research, comparison, preparation, or risk classification — not paralysis. "Ask the human" is never the default.

+
+

Lanes

+
LaneNameAgent mayHuman involvement
greenSafe autonomousresearch, summarize, classify, draft, organize, test, preparenone (human-on-the-loop via logs)
blueReversible executioninternal docs, backlog updates, local scripts, reports, local commitsnone, but logged
yellowDeferred approvalprepare external emails, invoices, offers, releases, paymentsasync approval via decision records
orangeTime-window approvalcustomer/legal/accounting/banking actions needing business hoursengagement records, batched into command days
redHuman-onlysigning, strategic commitments, bank/credential changes, sensitive legal/HR/securityalways; agents prepare packages only
+

Optimization target: maximize green+blue throughput, queue yellow, batch orange, protect red from automation. Risk-tiered gating (in-the-loop for irreversible actions, on-the-loop for recoverable ones) is the only oversight pattern that scales.

+
+

Lane as a spine field

+

lane is a mandatory field on every work record (see work-record-types_v0.1.md) and on every agent instance manifest. The chain is closed end-to-end:

+
work record.lane → view routing (autopilot / decision / engagement)
+                 → harness tool profile (enforced allow-list)
+                 → ops-warden credential lane (catalog access)
+

Declaring a lane an item does not hold is a policy violation the harness must catch (tool profile refuses the run).

+
+

Approval packages (yellow and above)

+

An agent hitting a lane boundary prepares a complete decision package, never a bare question: recommended action, reason, evidence links, risk level, reversibility, deadline (needed_by), attention cost, fallback if no response, options.

+
+

Human attention is a WIP-limited workstation

+

The responsible human's capacity is modeled like any lane capacity: attention budget (minutes/day, max decisions/day, max deep topics/day) and availability as first-class state (available | evening_window | unavailable | office_hour_day), with an explicit escalation allow-list when unavailable (critical security incident, payment failure, legal deadline). Yellow routes to the decision view, orange to the engagement view, both subject to that capacity.

+

Time-boxing is hub-owned: needed_by / fallback_if_no_response windows are watched by the hub → NATS → activity-core; a lapsed window raises the escalation or executes the declared fallback — never a human re-reading a file.

+
+

Raising autonomy

+

Autonomy per area is raised only after the system proves reliable there, by explicit human decision recorded as a decision work record. Lane assignments are auditable history; lowering a lane needs no approval.

+
+

References

+
  • binky-control/AutonomyPolicy.md (origin instance)
  • canon/standards/work-record-types_v0.1.md
  • research/2026-07-19-work-orchestration-best-practices.md §2
+
diff --git a/build/standards/autonomy-lanes/v0.1/revisions/accepted-1/index.html b/build/standards/autonomy-lanes/v0.1/revisions/accepted-1/index.html new file mode 100644 index 0000000..c59a452 --- /dev/null +++ b/build/standards/autonomy-lanes/v0.1/revisions/accepted-1/index.html @@ -0,0 +1,222 @@ + + + + +Autonomy Lanes (Fleet) v0.1 + +
canon-autonomy-lanes accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Autonomy Lanes (Fleet) v0.1

Source: the-custodian · canon/standards/autonomy-lanes_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Promotes the binky-control AutonomyPolicy lane model to fleet canon, unchanged in substance. binky-control's AutonomyPolicy.md remains the company-level policy instance; this standard makes the lane vocabulary and enforcement rules fleet-wide.

+

The rule

+

If the responsible human is unavailable, the system must either continue safely, prepare the next decision, or explicitly defer with evidence. It must not silently idle.

+

Valid states: proceeding | prepared for review | deferred by policy. Invalid state: waiting because unsure. Uncertainty triggers research, comparison, preparation, or risk classification — not paralysis. "Ask the human" is never the default.

+
+

Lanes

+
LaneNameAgent mayHuman involvement
greenSafe autonomousresearch, summarize, classify, draft, organize, test, preparenone (human-on-the-loop via logs)
blueReversible executioninternal docs, backlog updates, local scripts, reports, local commitsnone, but logged
yellowDeferred approvalprepare external emails, invoices, offers, releases, paymentsasync approval via decision records
orangeTime-window approvalcustomer/legal/accounting/banking actions needing business hoursengagement records, batched into command days
redHuman-onlysigning, strategic commitments, bank/credential changes, sensitive legal/HR/securityalways; agents prepare packages only
+

Optimization target: maximize green+blue throughput, queue yellow, batch orange, protect red from automation. Risk-tiered gating (in-the-loop for irreversible actions, on-the-loop for recoverable ones) is the only oversight pattern that scales.

+
+

Lane as a spine field

+

lane is a mandatory field on every work record (see work-record-types_v0.1.md) and on every agent instance manifest. The chain is closed end-to-end:

+
work record.lane → view routing (autopilot / decision / engagement)
+                 → harness tool profile (enforced allow-list)
+                 → ops-warden credential lane (catalog access)
+

Declaring a lane an item does not hold is a policy violation the harness must catch (tool profile refuses the run).

+
+

Approval packages (yellow and above)

+

An agent hitting a lane boundary prepares a complete decision package, never a bare question: recommended action, reason, evidence links, risk level, reversibility, deadline (needed_by), attention cost, fallback if no response, options.

+
+

Human attention is a WIP-limited workstation

+

The responsible human's capacity is modeled like any lane capacity: attention budget (minutes/day, max decisions/day, max deep topics/day) and availability as first-class state (available | evening_window | unavailable | office_hour_day), with an explicit escalation allow-list when unavailable (critical security incident, payment failure, legal deadline). Yellow routes to the decision view, orange to the engagement view, both subject to that capacity.

+

Time-boxing is hub-owned: needed_by / fallback_if_no_response windows are watched by the hub → NATS → activity-core; a lapsed window raises the escalation or executes the declared fallback — never a human re-reading a file.

+
+

Raising autonomy

+

Autonomy per area is raised only after the system proves reliable there, by explicit human decision recorded as a decision work record. Lane assignments are auditable history; lowering a lane needs no approval.

+
+

References

+
  • binky-control/AutonomyPolicy.md (origin instance)
  • canon/standards/work-record-types_v0.1.md
  • research/2026-07-19-work-orchestration-best-practices.md §2
+
diff --git a/build/standards/contribution-convention/v0.1/index.html b/build/standards/contribution-convention/v0.1/index.html new file mode 100644 index 0000000..ec65d3b --- /dev/null +++ b/build/standards/contribution-convention/v0.1/index.html @@ -0,0 +1,273 @@ + + + + +Contribution Convention v0.1 + +
canon-contrib-convention accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Contribution Convention v0.1

Source: the-custodian · canon/standards/contribution-convention_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

This document defines the canonical convention for tracking upstream contributions across all custodian-ecosystem repositories. A contribution is any intentional engagement with an external upstream project: a bug report, feature request, extension-point proposal, or pull request.

+

Contributions are tracked as Markdown artifacts with typed YAML frontmatter, committed to the repository that authors them, and indexed in the State Hub DB. This enables the Custodian to maintain a full audit trail of all upstream engagement across all six project domains.

+
+

Artifact Types

+
CodeNameDescription
brBug ReportA defect reported to an upstream project
frFeature RequestA capability requested from an upstream project
epExtension-Point ProposalA proposed extension point in an upstream project
uprUpstream PRA pull request submitted or planned for upstream
+
+

Directory Layout

+
<repo-root>/
+  contrib/
+    bug-reports/       # BR artifacts
+    feature-requests/  # FR artifacts
+    extension-points/  # EP artifacts
+    upstream-prs/      # UPR artifacts
+

Each artifact file follows the naming pattern:

+
<YYYY-MM-DD>--<org>--<repo>--<slug>.md
+

Examples:

+
  • contrib/bug-reports/2026-03-01--observablehq--framework--plot-tooltip-flicker.md
  • contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md
  • contrib/extension-points/EP-CUST-002--anthropic--claude-code--hook-on-tool-result.md
+
+

Frontmatter Schema

+

All contribution artifacts share a common base frontmatter:

+
---
+id: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug>   # unique string ID
+type: br | fr | ep | upr                           # required
+target_org: <github-org-or-owner>                  # required
+target_repo: <repository-name>                     # required
+title: "Human-readable title"                      # required
+status: draft | submitted | acknowledged | accepted | rejected | merged | withdrawn
+domain: infotech | agents | communication | ...   # current sector domain; see Repo Classification Standard §6
+related_workstream: <workstream-slug>              # optional
+state_hub_contribution_id: <uuid>                  # set once registered in State Hub
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+---
+

BR — Bug Report (additional fields)

+
upstream_version: "1.2.3"          # version where bug was observed
+reproduction_steps: |
+  1. …
+  2. …
+expected: "What should happen"
+actual: "What actually happens"
+workaround: "Any known workaround"  # optional
+upstream_issue_url: "https://…"     # optional — link once filed
+

FR — Feature Request (additional fields)

+
motivation: "Why this feature is needed"
+proposed_api: |
+  # Sketch of the proposed interface
+alternatives: "What we do instead today"
+upstream_issue_url: "https://…"     # optional
+

EP — Extension-Point Proposal (additional fields)

+
ep_id: EP-<DOMAIN>-NNN              # e.g. EP-RAIL-007
+location: "src/file.ts:42"          # file:line in upstream where hook would live
+proposed_interface: |
+  # Interface or callback signature sketch
+rationale: "Why this extension point is valuable"
+upstream_issue_url: "https://…"     # optional
+

UPR — Upstream PR (additional fields)

+
local_component_path: "relative/path/in/this/repo"
+target_upstream_file: "path/in/upstream/repo"
+upstream_pr_url: "https://…"        # set once submitted
+draft_pr_body: |
+  ## Summary
+  …
+
+  ## Motivation
+  …
+
+

ID Schemes

+
  • BR / FR / UPR: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug> — date-prefixed slug
  • EP: EP-<DOMAIN>-NNN where <DOMAIN> is uppercase (CUST, RAIL, MARK, etc.) and NNN is a zero-padded three-digit sequence per domain (EP-CUST-001, EP-CUST-002, …). This scheme is an extension of the Railiance EP convention defined in the staged-promotion-lifecycle workstream; this canon document is the authoritative master spec.
+
+

Status Lifecycle

+
draft → submitted → acknowledged → accepted → merged
+                ↘             ↘
+              rejected      withdrawn
+
  • draft: artifact created locally, not yet sent upstream
  • submitted: issue filed or PR opened upstream
  • acknowledged: upstream team has responded
  • accepted: upstream has agreed to the proposal
  • rejected: upstream has declined
  • merged: PR merged / fix released
  • withdrawn: we decided not to pursue
+
+

Relationship to State Hub

+

Once an artifact is registered via register_contribution() MCP tool or POST /contributions/ API, the State Hub assigns a UUID and returns it. That UUID is written back into state_hub_contribution_id in the frontmatter.

+

The State Hub is a read/cache layer — the Markdown file is always the authoritative source of truth. If the DB is reset, contributions can be re-ingested from the files.

+
diff --git a/build/standards/contribution-convention/v0.1/revisions/accepted-1/index.html b/build/standards/contribution-convention/v0.1/revisions/accepted-1/index.html new file mode 100644 index 0000000..ec65d3b --- /dev/null +++ b/build/standards/contribution-convention/v0.1/revisions/accepted-1/index.html @@ -0,0 +1,273 @@ + + + + +Contribution Convention v0.1 + +
canon-contrib-convention accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Contribution Convention v0.1

Source: the-custodian · canon/standards/contribution-convention_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

This document defines the canonical convention for tracking upstream contributions across all custodian-ecosystem repositories. A contribution is any intentional engagement with an external upstream project: a bug report, feature request, extension-point proposal, or pull request.

+

Contributions are tracked as Markdown artifacts with typed YAML frontmatter, committed to the repository that authors them, and indexed in the State Hub DB. This enables the Custodian to maintain a full audit trail of all upstream engagement across all six project domains.

+
+

Artifact Types

+
CodeNameDescription
brBug ReportA defect reported to an upstream project
frFeature RequestA capability requested from an upstream project
epExtension-Point ProposalA proposed extension point in an upstream project
uprUpstream PRA pull request submitted or planned for upstream
+
+

Directory Layout

+
<repo-root>/
+  contrib/
+    bug-reports/       # BR artifacts
+    feature-requests/  # FR artifacts
+    extension-points/  # EP artifacts
+    upstream-prs/      # UPR artifacts
+

Each artifact file follows the naming pattern:

+
<YYYY-MM-DD>--<org>--<repo>--<slug>.md
+

Examples:

+
  • contrib/bug-reports/2026-03-01--observablehq--framework--plot-tooltip-flicker.md
  • contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md
  • contrib/extension-points/EP-CUST-002--anthropic--claude-code--hook-on-tool-result.md
+
+

Frontmatter Schema

+

All contribution artifacts share a common base frontmatter:

+
---
+id: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug>   # unique string ID
+type: br | fr | ep | upr                           # required
+target_org: <github-org-or-owner>                  # required
+target_repo: <repository-name>                     # required
+title: "Human-readable title"                      # required
+status: draft | submitted | acknowledged | accepted | rejected | merged | withdrawn
+domain: infotech | agents | communication | ...   # current sector domain; see Repo Classification Standard §6
+related_workstream: <workstream-slug>              # optional
+state_hub_contribution_id: <uuid>                  # set once registered in State Hub
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+---
+

BR — Bug Report (additional fields)

+
upstream_version: "1.2.3"          # version where bug was observed
+reproduction_steps: |
+  1. …
+  2. …
+expected: "What should happen"
+actual: "What actually happens"
+workaround: "Any known workaround"  # optional
+upstream_issue_url: "https://…"     # optional — link once filed
+

FR — Feature Request (additional fields)

+
motivation: "Why this feature is needed"
+proposed_api: |
+  # Sketch of the proposed interface
+alternatives: "What we do instead today"
+upstream_issue_url: "https://…"     # optional
+

EP — Extension-Point Proposal (additional fields)

+
ep_id: EP-<DOMAIN>-NNN              # e.g. EP-RAIL-007
+location: "src/file.ts:42"          # file:line in upstream where hook would live
+proposed_interface: |
+  # Interface or callback signature sketch
+rationale: "Why this extension point is valuable"
+upstream_issue_url: "https://…"     # optional
+

UPR — Upstream PR (additional fields)

+
local_component_path: "relative/path/in/this/repo"
+target_upstream_file: "path/in/upstream/repo"
+upstream_pr_url: "https://…"        # set once submitted
+draft_pr_body: |
+  ## Summary
+  …
+
+  ## Motivation
+  …
+
+

ID Schemes

+
  • BR / FR / UPR: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug> — date-prefixed slug
  • EP: EP-<DOMAIN>-NNN where <DOMAIN> is uppercase (CUST, RAIL, MARK, etc.) and NNN is a zero-padded three-digit sequence per domain (EP-CUST-001, EP-CUST-002, …). This scheme is an extension of the Railiance EP convention defined in the staged-promotion-lifecycle workstream; this canon document is the authoritative master spec.
+
+

Status Lifecycle

+
draft → submitted → acknowledged → accepted → merged
+                ↘             ↘
+              rejected      withdrawn
+
  • draft: artifact created locally, not yet sent upstream
  • submitted: issue filed or PR opened upstream
  • acknowledged: upstream team has responded
  • accepted: upstream has agreed to the proposal
  • rejected: upstream has declined
  • merged: PR merged / fix released
  • withdrawn: we decided not to pursue
+
+

Relationship to State Hub

+

Once an artifact is registered via register_contribution() MCP tool or POST /contributions/ API, the State Hub assigns a UUID and returns it. That UUID is written back into state_hub_contribution_id in the frontmatter.

+

The State Hub is a read/cache layer — the Markdown file is always the authoritative source of truth. If the DB is reset, contributions can be re-ingested from the files.

+
diff --git a/build/standards/project-repository-flavor/v0.1/index.html b/build/standards/project-repository-flavor/v0.1/index.html new file mode 100644 index 0000000..650f068 --- /dev/null +++ b/build/standards/project-repository-flavor/v0.1/index.html @@ -0,0 +1,279 @@ + + + + +Project Repository Flavor (prj-) v0.1 + +
canon-project-repository-flavor accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Project Repository Flavor (prj-) v0.1

Source: the-custodian · canon/standards/project-repository-flavor_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

Define the durable project repository flavor used for complex cross-repository efforts: naming, required files, authority boundary, lifecycle, residual handoff, and archive procedure.

+

This standard implements and completes ADR-005 (Cross-Repo Workplans Live in Dedicated Project Repos). It does not replace the Repo Classification Standard: project repositories still use category: project in .repo-classification.yaml.

+
+

When to use a project repository

+

Create a project repository when all of the following hold:

+
  1. The work coordinates change across two or more functional repositories.
  2. Binding the coordination workplan to any single product/tooling repo would misrepresent ownership or pollute that repo's history.
  3. The effort has a bounded outcome with explicit success and retirement conditions (not an open-ended product roadmap).
+

Do not create a project repository for:

+
  • single-repo workplans;
  • small cross-cutting fixes that fit one lead repo's workplan plus dependency links;
  • durable products, libraries, or services (those use INTENT.md and ordinary product/tooling/research categories);
  • long-lived domain charters (those remain under the-custodian/canon/projects/).
+
+

Naming

+
ElementConvention
Git / local directoryprj-<kebab-slug>
Hub repo slugsame as directory name
Workplan prefixshort uppercase prefix derived from the project, ending in -WP- (example: SHR-WP- for State Hub Retirement)
Classificationcategory: project
+

Canonical prefix is prj-. ADR-005's illustrative proj- form is superseded for new repositories. Do not invent parallel prefixes (project-, xrepo-, …).

+

Slug rules:

+
  • lowercase kebab-case;
  • outcome-oriented (prj-state-hub-retirement), not a random ticket id;
  • stable for the life of the project (rename only with an explicit migration note in history/).
+
+

Authority boundary

+
ConcernOwner
Project goal, success gates, retirement conditionsproject repo (GOAL.md)
Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidenceproject repo
Cross-repo workplans that coordinate the effortproject repo (workplans/)
Production implementation, tests, deployablesparticipating functional repositories
Per-repo implementation workplans and local evidenceeach functional repository
Durable post-project standards and ADRspermanent homes (the-custodian canon, or the owning product/tooling repo)
+

Hard rules:

+
  1. Project repositories MUST NOT host production implementation code for the systems being changed.
  2. Project workplans link child workplans by stable ID; they MUST NOT copy or replace child task lists.
  3. The hub remains a read/index layer; work records originate as files (ADR-001).
  4. Results of the project live primarily in the modified functional repositories and promoted canon. The project repo is coordination + provenance.
+
+

Required files

+

At registration / first meaningful commit:

+
PathRequiredRole
GOAL.mdyesOutcome, invariants, success gates, project retirement conditions. Replaces INTENT.md for this flavor.
SCOPE.mdyesProject authority, participating repos, in/out of scope, work-record rule.
README.mdyesShort entry point linking GOAL.md, SCOPE.md, genesis/history, active workplans.
AGENTS.mdyesAgent session protocol for this project (orient → work → close; hub integration).
.repo-classification.yamlyescategory: project plus domain / capability tags for the effort.
workplans/yesAt least one foundation workplan; prefix unique to the project.
history/recommendedGenesis and significant milestones (why the project exists).
WORK-RECORDS.mdgeneratedHub index; do not hand-edit.
.custodian-brief.mdgeneratedOffline orientation brief.
+

GOAL.md (not INTENT.md)

+

Durable product and tooling repositories explain why they exist with INTENT.md. Project repositories are temporary and outcome-bounded; they use GOAL.md instead.

+

GOAL.md MUST include:

+
  1. Outcome — what success looks like in one short section.
  2. Invariants — rules that must hold during the project.
  3. Success gates — checkable conditions for “goal achieved”.
  4. Project retirement — conditions under which this repository may be archived (usually: gates met + residuals handed off + durable decisions promoted).
+

Recommended frontmatter:

+
---
+repo: prj-<slug>
+repo_flavor: project
+project_status: draft | active | completed | archived
+started: "YYYY-MM-DD"
+reviewed: "YYYY-MM-DD"
+---
+

Anti-pattern: shipping both INTENT.md and GOAL.md in a prj- repo. If a durable intent emerges, promote it into a permanent repository's INTENT.md (or canon) and keep the project goal as the temporary outcome document.

+

Relation to durable INTENT.md

+
Repository kindPurpose document
product / tooling / research / business / experimentalINTENT.md
project (prj-)GOAL.md only
+

Tooling that scaffolds repositories (e.g. statehub register) MUST treat GOAL.md + repo_flavor: project as sufficient purpose documentation for prj- repos and MUST NOT require inventing an INTENT.md that pretends the project is a permanent product.

+
+

Lifecycle

+
draft → active → completed → archived
+
StatusMeaningRepo / hub signals
draftConvention and foundation still forming; may not yet be registeredproject_status: draft; workplans often proposed / ready
activeCoordination and child implementation in progressproject_status: active; at least one workplan active or ready
completedAll success gates have accepted evidence; residuals have live owners outside this repoproject_status: completed; project workplans finished or cancelled with rationale
archivedRepository is read-only provenanceforge archive flag; hub repo/workplan archived; no normal writes
+

Promotion rules:

+
  • draft → active when GOAL.md / SCOPE.md are reviewable and the foundation workplan is ready or active.
  • active → completed only when every GOAL.md success gate has accepted evidence and residuals are live work records elsewhere (see below).
  • completed → archived after the completion record is written, durable decisions are promoted, and a final consistency/link check passes.
+
+

Residuals before completion

+

Actionable leftovers MUST NOT live only in finished workplan prose or SCOPE.md. Before any project workplan is set to finished, and again before project_status: completed, each residual becomes a live work record outside the closing narrative:

+
  • intake with origin: residual + origin_ref: <WP-id>, or
  • a next workplan / decision / engagement / register-entry in a permanent repo.
+

Canon: work-record-types_v0.1.md § Residuals. Fleet residual listing is a State Hub concern, not a project-local queue file.

+
+

Completion record

+

Before archival, the project repository MUST contain a completion record (recommended path: history/YYYY-MM-DD-completion.md) that lists:

+
  1. deployed or merged revisions that realize the outcome;
  2. every participating repository touched, with links to merged PRs/commits or child workplan IDs;
  3. promoted durable artefacts (canon paths, ADRs, standards);
  4. migration and retirement evidence pointers (counts, cutover windows, backups);
  5. residual work-record IDs and their owning repos;
  6. rollback expiry or remaining operational obligations, if any.
+

Without this record, do not archive.

+
+

Archive procedure

+
  1. Verify all success gates and retirement conditions in GOAL.md.
  2. Confirm residuals are live and owned outside this repository.
  3. Promote remaining durable decisions/standards to permanent homes; leave pointers from the project repo.
  4. Finish or cancel project workplans; move finished files to workplans/archived/YYMMDD-<id>-<slug>.md per workplan convention.
  5. Write the completion record.
  6. Set project_status: archived in GOAL.md frontmatter.
  7. Run statehub fix-consistency (or equivalent) so the hub reflects finished workplans and the archived status.
  8. Archive the repository in the forge (read-only); do not delete it.
  9. Optionally mark the hub registration archived / read-only.
+

Archive means read-only provenance, never deletion. Historical evidence and coordination narrative remain queryable.

+
+

Workplan and agent conventions

+
  • Workplan files: workplans/<PREFIX>-WP-NNNN-<slug>.md with fleet status vocabulary (proposed … archived).
  • Session start order for agents: GOAL.md → SCOPE.md → genesis/history → active workplans (see project AGENTS.md).
  • Progress and task status follow ordinary State Hub / fix-consistency rules.
  • Ad-hoc low-risk fixes may use workplans/ADHOC-YYYY-MM-DD.md with canonical id {PREFIX}-WP-ADHOC-YYYY-MM-DD; anything multi-step belongs in a normal workplan.
+
+

Minimal layout example

+
prj-example-cutover/
+  GOAL.md
+  SCOPE.md
+  README.md
+  AGENTS.md
+  .repo-classification.yaml
+  history/
+    2026-08-09-genesis.md
+  workplans/
+    EX-WP-0001-foundation.md
+
+

Reference instance

+

The first repository under this standard is prj-state-hub-retirement (State Hub retirement / hub-core consolidation). Use it as the structural reference when scaffolding later prj- repos; do not copy its domain-specific content.

+
+

Conformance checklist

+

A repository conforms to the prj- flavor when:

+
  • [ ] Named prj-<slug> and classified category: project.
  • [ ] Has GOAL.md with outcome, invariants, success gates, and retirement.
  • [ ] Has no durable-product INTENT.md (or documents an explicit temporary exception during migration of a mis-scaffolded repo).
  • [ ] Has SCOPE.md, README.md, AGENTS.md, and .repo-classification.yaml.
  • [ ] Hosts coordination workplans only; implementation lives in child repos.
  • [ ] Links child workplans by ID rather than duplicating their tasks.
  • [ ] Defines archive/completion discipline consistent with this standard.
  • [ ] On completion, writes a completion record and archives read-only.
+
+
diff --git a/build/standards/project-repository-flavor/v0.1/revisions/accepted-1/index.html b/build/standards/project-repository-flavor/v0.1/revisions/accepted-1/index.html new file mode 100644 index 0000000..650f068 --- /dev/null +++ b/build/standards/project-repository-flavor/v0.1/revisions/accepted-1/index.html @@ -0,0 +1,279 @@ + + + + +Project Repository Flavor (prj-) v0.1 + +
canon-project-repository-flavor accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Project Repository Flavor (prj-) v0.1

Source: the-custodian · canon/standards/project-repository-flavor_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

Define the durable project repository flavor used for complex cross-repository efforts: naming, required files, authority boundary, lifecycle, residual handoff, and archive procedure.

+

This standard implements and completes ADR-005 (Cross-Repo Workplans Live in Dedicated Project Repos). It does not replace the Repo Classification Standard: project repositories still use category: project in .repo-classification.yaml.

+
+

When to use a project repository

+

Create a project repository when all of the following hold:

+
  1. The work coordinates change across two or more functional repositories.
  2. Binding the coordination workplan to any single product/tooling repo would misrepresent ownership or pollute that repo's history.
  3. The effort has a bounded outcome with explicit success and retirement conditions (not an open-ended product roadmap).
+

Do not create a project repository for:

+
  • single-repo workplans;
  • small cross-cutting fixes that fit one lead repo's workplan plus dependency links;
  • durable products, libraries, or services (those use INTENT.md and ordinary product/tooling/research categories);
  • long-lived domain charters (those remain under the-custodian/canon/projects/).
+
+

Naming

+
ElementConvention
Git / local directoryprj-<kebab-slug>
Hub repo slugsame as directory name
Workplan prefixshort uppercase prefix derived from the project, ending in -WP- (example: SHR-WP- for State Hub Retirement)
Classificationcategory: project
+

Canonical prefix is prj-. ADR-005's illustrative proj- form is superseded for new repositories. Do not invent parallel prefixes (project-, xrepo-, …).

+

Slug rules:

+
  • lowercase kebab-case;
  • outcome-oriented (prj-state-hub-retirement), not a random ticket id;
  • stable for the life of the project (rename only with an explicit migration note in history/).
+
+

Authority boundary

+
ConcernOwner
Project goal, success gates, retirement conditionsproject repo (GOAL.md)
Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidenceproject repo
Cross-repo workplans that coordinate the effortproject repo (workplans/)
Production implementation, tests, deployablesparticipating functional repositories
Per-repo implementation workplans and local evidenceeach functional repository
Durable post-project standards and ADRspermanent homes (the-custodian canon, or the owning product/tooling repo)
+

Hard rules:

+
  1. Project repositories MUST NOT host production implementation code for the systems being changed.
  2. Project workplans link child workplans by stable ID; they MUST NOT copy or replace child task lists.
  3. The hub remains a read/index layer; work records originate as files (ADR-001).
  4. Results of the project live primarily in the modified functional repositories and promoted canon. The project repo is coordination + provenance.
+
+

Required files

+

At registration / first meaningful commit:

+
PathRequiredRole
GOAL.mdyesOutcome, invariants, success gates, project retirement conditions. Replaces INTENT.md for this flavor.
SCOPE.mdyesProject authority, participating repos, in/out of scope, work-record rule.
README.mdyesShort entry point linking GOAL.md, SCOPE.md, genesis/history, active workplans.
AGENTS.mdyesAgent session protocol for this project (orient → work → close; hub integration).
.repo-classification.yamlyescategory: project plus domain / capability tags for the effort.
workplans/yesAt least one foundation workplan; prefix unique to the project.
history/recommendedGenesis and significant milestones (why the project exists).
WORK-RECORDS.mdgeneratedHub index; do not hand-edit.
.custodian-brief.mdgeneratedOffline orientation brief.
+

GOAL.md (not INTENT.md)

+

Durable product and tooling repositories explain why they exist with INTENT.md. Project repositories are temporary and outcome-bounded; they use GOAL.md instead.

+

GOAL.md MUST include:

+
  1. Outcome — what success looks like in one short section.
  2. Invariants — rules that must hold during the project.
  3. Success gates — checkable conditions for “goal achieved”.
  4. Project retirement — conditions under which this repository may be archived (usually: gates met + residuals handed off + durable decisions promoted).
+

Recommended frontmatter:

+
---
+repo: prj-<slug>
+repo_flavor: project
+project_status: draft | active | completed | archived
+started: "YYYY-MM-DD"
+reviewed: "YYYY-MM-DD"
+---
+

Anti-pattern: shipping both INTENT.md and GOAL.md in a prj- repo. If a durable intent emerges, promote it into a permanent repository's INTENT.md (or canon) and keep the project goal as the temporary outcome document.

+

Relation to durable INTENT.md

+
Repository kindPurpose document
product / tooling / research / business / experimentalINTENT.md
project (prj-)GOAL.md only
+

Tooling that scaffolds repositories (e.g. statehub register) MUST treat GOAL.md + repo_flavor: project as sufficient purpose documentation for prj- repos and MUST NOT require inventing an INTENT.md that pretends the project is a permanent product.

+
+

Lifecycle

+
draft → active → completed → archived
+
StatusMeaningRepo / hub signals
draftConvention and foundation still forming; may not yet be registeredproject_status: draft; workplans often proposed / ready
activeCoordination and child implementation in progressproject_status: active; at least one workplan active or ready
completedAll success gates have accepted evidence; residuals have live owners outside this repoproject_status: completed; project workplans finished or cancelled with rationale
archivedRepository is read-only provenanceforge archive flag; hub repo/workplan archived; no normal writes
+

Promotion rules:

+
  • draft → active when GOAL.md / SCOPE.md are reviewable and the foundation workplan is ready or active.
  • active → completed only when every GOAL.md success gate has accepted evidence and residuals are live work records elsewhere (see below).
  • completed → archived after the completion record is written, durable decisions are promoted, and a final consistency/link check passes.
+
+

Residuals before completion

+

Actionable leftovers MUST NOT live only in finished workplan prose or SCOPE.md. Before any project workplan is set to finished, and again before project_status: completed, each residual becomes a live work record outside the closing narrative:

+
  • intake with origin: residual + origin_ref: <WP-id>, or
  • a next workplan / decision / engagement / register-entry in a permanent repo.
+

Canon: work-record-types_v0.1.md § Residuals. Fleet residual listing is a State Hub concern, not a project-local queue file.

+
+

Completion record

+

Before archival, the project repository MUST contain a completion record (recommended path: history/YYYY-MM-DD-completion.md) that lists:

+
  1. deployed or merged revisions that realize the outcome;
  2. every participating repository touched, with links to merged PRs/commits or child workplan IDs;
  3. promoted durable artefacts (canon paths, ADRs, standards);
  4. migration and retirement evidence pointers (counts, cutover windows, backups);
  5. residual work-record IDs and their owning repos;
  6. rollback expiry or remaining operational obligations, if any.
+

Without this record, do not archive.

+
+

Archive procedure

+
  1. Verify all success gates and retirement conditions in GOAL.md.
  2. Confirm residuals are live and owned outside this repository.
  3. Promote remaining durable decisions/standards to permanent homes; leave pointers from the project repo.
  4. Finish or cancel project workplans; move finished files to workplans/archived/YYMMDD-<id>-<slug>.md per workplan convention.
  5. Write the completion record.
  6. Set project_status: archived in GOAL.md frontmatter.
  7. Run statehub fix-consistency (or equivalent) so the hub reflects finished workplans and the archived status.
  8. Archive the repository in the forge (read-only); do not delete it.
  9. Optionally mark the hub registration archived / read-only.
+

Archive means read-only provenance, never deletion. Historical evidence and coordination narrative remain queryable.

+
+

Workplan and agent conventions

+
  • Workplan files: workplans/<PREFIX>-WP-NNNN-<slug>.md with fleet status vocabulary (proposed … archived).
  • Session start order for agents: GOAL.md → SCOPE.md → genesis/history → active workplans (see project AGENTS.md).
  • Progress and task status follow ordinary State Hub / fix-consistency rules.
  • Ad-hoc low-risk fixes may use workplans/ADHOC-YYYY-MM-DD.md with canonical id {PREFIX}-WP-ADHOC-YYYY-MM-DD; anything multi-step belongs in a normal workplan.
+
+

Minimal layout example

+
prj-example-cutover/
+  GOAL.md
+  SCOPE.md
+  README.md
+  AGENTS.md
+  .repo-classification.yaml
+  history/
+    2026-08-09-genesis.md
+  workplans/
+    EX-WP-0001-foundation.md
+
+

Reference instance

+

The first repository under this standard is prj-state-hub-retirement (State Hub retirement / hub-core consolidation). Use it as the structural reference when scaffolding later prj- repos; do not copy its domain-specific content.

+
+

Conformance checklist

+

A repository conforms to the prj- flavor when:

+
  • [ ] Named prj-<slug> and classified category: project.
  • [ ] Has GOAL.md with outcome, invariants, success gates, and retirement.
  • [ ] Has no durable-product INTENT.md (or documents an explicit temporary exception during migration of a mis-scaffolded repo).
  • [ ] Has SCOPE.md, README.md, AGENTS.md, and .repo-classification.yaml.
  • [ ] Hosts coordination workplans only; implementation lives in child repos.
  • [ ] Links child workplans by ID rather than duplicating their tasks.
  • [ ] Defines archive/completion discipline consistent with this standard.
  • [ ] On completion, writes a completion record and archives read-only.
+
+
diff --git a/build/standards/work-record-types/v0.1/index.html b/build/standards/work-record-types/v0.1/index.html new file mode 100644 index 0000000..c7f38af --- /dev/null +++ b/build/standards/work-record-types/v0.1/index.html @@ -0,0 +1,246 @@ + + + + +Work Record Types & Identity (Fleet) v0.1 + +
canon-work-record-types accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Work Record Types & Identity (Fleet) v0.1

Source: the-custodian · canon/standards/work-record-types_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Source: research/WorkOrchestrationArchitectureDraft.md v0.2 (founder-reviewed 2026-07-20). Extends — does not replace — workplan-terminology-fleet_v0.1.md and ADR-001/ADR-005.

+

Purpose

+

Define work record as the umbrella term for every identified, lifecycle-bearing coordination artefact in the fleet; register the closed list of work-record kinds, their id schemes and abstract lifecycles; and fix the two-layer identity rule. This is the backbone convention for all work — planning, development, testing, operations, security & compliance, controlling, billing, marketing, sales — under one conceptual framework (different demands are met by flow profiles and kind-specific fields, never by parallel ontologies).

+
+

Core definition

+

A work record is any identified, lifecycle-bearing coordination artefact. A task is one kind of work record — the smallest executable unit. Every work record, regardless of kind, carries the conventional spine:

+
FieldConvention
idcanonical name per the type registry below
uuidUUIDv7, hub-assigned at first index, written back to the source file
kindone of the registered kinds
laneautonomy lane (autonomy-lanes_v0.1.md)
statusabstract lifecycle of the kind (below)
owneragent identity (agt-…) or human
repoowning repo (ADR-001/ADR-005 anchor)
tagspolicy + derived tags (§ Tags)
created / updateddates (UUIDv7 supplies fine-grained internal time)
+

Kind-specific fields (budget, evidence, counterparty, deadline_pressure, attention_cost, …) extend the spine; they never replace it.

+
+

Kind registry (closed list)

+
KindId schemeMeaningAbsorbs / legacy
`workplan`{PREFIX}-WP-NNNN · {PREFIX}-WP-ADHOC-YYYY-MM-DDstructured, dependency-bearing body of work; repository-qualified daily container for small same-day tasksunqualified ADHOC-YYYY-MM-DD; MASON-0001 (grandfathered)
`task`{WP-ID}-TNNsmallest executable unitunqualified ADHOC-YYYY-MM-DD-TNN; MASON-0001-TNN (grandfathered); issue-core issues become external projections only
`intake`{PREFIX}-IN-NNNNspark: idea, finding, directive, requesthub suggestions (legacy, read-only close-out); AWQ-NNN (grandfathered)
`decision`{PREFIX}-DEC-YYYY-NNNapproval package + resolutionDEC-YYYY-NNN (binky, grandfathered as-is)
`engagement`{PREFIX}-ENG-YYYY-NNNscheduled external interaction (counterparty, prepared material, time window)OH-YYYY-NNN (grandfathered)
`register-entry`existing schemes: RISK-NNN, RISK-F-NNNN, RISK-REG-NNNN, TD-…, CAP-…, CCR-YYYY-NNNN, ADR-NNNrisks/findings, regulatory records, technical debt, capability requests, credential change requests, architecture decisionsunchanged semantics, brought under the spine
+

Rules:

+
  1. Prefix grammar: {PREFIX} is one or more uppercase alphanumeric segments, each beginning with a letter, joined by hyphens. Both compact prefixes such as CUST and repository-derived prefixes such as RAPP-OPENBAO or RAIL-K8S are canonical. The final -WP- token remains the unambiguous kind separator.
  2. The registry is closed. An id pattern not registered in work-record-types.yaml fails CI and fix-consistency (the sidetrack detector). New kinds/prefixes are added by canon PR — deliberately cheap (one YAML entry + one schema) so the legitimate path is easier than any workaround.
  3. Grandfathering: existing ids are never renamed. Legacy prefixes map to kinds in the registry; retirement of a scheme (never of records) follows the legacy-meter discipline of workplan-terminology-fleet_v0.1.md.
+

Compatibility correction 2026-08-23: State Hub message 24504ce7-4f73-47da-a150-629b07b37073 exposed that the machine pattern did not accept the already owner-registered RAPP-OPENBAO-WP prefix. The grammar now matches ADR-007's repository-derived prefix model; prefix ownership and uniqueness remain separate registry checks and are not weakened by this syntax correction.

+

The same compatibility review initially registered unqualified ADHOC-YYYY-MM-DD containers. A same-day collision between Activity Core and Net Kingdom then demonstrated that this form violates ADR-007's fleet-namespace uniqueness rule and cannot be used with deterministic UUID derivation. New daily records therefore use {PREFIX}-WP-ADHOC-YYYY-MM-DD; the filename remains workplans/ADHOC-YYYY-MM-DD.md. Existing unqualified ids are grandfathered and are never silently re-derived or disambiguated. Ad-hoc containers remain only for low-risk work completed directly.

+

Risk Nexus findings (RISK-F-*) and regulatory records (RISK-REG-*) are registered as variants of register-entry, not as parallel work kinds. Their lifecycles remain owned by the register convention. RISK-N-* notes are deliberately not registered: a note has no lifecycle, so it does not meet the core definition of a work record. A note becomes part of the backbone only when an event promotes its substance into a lifecycle-bearing kind.

+
+

Identity layering

+
  • UUIDv7 is primary for bookkeeping, relations, dependencies, and history. It is stable across renames, migrations, and terminology transitions.
  • Canonical names are primary for humans and agents — UI, CLI, API output, prose, commits. UUIDs stay inspectable on demand but are never required reading.
  • The hub writes the UUID back into the source file at first index (pattern: today's state_hub_*_id fields).
  • A repeated source block with the same canonical id and the same UUID is one record with duplicate source occurrences. Index it once, retain every source location as diagnostic provenance, and report the duplication for governed cleanup. The repetition must not mint a second record. The same canonical id with different UUIDs is an identity collision and fails closed.
+
+

Abstract lifecycles (canon-fixed, minimal)

+
KindLifecycle
task`wait → todo → progress → done \cancel` (InfoTechCanon)
workplanproposed → ready → active → blocked → backlog → finished → archived
intake`open → vetted → routed → closed(promoted \declined \absorbed)`
decision`prepared → resolved(approved \rejected \revised \deferred)`
engagementqueued → prepared → done
register-entryper existing register conventions (unchanged)
+

Promotion is a first-class transition: intake.routed → workplan | task | decision | engagement, executed by one CLI/MCP call that writes both artefacts, sets promoted_to / origin back-links, and re-syncs. Manual transcription of an intake item into other kinds is a process defect.

+

Kind-specific rigor lives in flow profiles, not extra states: named task-flow-engine workstation definitions whose entry/exit assertions encode per-work-kind gates (e.g. compliance tasks cannot exit progress without an evidence link). Profiles are YAML in repos, in the same reconciliation loop.

+
+

Residuals (role, not kind)

+

A residual is work intentionally left after a workplan (or large task bundle) finishes. It is not a registered kind — inventing a parallel “residuals queue” or parking leftovers only in SCOPE.md / finished-file prose is a process defect. Residuals must be live work records so the hub can list them across repos and domains.

+
Residual shapeCapture asRequired links
Small Green/Blue follow-up, parkableintake (e.g. AWQ / *-IN-*)origin: residual, origin_ref: <parent-WP-id>
Multi-step / dependency-bearingworkplan (spawn next WP)body or frontmatter names parent WP; optional origin/origin_ref when promoted from intake
Needs founder choicedecisionsame origin fields when created from residual intake
Needs founder time windowengagementsame
Persistent gap / riskregister-entry (risk, tech debt, …)cross-link parent WP in notes
+

Close discipline for finished workplans:

+
  1. Short residual narrative may remain under the closing task (human context).
  2. Before status: finished, each residual that is still actionable becomes a live record (intake and/or child workplan). Prose alone is not the backlog.
  3. Progress milestone may name the handoff ids.
  4. statehub fix-consistency so the index (WORK-RECORDS.md, hub) reflects the handoff.
+

Fleet list (future CLI): filter open/vetted/routed intakes (and ready/ active workplans) with origin ∈ {residual, handoff} and optional topic_id / repo / origin_ref. Implementation home for that query is state-hub (statehub residuals / API), not domain repos.

+
+

Source files, index, and views

+
  1. Any repo file is a potential source of work records. Records are authored as schema-valid YAML blocks in context — thematic live documents, meeting notes, design docs, triage logs. The schema is the contract, not the location. Workplans keep dedicated files.
  2. A generated per-repo work-record index references every registered record in its source location (transclusion-style; markitect-family tooling). It is the "everything across all files" orientation view and a concurrency cross-check.
  3. Every working list is a generated view ([auto]-marked) over indexed records — autopilot views, decision queues, engagement batches, briefs. Hand-maintained completed-logs and queue tails are retired.
  4. Ordering of views is lane + priority + age by default; dependency capture optional; WSJF optional and situational (overload triage only).
+
+

Tags

+

Two classes, both in tags, never in status:

+
  • Derived tags — computed, read-only in files: stalled, stale, overdue-decision, budget-breached, orphaned.
  • Policy tags — assigned under tagging policies: automatable, needs-human, unclear-implementation, red-adjacent, compliance-relevant, residual (optional badge when origin is not used).
+

States migrate badly; tags migrate trivially. Anything situational is a tag.

+

Origin values (intake and promoted children): use stable strings, not free prose. For residuals prefer origin: residual (or handoff) and origin_ref: <parent canonical id> (e.g. BINKY-WP-0006). Other established origins (e.g. legacy-suggestion:<uuid>, mail-triage ids) remain valid.

+
+

Budgets

+

Guardrail envelopes resolve programmatically at run start: workplan-frontmatter override → per-repo budgets.yaml (lane/default envelopes) → global best-guess default. Nothing runs unbounded. Budget resolution and enforcement is automation infrastructure, never agentic effort; metering via token events; breach ⇒ budget-breached + escalation.

+
+

Reconciliation loop (normative)

+
author (any repo file) → CI schema validation → commit
+      → fix-consistency: register/sync, UUID write-back
+      → hub read model → generated index + views → NATS events → activity-core
+

The hub remains a read model per ADR-001; runtime operations data (logs, metrics, run histories, token events) is the sanctioned DB-only exception.

+
+

References

+
  • research/WorkOrchestrationArchitectureDraft.md (v0.2)
  • research/2026-07-19-work-orchestration-infrastructure-survey.md
  • research/2026-07-19-work-orchestration-best-practices.md
  • canon/architecture/adr-001-workplans-as-repo-artefacts.md, adr-005-…
  • canon/standards/workplan-terminology-fleet_v0.1.md
  • canon/standards/autonomy-lanes_v0.1.md
  • state-hub/docs/task-flow-engine-spec.md
+
diff --git a/build/standards/work-record-types/v0.1/revisions/accepted-1/index.html b/build/standards/work-record-types/v0.1/revisions/accepted-1/index.html new file mode 100644 index 0000000..c7f38af --- /dev/null +++ b/build/standards/work-record-types/v0.1/revisions/accepted-1/index.html @@ -0,0 +1,246 @@ + + + + +Work Record Types & Identity (Fleet) v0.1 + +
canon-work-record-types accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Work Record Types & Identity (Fleet) v0.1

Source: the-custodian · canon/standards/work-record-types_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Source: research/WorkOrchestrationArchitectureDraft.md v0.2 (founder-reviewed 2026-07-20). Extends — does not replace — workplan-terminology-fleet_v0.1.md and ADR-001/ADR-005.

+

Purpose

+

Define work record as the umbrella term for every identified, lifecycle-bearing coordination artefact in the fleet; register the closed list of work-record kinds, their id schemes and abstract lifecycles; and fix the two-layer identity rule. This is the backbone convention for all work — planning, development, testing, operations, security & compliance, controlling, billing, marketing, sales — under one conceptual framework (different demands are met by flow profiles and kind-specific fields, never by parallel ontologies).

+
+

Core definition

+

A work record is any identified, lifecycle-bearing coordination artefact. A task is one kind of work record — the smallest executable unit. Every work record, regardless of kind, carries the conventional spine:

+
FieldConvention
idcanonical name per the type registry below
uuidUUIDv7, hub-assigned at first index, written back to the source file
kindone of the registered kinds
laneautonomy lane (autonomy-lanes_v0.1.md)
statusabstract lifecycle of the kind (below)
owneragent identity (agt-…) or human
repoowning repo (ADR-001/ADR-005 anchor)
tagspolicy + derived tags (§ Tags)
created / updateddates (UUIDv7 supplies fine-grained internal time)
+

Kind-specific fields (budget, evidence, counterparty, deadline_pressure, attention_cost, …) extend the spine; they never replace it.

+
+

Kind registry (closed list)

+
KindId schemeMeaningAbsorbs / legacy
`workplan`{PREFIX}-WP-NNNN · {PREFIX}-WP-ADHOC-YYYY-MM-DDstructured, dependency-bearing body of work; repository-qualified daily container for small same-day tasksunqualified ADHOC-YYYY-MM-DD; MASON-0001 (grandfathered)
`task`{WP-ID}-TNNsmallest executable unitunqualified ADHOC-YYYY-MM-DD-TNN; MASON-0001-TNN (grandfathered); issue-core issues become external projections only
`intake`{PREFIX}-IN-NNNNspark: idea, finding, directive, requesthub suggestions (legacy, read-only close-out); AWQ-NNN (grandfathered)
`decision`{PREFIX}-DEC-YYYY-NNNapproval package + resolutionDEC-YYYY-NNN (binky, grandfathered as-is)
`engagement`{PREFIX}-ENG-YYYY-NNNscheduled external interaction (counterparty, prepared material, time window)OH-YYYY-NNN (grandfathered)
`register-entry`existing schemes: RISK-NNN, RISK-F-NNNN, RISK-REG-NNNN, TD-…, CAP-…, CCR-YYYY-NNNN, ADR-NNNrisks/findings, regulatory records, technical debt, capability requests, credential change requests, architecture decisionsunchanged semantics, brought under the spine
+

Rules:

+
  1. Prefix grammar: {PREFIX} is one or more uppercase alphanumeric segments, each beginning with a letter, joined by hyphens. Both compact prefixes such as CUST and repository-derived prefixes such as RAPP-OPENBAO or RAIL-K8S are canonical. The final -WP- token remains the unambiguous kind separator.
  2. The registry is closed. An id pattern not registered in work-record-types.yaml fails CI and fix-consistency (the sidetrack detector). New kinds/prefixes are added by canon PR — deliberately cheap (one YAML entry + one schema) so the legitimate path is easier than any workaround.
  3. Grandfathering: existing ids are never renamed. Legacy prefixes map to kinds in the registry; retirement of a scheme (never of records) follows the legacy-meter discipline of workplan-terminology-fleet_v0.1.md.
+

Compatibility correction 2026-08-23: State Hub message 24504ce7-4f73-47da-a150-629b07b37073 exposed that the machine pattern did not accept the already owner-registered RAPP-OPENBAO-WP prefix. The grammar now matches ADR-007's repository-derived prefix model; prefix ownership and uniqueness remain separate registry checks and are not weakened by this syntax correction.

+

The same compatibility review initially registered unqualified ADHOC-YYYY-MM-DD containers. A same-day collision between Activity Core and Net Kingdom then demonstrated that this form violates ADR-007's fleet-namespace uniqueness rule and cannot be used with deterministic UUID derivation. New daily records therefore use {PREFIX}-WP-ADHOC-YYYY-MM-DD; the filename remains workplans/ADHOC-YYYY-MM-DD.md. Existing unqualified ids are grandfathered and are never silently re-derived or disambiguated. Ad-hoc containers remain only for low-risk work completed directly.

+

Risk Nexus findings (RISK-F-*) and regulatory records (RISK-REG-*) are registered as variants of register-entry, not as parallel work kinds. Their lifecycles remain owned by the register convention. RISK-N-* notes are deliberately not registered: a note has no lifecycle, so it does not meet the core definition of a work record. A note becomes part of the backbone only when an event promotes its substance into a lifecycle-bearing kind.

+
+

Identity layering

+
  • UUIDv7 is primary for bookkeeping, relations, dependencies, and history. It is stable across renames, migrations, and terminology transitions.
  • Canonical names are primary for humans and agents — UI, CLI, API output, prose, commits. UUIDs stay inspectable on demand but are never required reading.
  • The hub writes the UUID back into the source file at first index (pattern: today's state_hub_*_id fields).
  • A repeated source block with the same canonical id and the same UUID is one record with duplicate source occurrences. Index it once, retain every source location as diagnostic provenance, and report the duplication for governed cleanup. The repetition must not mint a second record. The same canonical id with different UUIDs is an identity collision and fails closed.
+
+

Abstract lifecycles (canon-fixed, minimal)

+
KindLifecycle
task`wait → todo → progress → done \cancel` (InfoTechCanon)
workplanproposed → ready → active → blocked → backlog → finished → archived
intake`open → vetted → routed → closed(promoted \declined \absorbed)`
decision`prepared → resolved(approved \rejected \revised \deferred)`
engagementqueued → prepared → done
register-entryper existing register conventions (unchanged)
+

Promotion is a first-class transition: intake.routed → workplan | task | decision | engagement, executed by one CLI/MCP call that writes both artefacts, sets promoted_to / origin back-links, and re-syncs. Manual transcription of an intake item into other kinds is a process defect.

+

Kind-specific rigor lives in flow profiles, not extra states: named task-flow-engine workstation definitions whose entry/exit assertions encode per-work-kind gates (e.g. compliance tasks cannot exit progress without an evidence link). Profiles are YAML in repos, in the same reconciliation loop.

+
+

Residuals (role, not kind)

+

A residual is work intentionally left after a workplan (or large task bundle) finishes. It is not a registered kind — inventing a parallel “residuals queue” or parking leftovers only in SCOPE.md / finished-file prose is a process defect. Residuals must be live work records so the hub can list them across repos and domains.

+
Residual shapeCapture asRequired links
Small Green/Blue follow-up, parkableintake (e.g. AWQ / *-IN-*)origin: residual, origin_ref: <parent-WP-id>
Multi-step / dependency-bearingworkplan (spawn next WP)body or frontmatter names parent WP; optional origin/origin_ref when promoted from intake
Needs founder choicedecisionsame origin fields when created from residual intake
Needs founder time windowengagementsame
Persistent gap / riskregister-entry (risk, tech debt, …)cross-link parent WP in notes
+

Close discipline for finished workplans:

+
  1. Short residual narrative may remain under the closing task (human context).
  2. Before status: finished, each residual that is still actionable becomes a live record (intake and/or child workplan). Prose alone is not the backlog.
  3. Progress milestone may name the handoff ids.
  4. statehub fix-consistency so the index (WORK-RECORDS.md, hub) reflects the handoff.
+

Fleet list (future CLI): filter open/vetted/routed intakes (and ready/ active workplans) with origin ∈ {residual, handoff} and optional topic_id / repo / origin_ref. Implementation home for that query is state-hub (statehub residuals / API), not domain repos.

+
+

Source files, index, and views

+
  1. Any repo file is a potential source of work records. Records are authored as schema-valid YAML blocks in context — thematic live documents, meeting notes, design docs, triage logs. The schema is the contract, not the location. Workplans keep dedicated files.
  2. A generated per-repo work-record index references every registered record in its source location (transclusion-style; markitect-family tooling). It is the "everything across all files" orientation view and a concurrency cross-check.
  3. Every working list is a generated view ([auto]-marked) over indexed records — autopilot views, decision queues, engagement batches, briefs. Hand-maintained completed-logs and queue tails are retired.
  4. Ordering of views is lane + priority + age by default; dependency capture optional; WSJF optional and situational (overload triage only).
+
+

Tags

+

Two classes, both in tags, never in status:

+
  • Derived tags — computed, read-only in files: stalled, stale, overdue-decision, budget-breached, orphaned.
  • Policy tags — assigned under tagging policies: automatable, needs-human, unclear-implementation, red-adjacent, compliance-relevant, residual (optional badge when origin is not used).
+

States migrate badly; tags migrate trivially. Anything situational is a tag.

+

Origin values (intake and promoted children): use stable strings, not free prose. For residuals prefer origin: residual (or handoff) and origin_ref: <parent canonical id> (e.g. BINKY-WP-0006). Other established origins (e.g. legacy-suggestion:<uuid>, mail-triage ids) remain valid.

+
+

Budgets

+

Guardrail envelopes resolve programmatically at run start: workplan-frontmatter override → per-repo budgets.yaml (lane/default envelopes) → global best-guess default. Nothing runs unbounded. Budget resolution and enforcement is automation infrastructure, never agentic effort; metering via token events; breach ⇒ budget-breached + escalation.

+
+

Reconciliation loop (normative)

+
author (any repo file) → CI schema validation → commit
+      → fix-consistency: register/sync, UUID write-back
+      → hub read model → generated index + views → NATS events → activity-core
+

The hub remains a read model per ADR-001; runtime operations data (logs, metrics, run histories, token events) is the sanctioned DB-only exception.

+
+

References

+
  • research/WorkOrchestrationArchitectureDraft.md (v0.2)
  • research/2026-07-19-work-orchestration-infrastructure-survey.md
  • research/2026-07-19-work-orchestration-best-practices.md
  • canon/architecture/adr-001-workplans-as-repo-artefacts.md, adr-005-…
  • canon/standards/workplan-terminology-fleet_v0.1.md
  • canon/standards/autonomy-lanes_v0.1.md
  • state-hub/docs/task-flow-engine-spec.md
+
diff --git a/build/standards/workplan-terminology/v0.1/index.html b/build/standards/workplan-terminology/v0.1/index.html new file mode 100644 index 0000000..3f13d54 --- /dev/null +++ b/build/standards/workplan-terminology/v0.1/index.html @@ -0,0 +1,236 @@ + + + + +Workplan Terminology (Fleet) v0.1 + +
canon-workplan-terminology-fleet accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplan Terminology (Fleet) v0.1

Source: the-custodian · canon/standards/workplan-terminology-fleet_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

Define workplan as the canonical fleet term for repo-backed deliverable work indexed by State Hub. Preserve explicit legacy bridges where APIs, events, generated fields, or historical documents still say workstream, until metered retirement criteria are met.

+

This standard complements:

+
  • ADR-001 — workplans originate as repo files; the hub indexes them.
  • STATE-WP-0054 — State Hub compatibility layer and legacy-meter.
  • STATE-WP-0069 — State Hub legacy interface retirement (child plan).
  • CUST-WP-0055 — fleet-wide coordination and prose migration.
+

Authoritative interface matrix for State Hub: state-hub/docs/workplan-terminology-transition.md.

+
+

Canonical term

+
ConceptFleet termMeaning
Repo-backed body of workworkplanMarkdown file under workplans/ per ADR-001
Workplan file id{PREFIX}-WP-NNNNe.g. CUST-WP-0055, STATE-WP-0069
Hub index rowworkplan (product term)DB entity keyed by UUID; may still use legacy column names internally
Task within a workplantaskid: {WP}-TNN in workplan file blocks
+
+

Work-record umbrella (v0.2 addendum, CUST-WP-0060)

+

The workplan and task definitions above are unchanged. Since v0.2 they are two kinds of the fleet umbrella term work record — any identified, lifecycle-bearing coordination artefact. The full kind registry (workplan, task, intake item, decision, engagement, register entry), the conventional spine, identity layering (UUIDv7 internal, canonical names external), and grandfathered legacy id schemes (AWQ-, DEC-, OH-) are normative in work-record-types_v0.1.md (+ machine registry work-record-types.yaml). Autonomy-lane vocabulary is normative in autonomy-lanes_v0.1.md. "Suggestion" is a legacy bridge name for the intake kind (state-hub suggestions table: read-only legacy pending close-out). This file keeps its _v0.1 name for reference stability; the frontmatter version field is authoritative.

+

Use workplan in human-facing prose: SCOPE.md, AGENTS.md, INTENT.md, README, workplan bodies, operator runbooks, and agent session guidance.

+
+

Legacy bridges (keep until retired)

+

Do not mass-rename these in the CUST-WP-0055 migration window:

+
SurfaceCanonicalLegacy bridgeRetirement owner
Workplan frontmatter link(implicit workplan UUID)state_hub_workstream_idSeparate bridge-field migration
REST/MCP parametersworkplan_idworkstream_idSTATE-WP-0069 + legacy-meter
REST routes/workplans//workstreams/STATE-WP-0069
MCP procedurescreate_workplan, etc.create_workstream, etc.STATE-WP-0069
State Hub completion eventorg.statehub.workplan.completedorg.statehub.workstream.completedSTATE-WP-0069 T05
activity-core catalog (custodian-era)org.statehub.workplan.completedorg.workstream.completedCUST-WP-0055 T03
Archived workplan proseworkplan (when editing)historical "workstream" textGrandfathered; header note only
Grandfathered filenames—paths containing workstreamADR-001 non-rename policy
+

Do not introduce a bare org.workplan.completed event subject. State Hub uses the org.statehub.* namespace.

+
+

Event subjects (normative)

+
SubjectStatusNotes
org.statehub.workplan.completedpreferredEmitted on workplan finish; subscribe here
org.statehub.workstream.completedlegacy (metered)Dual-published today; retire per legacy-meter
org.workstream.completedlegacy (catalog)activity-core custodian-era type; align to State Hub subject
+
+

Agent and documentation rules

+
  1. Write workplan in instructions, orientation steps, and error messages aimed at humans or coding agents.
  2. Mention workstream only in an explicit compatibility footnote, e.g.: > Legacy term: State Hub still exposes /workstreams and workstream_id > aliases until legacy-meter retires them (STATE-WP-0069).
  3. Leave unchanged in code or docs when the string is a wire key, route, legacy-meter registry entry, or state_hub_workstream_id frontmatter field.
  4. Prefer GET /workplans/ and workplan_id in new examples and scripts.
+

Regenerated agent files (state-hub/scripts/update_agent_instruction_files.py) should follow rules 1–2. Templates live under state-hub/scripts/project_rules/*.template.

+
+

Retirement rule (unchanged)

+

A legacy interface may be removed only when all are true:

+
  • registered in State Hub legacy-meter;
  • replacement reference verified;
  • no manual hold;
  • zero measured calls in the review window.
+

State Hub owns usage evidence; activity-core may run weekly review activities. See state-hub/docs/workplan-terminology-transition.md.

+
+

Verification

+

Fleet terminology drift is measured with:

+
python tools/scan_workstream_terminology.py
+python tools/scan_workstream_terminology.py --repo <slug> --json
+

Baseline artefact (2026-07-08): docs/evidence/workstream-terminology-baseline-20260708.json.

+

Exit criteria and scan exclusions: CUST-WP-0055 T08.

+
+

Out of scope (this standard)

+
  • Renaming state_hub_workstream_id in workplan frontmatter.
  • Database table or ORM model renames (completed in STATE-WP-0065).
  • Rewriting archived workplan bodies in bulk (CUST-WP-0055 T07).
+
+

References

+
  • canon/architecture/adr-001-workplans-as-repo-artefacts.md
  • state-hub/docs/workplan-terminology-transition.md
  • state-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md
  • state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md
  • workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md
+
diff --git a/build/standards/workplan-terminology/v0.1/revisions/accepted-1/index.html b/build/standards/workplan-terminology/v0.1/revisions/accepted-1/index.html new file mode 100644 index 0000000..3f13d54 --- /dev/null +++ b/build/standards/workplan-terminology/v0.1/revisions/accepted-1/index.html @@ -0,0 +1,236 @@ + + + + +Workplan Terminology (Fleet) v0.1 + +
canon-workplan-terminology-fleet accepted · accepted-1 the-custodian reviewed 2026-08-31generated from canonical source — do not edit

Workplan Terminology (Fleet) v0.1

Source: the-custodian · canon/standards/workplan-terminology-fleet_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93

Review due: 2027-02-28

Purpose

+

Define workplan as the canonical fleet term for repo-backed deliverable work indexed by State Hub. Preserve explicit legacy bridges where APIs, events, generated fields, or historical documents still say workstream, until metered retirement criteria are met.

+

This standard complements:

+
  • ADR-001 — workplans originate as repo files; the hub indexes them.
  • STATE-WP-0054 — State Hub compatibility layer and legacy-meter.
  • STATE-WP-0069 — State Hub legacy interface retirement (child plan).
  • CUST-WP-0055 — fleet-wide coordination and prose migration.
+

Authoritative interface matrix for State Hub: state-hub/docs/workplan-terminology-transition.md.

+
+

Canonical term

+
ConceptFleet termMeaning
Repo-backed body of workworkplanMarkdown file under workplans/ per ADR-001
Workplan file id{PREFIX}-WP-NNNNe.g. CUST-WP-0055, STATE-WP-0069
Hub index rowworkplan (product term)DB entity keyed by UUID; may still use legacy column names internally
Task within a workplantaskid: {WP}-TNN in workplan file blocks
+
+

Work-record umbrella (v0.2 addendum, CUST-WP-0060)

+

The workplan and task definitions above are unchanged. Since v0.2 they are two kinds of the fleet umbrella term work record — any identified, lifecycle-bearing coordination artefact. The full kind registry (workplan, task, intake item, decision, engagement, register entry), the conventional spine, identity layering (UUIDv7 internal, canonical names external), and grandfathered legacy id schemes (AWQ-, DEC-, OH-) are normative in work-record-types_v0.1.md (+ machine registry work-record-types.yaml). Autonomy-lane vocabulary is normative in autonomy-lanes_v0.1.md. "Suggestion" is a legacy bridge name for the intake kind (state-hub suggestions table: read-only legacy pending close-out). This file keeps its _v0.1 name for reference stability; the frontmatter version field is authoritative.

+

Use workplan in human-facing prose: SCOPE.md, AGENTS.md, INTENT.md, README, workplan bodies, operator runbooks, and agent session guidance.

+
+

Legacy bridges (keep until retired)

+

Do not mass-rename these in the CUST-WP-0055 migration window:

+
SurfaceCanonicalLegacy bridgeRetirement owner
Workplan frontmatter link(implicit workplan UUID)state_hub_workstream_idSeparate bridge-field migration
REST/MCP parametersworkplan_idworkstream_idSTATE-WP-0069 + legacy-meter
REST routes/workplans//workstreams/STATE-WP-0069
MCP procedurescreate_workplan, etc.create_workstream, etc.STATE-WP-0069
State Hub completion eventorg.statehub.workplan.completedorg.statehub.workstream.completedSTATE-WP-0069 T05
activity-core catalog (custodian-era)org.statehub.workplan.completedorg.workstream.completedCUST-WP-0055 T03
Archived workplan proseworkplan (when editing)historical "workstream" textGrandfathered; header note only
Grandfathered filenames—paths containing workstreamADR-001 non-rename policy
+

Do not introduce a bare org.workplan.completed event subject. State Hub uses the org.statehub.* namespace.

+
+

Event subjects (normative)

+
SubjectStatusNotes
org.statehub.workplan.completedpreferredEmitted on workplan finish; subscribe here
org.statehub.workstream.completedlegacy (metered)Dual-published today; retire per legacy-meter
org.workstream.completedlegacy (catalog)activity-core custodian-era type; align to State Hub subject
+
+

Agent and documentation rules

+
  1. Write workplan in instructions, orientation steps, and error messages aimed at humans or coding agents.
  2. Mention workstream only in an explicit compatibility footnote, e.g.: > Legacy term: State Hub still exposes /workstreams and workstream_id > aliases until legacy-meter retires them (STATE-WP-0069).
  3. Leave unchanged in code or docs when the string is a wire key, route, legacy-meter registry entry, or state_hub_workstream_id frontmatter field.
  4. Prefer GET /workplans/ and workplan_id in new examples and scripts.
+

Regenerated agent files (state-hub/scripts/update_agent_instruction_files.py) should follow rules 1–2. Templates live under state-hub/scripts/project_rules/*.template.

+
+

Retirement rule (unchanged)

+

A legacy interface may be removed only when all are true:

+
  • registered in State Hub legacy-meter;
  • replacement reference verified;
  • no manual hold;
  • zero measured calls in the review window.
+

State Hub owns usage evidence; activity-core may run weekly review activities. See state-hub/docs/workplan-terminology-transition.md.

+
+

Verification

+

Fleet terminology drift is measured with:

+
python tools/scan_workstream_terminology.py
+python tools/scan_workstream_terminology.py --repo <slug> --json
+

Baseline artefact (2026-07-08): docs/evidence/workstream-terminology-baseline-20260708.json.

+

Exit criteria and scan exclusions: CUST-WP-0055 T08.

+
+

Out of scope (this standard)

+
  • Renaming state_hub_workstream_id in workplan frontmatter.
  • Database table or ORM model renames (completed in STATE-WP-0065).
  • Rewriting archived workplan bodies in bulk (CUST-WP-0055 T07).
+
+

References

+
  • canon/architecture/adr-001-workplans-as-repo-artefacts.md
  • state-hub/docs/workplan-terminology-transition.md
  • state-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md
  • state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md
  • workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md
+
diff --git a/docs/adr-review/SUMMARY.md b/docs/adr-review/SUMMARY.md index cc54ebc..4672c83 100644 --- a/docs/adr-review/SUMMARY.md +++ b/docs/adr-review/SUMMARY.md @@ -5,15 +5,15 @@ Rows: 162 ## Inventory dispositions - `excluded`: 10 -- `metadata-pending`: 84 -- `published`: 60 +- `metadata-pending`: 79 +- `published`: 65 - `unsupported-format`: 8 ## Proposed dispositions - `conflict`: 5 -- `local`: 50 -- `publish`: 95 +- `local`: 52 +- `publish`: 93 - `superseded`: 12 ## Front-matter `id` collisions diff --git a/docs/adr-review/ledger.json b/docs/adr-review/ledger.json index 5e0f584..c759ddb 100644 --- a/docs/adr-review/ledger.json +++ b/docs/adr-review/ledger.json @@ -4868,8 +4868,8 @@ "review" ], "notes": "", - "proposed_disposition": "publish", - "review_notes": "Bootstrap protocol.", + "proposed_disposition": "local", + "review_notes": "Explicitly sensitivity: internal and contains internal budget/legal formation detail. Keep inventoried and off the public Policy Nexus surface.", "source_path": "canon/constitution/bootstrap-protocol_v0.1.md", "source_repo": "the-custodian", "successor": "" @@ -4899,8 +4899,8 @@ "review" ], "notes": "", - "proposed_disposition": "publish", - "review_notes": "Estate constitution.", + "proposed_disposition": "local", + "review_notes": "Custodian-owned but explicitly sensitivity: internal. Keep inventoried and off the public Policy Nexus surface.", "source_path": "canon/constitution/custodian_constitution_v0.1.md", "source_repo": "the-custodian", "successor": "" @@ -4912,22 +4912,19 @@ "file_present": true, "frontmatter": { "id": "canon-autonomy-lanes", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", + "last_reviewed": "2026-08-31", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", + "status": "accepted", "title": "Autonomy Lanes (Fleet) v0.1", "updated": "2026-07-20", "version": "0.1" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Autonomy lanes.", @@ -5097,22 +5094,19 @@ "file_present": true, "frontmatter": { "id": "canon-contrib-convention", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", + "last_reviewed": "2026-08-31", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", + "status": "accepted", "title": "Contribution Convention v0.1", "updated": "", "version": "0.1" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Contribution convention.", @@ -5492,22 +5486,19 @@ "file_present": true, "frontmatter": { "id": "canon-project-repository-flavor", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", + "last_reviewed": "2026-08-31", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", + "status": "accepted", "title": "Project Repository Flavor (prj-) v0.1", "updated": "2026-08-09", "version": "0.1" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "prj- flavor.", @@ -5820,22 +5811,19 @@ "file_present": true, "frontmatter": { "id": "canon-work-record-types", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", + "last_reviewed": "2026-08-31", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", + "status": "accepted", "title": "Work Record Types & Identity (Fleet) v0.1", "updated": "2026-08-23", "version": "0.1" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Work-record type registry.", @@ -5850,22 +5838,19 @@ "file_present": true, "frontmatter": { "id": "canon-workplan-terminology-fleet", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", + "last_reviewed": "2026-08-31", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", + "status": "accepted", "title": "Workplan Terminology (Fleet) v0.1", "updated": "2026-07-20", "version": "0.2" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Fleet workplan terminology.", diff --git a/docs/adr-review/rulings.json b/docs/adr-review/rulings.json index dc78d7d..6f14048 100644 --- a/docs/adr-review/rulings.json +++ b/docs/adr-review/rulings.json @@ -1,8 +1,8 @@ { "schema_version": 1, - "ruled_at": "2026-08-18", + "ruled_at": "2026-08-31", "workplan": "PNEX-WP-0003", - "note": "T03/T04 overlay. Regenerating the ledger merges these fields onto inventory facts. Kind 1 on a shared front-matter id is also applied automatically.", + "note": "T03/T04 overlay, amended by PNEX-WP-0004's Custodian disclosure review. Regenerating the ledger merges these fields onto inventory facts. Kind 1 on a shared front-matter id is also applied automatically.", "rulings": [ { "source_repo": "the-custodian", @@ -772,18 +772,18 @@ { "source_repo": "the-custodian", "source_path": "canon/constitution/custodian_constitution_v0.1.md", - "proposed_disposition": "publish", + "proposed_disposition": "local", "conflict_kinds": [], "successor": "", - "review_notes": "Estate constitution." + "review_notes": "Custodian-owned but explicitly sensitivity: internal. Keep inventoried and off the public Policy Nexus surface." }, { "source_repo": "the-custodian", "source_path": "canon/constitution/bootstrap-protocol_v0.1.md", - "proposed_disposition": "publish", + "proposed_disposition": "local", "conflict_kinds": [], "successor": "", - "review_notes": "Bootstrap protocol." + "review_notes": "Explicitly sensitivity: internal and contains internal budget/legal formation detail. Keep inventoried and off the public Policy Nexus surface." }, { "source_repo": "the-custodian", diff --git a/publication.json b/publication.json index f1de378..650f800 100644 --- a/publication.json +++ b/publication.json @@ -54,6 +54,46 @@ "subtitle": "A framework for describing, holding and improving multi-tenancy \u2014 including where we are not there yet.", "review_interval": "6m" }, + { + "id": "canon-autonomy-lanes", + "source_repo": "the-custodian", + "source_path": "canon/standards/autonomy-lanes_v0.1.md", + "canonical_path": "standards/autonomy-lanes/v0.1/index.html", + "revision_path": "standards/autonomy-lanes/v0.1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "canon-contrib-convention", + "source_repo": "the-custodian", + "source_path": "canon/standards/contribution-convention_v0.1.md", + "canonical_path": "standards/contribution-convention/v0.1/index.html", + "revision_path": "standards/contribution-convention/v0.1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "canon-project-repository-flavor", + "source_repo": "the-custodian", + "source_path": "canon/standards/project-repository-flavor_v0.1.md", + "canonical_path": "standards/project-repository-flavor/v0.1/index.html", + "revision_path": "standards/project-repository-flavor/v0.1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "canon-work-record-types", + "source_repo": "the-custodian", + "source_path": "canon/standards/work-record-types_v0.1.md", + "canonical_path": "standards/work-record-types/v0.1/index.html", + "revision_path": "standards/work-record-types/v0.1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "canon-workplan-terminology-fleet", + "source_repo": "the-custodian", + "source_path": "canon/standards/workplan-terminology-fleet_v0.1.md", + "canonical_path": "standards/workplan-terminology/v0.1/index.html", + "revision_path": "standards/workplan-terminology/v0.1/revisions/{revision}/index.html", + "review_interval": "6m" + }, { "id": "coulomb-estate-architecture", "source_repo": "the-custodian", diff --git a/source-inventory.json b/source-inventory.json index 2ce7d28..fd119b1 100644 --- a/source-inventory.json +++ b/source-inventory.json @@ -794,8 +794,8 @@ "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/autonomy-lanes_v0.1.md", "source_repo": "the-custodian" }, @@ -830,8 +830,8 @@ "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/contribution-convention_v0.1.md", "source_repo": "the-custodian" }, @@ -902,8 +902,8 @@ "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/project-repository-flavor_v0.1.md", "source_repo": "the-custodian" }, @@ -962,14 +962,14 @@ "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/work-record-types_v0.1.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/workplan-terminology-fleet_v0.1.md", "source_repo": "the-custodian" } diff --git a/tests/test_fetch_sources.py b/tests/test_fetch_sources.py new file mode 100644 index 0000000..530aebd --- /dev/null +++ b/tests/test_fetch_sources.py @@ -0,0 +1,57 @@ +from __future__ import annotations + +from pathlib import Path +import sys +import unittest + + +ROOT = Path(__file__).parents[1] +sys.path.insert(0, str(ROOT / "tools")) +from fetch_sources import _archive_url, _request + + +class FetchSourcesAuthenticationTest(unittest.TestCase): + def test_same_origin_request_carries_forgejo_token(self) -> None: + request = _request( + "https://forgejo.coulomb.social/api/v1/repos/coulomb/policy-nexus", + token="test-secret", + token_origin="https://forgejo.coulomb.social", + ) + + self.assertEqual("token test-secret", request.get_header("Authorization")) + self.assertNotIn("test-secret", request.full_url) + + def test_cross_origin_request_refuses_source_token(self) -> None: + with self.assertRaisesRegex(ValueError, "refusing to send source credential"): + _request( + "https://example.invalid/coulomb/policy-nexus/archive/main.tar.gz", + token="test-secret", + token_origin="https://forgejo.coulomb.social", + ) + + def test_token_and_origin_must_be_configured_together(self) -> None: + with self.assertRaisesRegex(ValueError, "must be provided together"): + _request( + "https://forgejo.coulomb.social/coulomb/policy-nexus", + token="test-secret", + ) + + def test_anonymous_request_has_no_authorization_header(self) -> None: + request = _request("https://forgejo.coulomb.social/public/repository") + + self.assertIsNone(request.get_header("Authorization")) + + def test_archive_uses_full_resolved_revision(self) -> None: + revision = "a" * 40 + + self.assertEqual( + f"https://forgejo.coulomb.social/coulomb/policy-nexus/archive/{revision}.tar.gz", + _archive_url( + "https://forgejo.coulomb.social/coulomb/policy-nexus.git", + revision, + ), + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/fetch_sources.py b/tools/fetch_sources.py index 14ed102..0c81fab 100644 --- a/tools/fetch_sources.py +++ b/tools/fetch_sources.py @@ -6,6 +6,7 @@ from __future__ import annotations import argparse import hashlib import json +import os from pathlib import Path, PurePosixPath import tarfile import tempfile @@ -13,7 +14,43 @@ import urllib.parse import urllib.request -def _revision(remote: str, branch: str) -> str: +def _url_origin(url: str) -> str: + parsed = urllib.parse.urlparse(url) + if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password: + raise ValueError(f"authenticated source URL must use an HTTPS origin: {url!r}") + return f"{parsed.scheme}://{parsed.netloc.lower()}" + + +def _credential_origin(value: str) -> str: + parsed = urllib.parse.urlparse(value) + if parsed.path not in ("", "/") or parsed.params or parsed.query or parsed.fragment: + raise ValueError("credential origin must contain only an HTTPS scheme and authority") + return _url_origin(value) + + +def _request( + url: str, *, token: str | None = None, token_origin: str | None = None +) -> urllib.request.Request: + if bool(token) != bool(token_origin): + raise ValueError("source token and token origin must be provided together") + request = urllib.request.Request(url) + if token: + expected_origin = _credential_origin(token_origin or "") + if _url_origin(url) != expected_origin: + raise ValueError( + f"refusing to send source credential outside {expected_origin}" + ) + request.add_header("Authorization", f"token {token}") + return request + + +def _revision( + remote: str, + branch: str, + *, + token: str | None = None, + token_origin: str | None = None, +) -> str: parsed = urllib.parse.urlparse(remote) parts = parsed.path.removesuffix(".git").strip("/").split("/") if parsed.scheme != "https" or len(parts) != 2: @@ -21,7 +58,9 @@ def _revision(remote: str, branch: str) -> str: owner, repo = (urllib.parse.quote(part, safe="") for part in parts) branch_name = urllib.parse.quote(branch, safe="") url = f"{parsed.scheme}://{parsed.netloc}/api/v1/repos/{owner}/{repo}/branches/{branch_name}" - with urllib.request.urlopen(url, timeout=30) as response: + with urllib.request.urlopen( + _request(url, token=token, token_origin=token_origin), timeout=30 + ) as response: revision = json.load(response).get("commit", {}).get("id", "") if len(revision) != 40 or any(char not in "0123456789abcdef" for char in revision): raise ValueError(f"{remote}: could not resolve a clean 40-hex {branch} revision") @@ -31,7 +70,7 @@ def _revision(remote: str, branch: str) -> str: def _archive_url(remote: str, revision: str) -> str: if not remote.startswith("https://") or not remote.endswith(".git"): raise ValueError(f"archive source must be an HTTPS .git URL, got {remote!r}") - return f"{remote[:-4]}/archive/{revision[:7]}.tar.gz" + return f"{remote[:-4]}/archive/{revision}.tar.gz" def _extract(archive: Path, target: Path) -> None: @@ -73,7 +112,14 @@ def _extract(archive: Path, target: Path) -> None: output.write(chunk) -def fetch(config_path: Path, destination: Path, policy_revision: str) -> dict[str, object]: +def fetch( + config_path: Path, + destination: Path, + policy_revision: str, + *, + token: str | None = None, + token_origin: str | None = None, +) -> dict[str, object]: if len(policy_revision) != 40 or any( char not in "0123456789abcdef" for char in policy_revision ): @@ -95,10 +141,14 @@ def fetch(config_path: Path, destination: Path, policy_revision: str) -> dict[st continue remote = repository["remote"] branch = repository.get("branch", "main") - revision = _revision(remote, branch) + revision = _revision( + remote, branch, token=token, token_origin=token_origin + ) url = _archive_url(remote, revision) with tempfile.NamedTemporaryFile(suffix=".tar.gz") as archive: - with urllib.request.urlopen(url, timeout=60) as response: + with urllib.request.urlopen( + _request(url, token=token, token_origin=token_origin), timeout=60 + ) as response: while chunk := response.read(1024 * 1024): archive.write(chunk) archive.flush() @@ -127,8 +177,29 @@ def main() -> int: parser.add_argument("--config", type=Path, default=Path("source-inventory.config.json")) parser.add_argument("--destination", type=Path, required=True) parser.add_argument("--policy-revision", required=True) + parser.add_argument( + "--token-env", + help="environment variable containing a Forgejo repository-read token", + ) + parser.add_argument( + "--token-origin", + help="sole HTTPS origin to which the source token may be sent", + ) args = parser.parse_args() - lock = fetch(args.config.resolve(), args.destination.resolve(), args.policy_revision) + token = None + if args.token_env: + token = os.environ.get(args.token_env, "").strip() + if not token: + parser.error(f"source token environment variable {args.token_env!r} is empty") + if bool(token) != bool(args.token_origin): + parser.error("--token-env and --token-origin must be supplied together") + lock = fetch( + args.config.resolve(), + args.destination.resolve(), + args.policy_revision, + token=token, + token_origin=args.token_origin, + ) print( json.dumps( { diff --git a/workplans/PNEX-WP-0004-fleet-standards-publication-and-ci-source-auth.md b/workplans/PNEX-WP-0004-fleet-standards-publication-and-ci-source-auth.md new file mode 100644 index 0000000..20f4e45 --- /dev/null +++ b/workplans/PNEX-WP-0004-fleet-standards-publication-and-ci-source-auth.md @@ -0,0 +1,166 @@ +--- +id: PNEX-WP-0004 +type: workplan +title: "Publish the first deferred fleet-standards batch and authenticate CI source acquisition" +domain: infotech +repo: policy-nexus +status: active +owner: the-custodian +topic_slug: policy-nexus +created: "2026-08-31" +updated: "2026-08-31" +depends_on_workplans: + - PNEX-WP-0003 +state_hub_workstream_id: "a4f65253-4aab-5a43-8a19-3d07c11da244" +--- + +# PNEX-WP-0004 — fleet standards publication and CI source authentication + +## Goal + +Publish the first coherent return from `CUST-IN-0016`: five reviewed, +Custodian-owned fleet standards. At the same time, make the scheduled Forgejo +candidate build capable of reading private source repositories through a +dedicated least-privilege credential rather than anonymous HTTP or an admin +token. + +Done means the five standards have permanent current and immutable URLs, the +source inventory and ADR-review ledger reflect the Custodian rulings, the +retained-history/currency/release gates pass, and the CI workflow fails closed +with an actionable error when its dedicated source-read credential is absent. + +## Publication batch + +| id | Source | Address series | +| --- | --- | --- | +| `canon-autonomy-lanes` | `canon/standards/autonomy-lanes_v0.1.md` | `/standards/autonomy-lanes/v0.1/` | +| `canon-contrib-convention` | `canon/standards/contribution-convention_v0.1.md` | `/standards/contribution-convention/v0.1/` | +| `canon-project-repository-flavor` | `canon/standards/project-repository-flavor_v0.1.md` | `/standards/project-repository-flavor/v0.1/` | +| `canon-work-record-types` | `canon/standards/work-record-types_v0.1.md` | `/standards/work-record-types/v0.1/` | +| `canon-workplan-terminology-fleet` | `canon/standards/workplan-terminology-fleet_v0.1.md` | `/standards/workplan-terminology/v0.1/` | + +All five are owned by `the-custodian`, reviewed on 2026-08-31, use revision +`accepted-1`, and retain a six-month review interval. Source-owner commit: +`the-custodian@4b951be`. + +## Explicit exclusions and deferrals + +- `bootstrap-protocol_v0.1.md` and `custodian_constitution_v0.1.md` declare + `sensitivity: internal`; they must not be published on the public surface. +- `repo-classification-standard_v1.0.md` remains deferred until its `active` + front-matter and body-level `Draft v1.0` statement are reconciled. +- `sbom-convention_v0.1.md` remains deferred until its authority and operating + model are reviewed against current SBOM Nexus architecture. +- The other owner repositories and all five conflict rows stay with + `CUST-IN-0016`; they are not pulled into this bounded batch. + +## CI credential boundary + +`fetch_sources.py` may accept a Forgejo token only through an environment +variable or an explicit caller-provided value. It sends the token solely to the configured +Forgejo origin over HTTPS, never prints it, never writes it to `source-lock`, +and refuses a credential for a remote on another origin. The workflow uses a +dedicated `FORGEJO_SOURCE_TOKEN` secret. Registry credentials remain confined +to registry login and are not reused for repository reads. + +Provisioning the secret is an external Custodian/platform handoff: the token +must have organization-private repository read access and no package write, +admin, cluster, or deployment authority. Code and tests may land before that +secret is installed; the scheduled workflow must fail closed until it is. + +## Tasks + +### T01 — Owner review and disclosure gate + +```task +id: PNEX-WP-0004-T01 +status: done +priority: high +state_hub_task_id: "2301c729-841b-5c5c-a9dd-aa5d4390c36b" +``` + +Review the Custodian slice, add truthful publication metadata to the five +public fleet standards, and record the internal/deferred sources explicitly in +`CUST-IN-0016`. + +Completed 2026-08-31 in `the-custodian@4b951be`. No normative body text was +changed. + +### T02 — Register and audit the five standards + +```task +id: PNEX-WP-0004-T02 +status: done +priority: high +state_hub_task_id: "a4378f0b-cf58-5dac-9f8e-2a69b07ff6e3" +``` + +Add five explicit `publication.json` entries, refresh the source inventory and +review ledger, and ensure the two internal constitution sources are never +classified as publishable output. + +Completed 2026-08-31. The explicit registry contains 65 documents; the source +audit reports 65 published and 79 metadata-pending sources. The two internal +constitution records are ruled `local` and have no publication address. + +### T03 — Authenticate private source acquisition + +```task +id: PNEX-WP-0004-T03 +status: done +priority: high +state_hub_task_id: "e0c0fa67-5a90-5990-a4e9-35e517816a7d" +``` + +Add same-origin Forgejo-token support to `fetch_sources.py`, cover header, +redaction, and cross-origin refusal behavior with unit tests, and pass only the +dedicated source token from the Forgejo workflow. Authenticate the workflow's +own archive download as well as every declared owner-repository fetch. + +Completed 2026-08-31. Five authentication-boundary tests cover same-origin +header injection, cross-origin refusal, paired token/origin configuration, +anonymous mode, and full-revision archive addressing. The complete 22-test +suite passes. Installing the read-only Forgejo Actions secret remains the +credential-owner handoff and is not a code-completion gate. + +### T04 — Build and publish the immutable candidate + +```task +id: PNEX-WP-0004-T04 +status: progress +priority: high +state_hub_task_id: "a6f789ea-5d90-55cf-b67b-5cf401b81e66" +``` + +Run `make check`, retained-history build, currency, and release verification. +Publish the OCI candidate and record its image, publication-manifest, +source-inventory, and source-set digests. + +2026-08-31: the local retained-history build, release verifier, and currency +gate pass for all 65 documents. Pre-publication identities are publication +manifest `c54efb4226f964b8af4e37cebcccda6d3becaa5db1cd9465c166392d2a87c842`, +source inventory +`b061ebc593f8e6353929eb795663d66278eca094429f139b6060e7b236e3d8d8`, and +source set +`7e0f0ee3fdf3bcdc8d34e7fc9ba12304ba84864b06c63e9226324e6aa0ea4e7f`. + +### T05 — Promote, smoke, and close + +```task +id: PNEX-WP-0004-T05 +status: todo +priority: medium +state_hub_task_id: "07c9c18d-95cf-5b09-940a-40b5ff5828a7" +``` + +Update the paired `rapp-policy-nexus` and `railiance-apps` bindings, pass +server-side admission, deploy atomically, and verify all five current and +immutable `accepted-1` URLs before closing this workplan. + +## Residuals + +- Secret provisioning and rotation remain with the credential owner surfaced + by `warden route`; no token value enters this repository or State Hub. +- `CUST-IN-0016` remains open for 26 other-owner metadata returns, two + substantive Custodian reviews, and five owner conflict rows. The two internal + constitutions are explicit local/excluded outcomes, not publication backlog.