Add Architecture Proof Register JSON Schema MVP by ifanjuang · Pull Request #35 · ifanjuang/Pantheon-Next

ifanjuang · 2026-05-31T23:21:00Z

Summary

Adds a JSON Schema Draft 2020-12 MVP proposal for the Architecture Proof Register.

This is the first technical schema proposal for issue #34.

Branch

schema/architecture-proof-register-mvp

Added files

schemas/architecture-proof-register/README.md
schemas/architecture-proof-register/shared.schema.json
schemas/architecture-proof-register/document_family.schema.json
schemas/architecture-proof-register/indexed_document_version.schema.json
schemas/architecture-proof-register/version_event.schema.json
schemas/architecture-proof-register/proof_entry.schema.json
schemas/architecture-proof-register/review_trigger.schema.json
ai_logs/2026-05-31-architecture-proof-register-schema-mvp.md

Scope

The MVP covers only:

document_family
indexed_document_version
version_event
proof_entry
review_trigger
shared vocabularies

Design posture

Store every index.
Govern the effect.
Never let the latest filename decide authority.

The schema is intentionally light:

strict governance fields
controlled metadata
no ERP-style expansion
no SQL migration
no runtime implementation

Explicitly not implemented

Postgres migrations
RLS policies
Directus collections
object storage layout
OCR
pgvector
OpenWebUI forms
Hermes skills
queue runtime
scheduler
approval engine
memory engine
connector

Notes

This PR is a proposal for review. It should not be described as a working implementation of the data platform.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d4b00046b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T23:23:22Z

+  "description": "Relation saying that evidence supports a claim, status or professional object. It records support; it does not decide truth alone.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["proof_entry_id", "scope_id", "professional_object_type", "claim_or_status", "proof_status", "approval_state"],


Require an indexed version before accepting proof

When proof_status is accepted_as_support and approval_state is a governed approval such as approved_for_contractual_action, this schema still validates an entry with neither source_document_version_id nor any evidence_refs. That permits an unsupported claim to be represented as approved, contrary to the folder README's core rule that professional claims reference an indexed version and the implementation spec's rule No professional proof without an indexed version. Add a conditional requirement for an indexed source version before support can be accepted or approved for use.

Useful? React with 👍 / 👎.

Accepted and fixed.

proof_entry.schema.json now requires both:

source_document_version_id evidence_refs with minItems: 1

when either:

proof_status = accepted_as_support

or approval_state is one of the governed approved states:

approved_for_internal_use approved_for_meeting_preparation approved_for_transmission_draft approved_for_contractual_action

This keeps the MVP aligned with the rule: no professional proof without an indexed version.

chatgpt-codex-connector · 2026-05-31T23:23:22Z

+      "if": { "properties": { "external_effect_possible": { "const": "unknown" } }, "required": ["external_effect_possible"] },
+      "then": { "properties": { "decision_gate_required": { "const": true } } }


Gate known external effects as well as unknown ones

For a C3 trigger with external_effect_possible: "yes", the schema accepts decision_gate_required: false; only the "unknown" case is forced through a gate. This leaves the known external-effect path unguarded even though the implementation spec requires external effects to remain gated and the shared vocabulary already defines C3_external_effect as a gate reason. Extend this condition to cover "yes" as well.

Useful? React with 👍 / 👎.

Accepted and fixed.

review_trigger.schema.json now gates known external C3 effects as well:

consequence_level = C3_client_commitment external_effect_possible = yes

forces:

decision_gate_required = true requires_user_decision_gate = true

The existing unknown case remains gated too.

chatgpt-codex-connector · 2026-05-31T23:23:22Z

+    "requires_user_decision_gate": { "type": "boolean" },
+    "decision_gate_required": { "type": "boolean" },


Keep the two decision-gate flags consistent

The schema requires both gate flags but does not relate them, so a C4/C5 trigger can validate with decision_gate_required: true and requires_user_decision_gate: false. The existing urgent-triage form exposes requires_user_decision_gate, making contradictory records unsafe for consumers that read that established field. Remove the duplicate field or enforce equality between the two values.

Useful? React with 👍 / 👎.

Accepted with nuance and fixed.

The two fields are kept because they express different layers:

requires_user_decision_gate = system signal / recommendation decision_gate_required = governed final requirement

But the unsafe contradiction is now prevented:

if decision_gate_required = true then requires_user_decision_gate = true

C4/C5, C3 external effect, and unknown external effect cases now force both flags to true.

ifanjuang · 2026-05-31T23:27:20Z

Review pass

Verdict: acceptable as a lightweight schema proposal after two corrections.

Corrections applied on branch:

1. indexed_document_version.index_label is no longer required.
   Reason: the model allows unqualified capture, and index_label_missing is a valid review trigger.

2. shared.anchor.note now has minLength: 1.
   Reason: when anchor.type = other, the note must explain the non-standard anchor and must not be an empty string.

Review status:

Accepted: five-object MVP, shared vocabulary file, strict governance fields, controlled metadata.
To verify later: whether validators used by the project resolve pantheon:// $id references without custom resolver.
Not implemented: SQL, DB, runtime, Directus, OpenWebUI, Hermes, queue, approval engine.

This PR remains a schema proposal, not a working data platform implementation.

ifanjuang · 2026-06-01T05:29:16Z

Review verdict — strong work, keep isolated as a proposal until aligned

The business modeling here is the best concrete artifact in the repo: faithful phase_code (DIAG…GPA), a graded source_authority_level, append-only version_event, and review_trigger with conditional logic (if consequence_level C4/C5 → decision_gate_required const true). Governance encoded in the schema, strict (additionalProperties: false). Good.

It is also the right first slice for #34.

Decision: keep it isolated as a "proposal" for now; do not fold into the canonical baseline yet

It diverges from the existing schemas/ conventions (this is exactly the scope of #37):

Format — baseline schemas are .schema.yaml; this MVP is .schema.json. Owner decision: YAML everywhere. Convert before integration.
$ref resolver — pantheon://... $id/$ref are not resolvable by the existing test harness (jsonschema without a custom resolver), so these schemas can't be validated as-is.
x-boundary — every baseline schema carries an x-boundary block (a test asserts it); this MVP has none.
Examples + test — no example fixtures and not in the test map, so zero conformance coverage.
Scope enum — introduces a third scope vocabulary (project/phase/lot/agency_library/global_reference/external_project_subset). Owner decision: one general scope enum + documented domain extensions — so a common base shared with task_contract/manifest, plus the architecture-specific values as an extension. Align to that.
consequence_level C0–C5 sits next to approval C0–C5 (APPROVALS). Keep them clearly distinct (risk/consequence ≠ approval ceiling) to avoid collapse.

Suggested path

Land/keep this branch as an explicit proposal subfolder (schemas/architecture-proof-register/, status: proposal), not as canonical baseline.
Do the alignment (YAML, x-boundary, one example + test entry, shared scope enum + extensions, resolver-friendly refs) as a deliberate pass under Schema reconciliation (Phase D3): align schemas/ with current doctrine #37, with this proof register as the first client. CI pytest wiring is intentionally deferred to Schema reconciliation (Phase D3): align schemas/ with current doctrine #37.

Net: excellent on the domain, premature on conventions. Isolate now, align deliberately — don't rework it against a moving target.

Related: #34, #37.

Generated by Claude Code

…ciliation

ifanjuang · 2026-06-01T05:53:22Z

Disposition of Claude Code review

Accepted as direction.

Decision:

PR #35 remains an isolated proposal.
It is not the canonical schema baseline.
Formal alignment is deferred to #37.

Accepted:

- the domain model is the right first slice for #34
- keep this folder explicitly proposal-only for now
- do not treat it as runtime or data-platform implementation
- defer x-boundary / governance_refs / examples / tests / shared scope alignment to #37

To verify under #37:

- final schema file format convention
- resolver strategy for pantheon:// refs or replacement with resolver-friendly relative refs

To arbitrate under #37:

- one general scope enum plus architecture-domain extensions
- naming distinction between risk consequence levels and approval ceilings

I updated schemas/architecture-proof-register/README.md to state the integration status explicitly.

ifanjuang added 8 commits June 1, 2026 01:16

Add architecture proof register schema README

f6e8490

Add shared schema vocabularies

f80ce15

Add document family schema

24dc463

Add indexed document version schema

b22be66

Add version event schema

74d4e9d

Add proof entry schema

cf37a46

Add review trigger schema

dcf1895

Log architecture proof register schema MVP proposal

d4b0004

ifanjuang mentioned this pull request May 31, 2026

Implement Architecture Proof Register MVP #34

Open

chatgpt-codex-connector Bot reviewed May 31, 2026

View reviewed changes

ifanjuang added 2 commits June 1, 2026 01:25

Relax index label requirement for unqualified capture

12f92a1

Require non-empty note for other anchors

dd91843

ifanjuang added 2 commits June 1, 2026 01:51

Require evidence for accepted or approved proof entries

41e1869

Gate external effects and align decision flags

a3a9b6f

ifanjuang mentioned this pull request May 31, 2026

Fix governance CI lint false positive on the word "queue" #40

Closed

ifanjuang mentioned this pull request Jun 1, 2026

Coordination: prefer PRs over direct-to-main, and pause doctrine sprawl #41

Open

Mark proof register schemas as isolated proposal pending schema recon…

43065ac

…ciliation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Architecture Proof Register JSON Schema MVP#35

Add Architecture Proof Register JSON Schema MVP#35
ifanjuang wants to merge 13 commits into
mainfrom
schema/architecture-proof-register-mvp

ifanjuang commented May 31, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

ifanjuang May 31, 2026

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

ifanjuang May 31, 2026

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

ifanjuang May 31, 2026

Uh oh!

ifanjuang commented May 31, 2026

Uh oh!

ifanjuang commented Jun 1, 2026

Uh oh!

ifanjuang commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		"if": { "properties": { "external_effect_possible": { "const": "unknown" } }, "required": ["external_effect_possible"] },
		"then": { "properties": { "decision_gate_required": { "const": true } } }

		"requires_user_decision_gate": { "type": "boolean" },
		"decision_gate_required": { "type": "boolean" },

Conversation

ifanjuang commented May 31, 2026

Summary

Branch

Added files

Scope

Design posture

Explicitly not implemented

Notes

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

ifanjuang May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

ifanjuang May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

ifanjuang May 31, 2026

Choose a reason for hiding this comment

Uh oh!

ifanjuang commented May 31, 2026

Review pass

Uh oh!

ifanjuang commented Jun 1, 2026

Review verdict — strong work, keep isolated as a proposal until aligned

Decision: keep it isolated as a "proposal" for now; do not fold into the canonical baseline yet

Suggested path

Uh oh!

ifanjuang commented Jun 1, 2026

Disposition of Claude Code review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant