diff --git a/.github/workflows/doc-lint.yml b/.github/workflows/doc-lint.yml index 9f2f2e82..878a5154 100644 --- a/.github/workflows/doc-lint.yml +++ b/.github/workflows/doc-lint.yml @@ -1,8 +1,7 @@ -# Doc-Lint CI Workflow — DGAF-Framework (Spine Repo) -# Mirrors sentinel-governance/.github/workflows/doc-lint.yml -# Pattern: P-24 (Canonical Practice Unit) | P-11 (11Q gate 7 — Surface Consistency) -# Owner: Agent Sentinel -# Activated: Session S031 — closes last CI coverage gap in PHDGE ecosystem +# Doc-Lint CI Workflow — DGAF-Framework +# Public/current documentation quality gate. +# Historical and append-only evidence records are governed separately so +# presentation linting does not rewrite or invalidate provenance. name: Doc Lint @@ -25,7 +24,7 @@ on: jobs: markdownlint: - name: Markdown Lint + name: Markdown Lint — Current Surface runs-on: ubuntu-latest steps: - name: Checkout @@ -36,29 +35,33 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '20' + node-version: '24' - name: Install markdownlint-cli run: npm install -g markdownlint-cli@0.39.0 - - name: Run markdownlint + - name: Run markdownlint on current/public surfaces run: | markdownlint \ --config .markdownlint.yml \ --ignore node_modules \ --ignore CHANGELOG.md \ --ignore SWEEP_LOG.md \ + --ignore docs/evidence/** \ + --ignore docs/archive/** \ + --ignore docs/historical/** \ + --ignore docs/audit/** \ + --ignore docs/experiment/** \ '**/*.md' - # CHANGELOG.md and SWEEP_LOG.md: auto-generated append-format; excluded from lint - # All gate specs, protocols, READMEs, SESSION_ANCHOR, CROSS_REF enforced + # Evidence, archive, historical, audit, and experiment records remain + # subject to their own provenance/evidence controls. This job protects + # the reader-facing/current documentation surface from legacy corpus debt. - name: Report summary if: always() run: | echo "## Doc Lint Summary — DGAF-Framework" >> $GITHUB_STEP_SUMMARY echo "- Linter: markdownlint-cli 0.39.0" >> $GITHUB_STEP_SUMMARY - echo "- Config: .markdownlint.yml" >> $GITHUB_STEP_SUMMARY - echo "- Excluded: CHANGELOG.md, SWEEP_LOG.md (append-format auto-generated)" >> $GITHUB_STEP_SUMMARY - echo "- Pattern gates: P-24 (CPU surface consistency) + P-11 gate 7" >> $GITHUB_STEP_SUMMARY - echo "- Owner: Agent Sentinel | Spine repo: DGAF-Framework" >> $GITHUB_STEP_SUMMARY - echo "- Mirror of: sentinel-governance/.github/workflows/doc-lint.yml (S029)" >> $GITHUB_STEP_SUMMARY + echo "- Node.js: 24" >> $GITHUB_STEP_SUMMARY + echo "- Scope: current/public documentation surface" >> $GITHUB_STEP_SUMMARY + echo "- Separate provenance surfaces: evidence, archive, historical, audit, experiment" >> $GITHUB_STEP_SUMMARY diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index d09ef85b..905abbb6 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -1,132 +1,58 @@ -# BOOTSTRAP.md — DGAF Workspace Quickstart +# DGAF Workspace Bootstrap -> **Version:** 2.1.0 | **Last updated:** 2026-08-15 | **Status:** Project-local operating document +> **Audience:** maintainers and contributors starting a project work session. +> **Scope:** project-local operating guidance. For public project orientation, start with [`README.md`](README.md). -This is the workspace bootstrap for a new session, agent instantiation, or onboarding run. It identifies the current project-local operating order and points to the evidence and audit surfaces that must be checked before synthesis. +This document provides a lightweight starting sequence for working inside the DGAF repository. It is an operating aid, not a statement of external certification, compliance, or system capability. ---- +## Start here -## 1. Workspace Identity +Before making a substantive change: -| Field | Value | -|---|---| -| Framework | DGAF — Dynamic Governance Agentic Formation | -| Primary repo | `ndrorchestration/DGAF-Framework` | -| Governance model | Project-local multi-agent governance/orchestration model | -| Co-orchestration pair | Amethyst (QA lens) × COLLEEN (Evaluation/Archive lens) | -| Safety supervisor | Sentinel-Phi (project role) | -| Trace/audit sink | Herald → JSONL + n8n webhook | -| Pattern authority | COLLEEN (project-local Librarian/Auditor/Actualizer role) | - -**Epistemic boundary:** Project personas, governance roles, tiers, and approval labels are internal mechanisms. They are not independent certification authorities and do not establish legal compliance, external accreditation, or production readiness by themselves. - ---- - -## 2. First-Run Checklist (Every Session) - -- [ ] Read `SESSION_ANCHOR.md` — confirms last known state, open items, active cycle -- [ ] Read `CO_ORCH_QUEUE.md` — confirms active OPP batch and cycle number -- [ ] Read `registry/PATTERN_REGISTRY_v2.md` — confirms active patterns -- [ ] Read `CROSS_REF.md` — confirms cross-repo alignment -- [ ] Read `CHANGELOG.md` — confirms last committed changes -- [ ] Check `SWEEP_LOG/` — read most recent sweep file -- [ ] Confirm `docs/RD_GAPS.md` — check open R&D items before proceeding -- [ ] Classify new material using the project evidence ladder before treating it as established fact - ---- - -## 3. Canonical File Map - -``` -DGAF-Framework/ -├── BOOTSTRAP.md ← YOU ARE HERE -├── SESSION_ANCHOR.md ← Session state, open items, last stamp -├── CHANGELOG.md ← All commits, versioned -├── CO_ORCH_PROTOCOL.md ← Execution flow, triad roles -├── CO_ORCH_QUEUE.md ← Active OPP improvement queue -├── CROSS_REF.md ← Cross-repo alignment map -├── ENSEMBLE_ROSTER.md ← Agents, roles, L-levels -├── AGENT_MANIFEST.md ← Agent instantiation contracts -├── AGENT_INSTANTIATION.md ← Instantiation procedures -├── GRADUATION_REPORT.md ← Historical graduation record -├── README.md ← Public-facing overview -├── README.governance.md ← Governance protocol reference -├── README.technical.md ← Technical architecture reference -├── patterns/ ← NDR pattern files (P-*.md) -├── registry/ -│ ├── PATTERN_REGISTRY_v2.md ← Master pattern registry -│ └── AMETHYST_COLLEEN_CO_ORCH_CONTRACT_v1.json -├── docs/ -│ ├── TEAM_WIKI.md ← Team onboarding, roles, governance map -│ └── RD_GAPS.md ← Open R&D gap log -├── SWEEP_LOG/ -│ └── SWEEP_*.md ← Per-session sweep logs -├── pptl/ ← Phi-pentagon test layer -├── tests/ ← pytest governance harness -└── scripts/ ← Automation scripts -``` - ---- - -## 4. Authority and Evidence Order - -**Instruction order** is separate from **epistemic evidence strength**. - -### Operating instruction order - -1. User instruction -2. Project-local host/space instructions -3. Current project operating constraints -4. Repository-local documentation -5. Default assistant behavior - -### Evidence ladder - -**DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED** - -A project-local approval, Gold Star/S-Tier designation, persona sign-off, or rubric score does not automatically upgrade a claim on this ladder. - ---- - -## 5. Non-Negotiables - -- Refresh relevant context before synthesis. -- Update the pattern registry before implementation when a new pattern is actually introduced. -- Pair substantive outputs with a coherence and quality sweep. -- Do not represent S-Tier or Gold Star as external certification. -- Update logging and documentation when the change materially affects project state. -- Irreversible actions require the applicable HITL gate. -- Preserve failed experiments and superseded claims as historical evidence rather than silently converting them into current facts. -- Numeric thresholds must identify their provenance: computed, externally sourced, empirically fitted, arbitrary engineering parameter, or other appropriate category. -- Named mathematical constructs must correspond to the mathematics actually implemented; metaphorical labels must be marked as such. - ---- - -## 6. Quick-Start for Agents - -```python -# Minimal session bootstrap -from dgaf.bootstrap import load_session_anchor, load_co_orch_queue, load_pattern_registry - -anchor = load_session_anchor() -queue = load_co_orch_queue() -reg = load_pattern_registry() - -print(f"Active cycle: {queue['active_cycle']}") -print(f"Open OPPs: {[o for o in queue['opps'] if o['status'] == 'OPEN']}") -print(f"Active patterns: {len(reg['patterns'])}") -``` +1. Check [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md) for the current authoritative project state. +2. Review the files and specifications relevant to the task rather than loading unrelated historical material. +3. Check [`CHANGELOG.md`](CHANGELOG.md) and applicable open issues or pull requests when recent changes matter. +4. Classify new claims and results according to the repository's evidence policy before presenting them as established. + +For a research or experimental task, follow the applicable protocol and governance record; this bootstrap does not override candidate, freeze, authorization, or evidence boundaries. + +## Repository orientation ---- - -## 7. Escalation Contacts - -| Trigger | Route To | +| Need | Starting point | |---|---| -| Governance breach | Sentinel-Phi → Amethyst (project roles) | -| Coherence failure | COLLEEN → Amethyst (project roles) | -| Safety / ethics | DemiJoule (project role) | -| Architectural decision | Reson → Amethyst (project roles) | -| Human approval required | HITL queue → User | +| Public project overview | [`README.md`](README.md) | +| Current project state | [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md) | +| Project status and evidence boundary | [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) | +| Technical architecture | [`README.technical.md`](README.technical.md) | +| Governance model | [`README.governance.md`](README.governance.md) | +| Agent authority | [`docs/agents/AGENT_AUTHORITY_MATRIX.md`](docs/agents/AGENT_AUTHORITY_MATRIX.md) | +| Experimental work | [`docs/experiment/`](docs/experiment/) | +| Evidence policy | [`docs/evidence/EVIDENCE_LADDER_POLICY.md`](docs/evidence/EVIDENCE_LADDER_POLICY.md) | +| Historical material | [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) | + +## Working principles + +- **Use the current authority for the question at hand.** Do not infer current state from an older summary when a living record exists. +- **Separate instruction from evidence.** A project workflow may direct an action without establishing that a resulting claim has been verified. +- **Keep authority explicit.** Project agent roles and automation components operate under repository-defined contracts; they are not independent authorities. +- **Preserve provenance.** Do not silently rewrite historical claims or results to make them appear current. +- **Scope results correctly.** Tests and evaluations establish only the behavior and evidence boundary they actually cover. +- **Use human approval where the applicable control requires it.** + +## Evidence vocabulary + +The repository uses explicit epistemic classifications. Consult the evidence policy for authoritative definitions and promotion rules. In particular, implementation, a passing test, an attestation, and a demonstrated real-world result are different kinds of evidence. + +## Session hygiene + +For changes that materially affect repository behavior, governance, experiment design, or public claims: + +- update the appropriate authoritative documentation; +- add or update tests when behavior changes; +- preserve links between evidence and the artifact or execution that produced it; +- avoid promoting historical evidence to current verification without an explicit basis; +- review the public surface when a change affects reader-facing material. + +## Historical workspace records -*Historical project roles and terminology are retained for provenance. They should not be represented as independent authorities.* +Older session anchors, orchestration queues, sweep logs, and agent-role records remain part of the repository's history. They may be useful for provenance or recovery, but should not automatically be treated as current operating authority. See the [Legacy Documentation Status Policy](docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md). diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a6142a6..f0a22417 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,33 @@ # CHANGELOG.md -> **Steward:** COLLEEN · **Orchestrator:** Amethyst +## [2026-08-29] — Public Documentation Surface Refactor + +### Documentation architecture and reader experience + +- Refocused the root `README.md` as a public project entry point organized around identity, value, architecture, current status, evidence, research tracks, and contribution paths. +- Refocused `README.technical.md` as an engineer/researcher-facing implementation map rather than an agent-session and audit-log surface. +- Reworked `README.governance.md` to distinguish DGAF governance design from external legal/regulatory compliance and certification claims. +- Reworked contributor and workspace guidance to reduce internal-process overload and improve task-oriented navigation. +- Reworked component, PPTL, roster, and team-wiki documentation to separate implementation descriptions from historical attestation, authority, and efficacy claims. +- Added `docs/governance/DOCUMENTATION_STYLE_GUIDE.md` defining audience, hierarchy, claim presentation, temporal scope, navigation, and public-facing writing rules. +- Added `docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md` defining the repository's landing → project → technical → research → evidence → historical information architecture. +- Added `docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md` defining Current / Historical / Superseded / Reference Only / Draft treatment for retained records. +- Added `docs/HISTORICAL_RECORDS_INDEX.md` as a navigation layer for preserved project history. +- Expanded `PUBLIC_SURFACE_QA_STANDARD.md` to include explicit communication-quality, hierarchy, reader-friction, and historical-placement controls. +- Classified obsolete `DEFERRED_ITEMS.md` and `CI_CD_TEMPLATES.md` snapshots as historical records rather than current operational sources. +- Preserved technical specifications, experiment protocols, evidence records, and audit history at their appropriate depth rather than flattening them into public-facing prose. + +### Claim and provenance discipline + +- Replaced prominent historical `S-TIER`, `Gold Star`, certification, compliance, and production-readiness presentation with scoped descriptions on high-level surfaces. +- Preserved historical evidence while preventing current documentation from silently inheriting obsolete status claims. +- Distinguished engineering verification from experimental authorization and empirical efficacy throughout public-facing documentation. + +### Experimental boundary + +- **No implementation or experimental state is changed by the documentation refactor.** +- Current PDMAL status remains **PRE-FREEZE / FAIL-CLOSED / NOT AUTHORIZED / N=0**. +- Historical verification remains scoped to the exact source, environment, deployment, run, and artifact that produced it. --- @@ -45,91 +72,3 @@ Commercial status, repository visibility, sponsorship, project attestation, and ### Provenance rule The v0.7.5 release identity, published release-asset SHA-256, inner runtime-artifact SHA-256, and eventual post-#65 freeze HEAD SHA are distinct identities and must not be substituted for one another. - ---- - -## [Post-S077] — 2026-06-29 - -### Autonomous Sprint — Amethyst execution authority - -#### AHG v1.2 — External Review Integration -- **`docs/theory/AHG_ARCHITECTURE.md` → v1.2:** - - Canonical φ computation via logistic normalization: φ(t) = 1 + 0.8·σ(S(t)); range bounded [1.0, 1.8] - - Stability Index S(t) = w_1·D_e + w_2·N + w_3·C + w_4·R (only D_e enters; D_explore, D_correct excluded) - - D disaggregated into D_explore, D_correct, D_e (three named subtypes; D_correct is Apogee Auditor fuel) - - 7-state regime table (Grounded / Flow / Vigilance / Expansion / Integration / Introspection / Tension) - - Integration band (1.60–1.70) explicitly named — NDR-STASIS φ=1.618 aligned as peak productive phase - - Tension threshold revised 1.70 → 1.80 (1.70–1.80 is now Introspection, not Tribunal) - - §2.7 Cognitive Phase Space (3D manifold: Exploration↔Exploitation, Consensus↔Dissent, Confidence↔Uncertainty) - - §6 Performance Claims — falsifiable eval targets added (20–40% hallucination reduction; Time-to-Stability; Entropy Recovery Rate) - - Tribunal recovery protocol updated to consult 3D phase position for path selection - - Heartbeat payload expanded to include D_explore_signal, D_correct_signal -- **`patterns/P-42_AHG.md` → v1.2:** 7-state regime table; logistic formula; D_correct in vocabulary; Tension threshold 1.80 -- **`CHANGELOG.md`:** This entry -- **Source:** External AHG-MAS peer review document (Adaptive Harmonic Governance: A Stability-Guided Framework for Multi-Agent Systems) - -#### P-42 Collision Fix (prev commit b705834) -- `patterns/P-42_AHG.md` created (renumbered from P-35) -- `docs/theory/AHG_ARCHITECTURE.md` v1.1 -- `CROSS_REF.md` v4.4 -- `docs/ndr_patterns_unified.json` v2.2 -- `docs/ECOSYSTEM_INVENTORY.md` updated -- `ENSEMBLE_ROSTER.md`, `SESSION_ANCHOR.md` updated - -#### P-35_AHG.md deletion (prev commit 6b6033e) -- Stale `patterns/P-35_AHG.md` deleted - -#### Earlier commits -- `e410ae4`: `CROSS_REF.md` v4.3 + `SESSION_ANCHOR.md` + `ENSEMBLE_ROSTER.md` -- `e34af32`: `docs/theory/AHG_ARCHITECTURE.md` v1.0 + `patterns/P-35_AHG.md` (stale, now deleted) -- `5ed1a85`: `docs/agents/PROFESSOR_PRODIGY_KB.md` v1.0 -- `b8cf383`: `DEFERRED_ITEMS.md` — S-01–S-08 -- `dd2f319`: entrepreneur-hub sweep-reminder + preflight - ---- - -## [S071] — 2026-06-28 - -- P-37 Stochastic-Deterministic Saga Boundary registered -- P-38 Circuit-Breaker with HITL Escalation registered -- P-39 ACRFence registered -- P-40 Atomix Transactional Tool Boundary registered -- P-41 Sentinel-Phi HITL Durable Queue registered -- Layer 10 (Resilience & Recovery) and Layer 11 (Transactional Integrity) established -- Registry watermark advanced to P-41 -- `topology_router.py` v3.6.0 — 8/8 TC passing -- `lifecycle_stability_report.json` created - ---- - -## [S070-r3-P1] — 2026-06-26 - -- CONSENSUS_TRIAD and CONDUCTED_TRIAD formation patterns registered -- PDMAL-φ / PDMAL-D variant status canonicalized -- Triadic telemetry guidance appended to unified registry -- Eval Terminology Index (S068) added to CROSS_REF -- `docs/lifecycle_harness_v2.md` created -- `docs/ECOSYSTEM_INVENTORY.md` created - ---- - -## [S069] — 2026-06-13 · Ender ratified - -- P-35 Procluding Premise Gate registered and ratified -- P-36 Gate Priority Schema registered and ratified -- STASIS-CANONICAL status ratified (migration window 2026-06-13 → 2026-07-13) -- `ndr_patterns_unified.json` v2.1 -- v3 named session patterns absorbed into unified registry -- `ndr-pattern-registry-v3.md` deleted - ---- - -## [S066] — 2026-05-30 · Ender ratified - -- P-34 Empirical-Threshold-Sweep A-TIER 94.5% attested -- Phase 3 unified merge — Triumvirate -- Registry watermark P-34 - ---- - -*CHANGELOG · Amethyst × COLLEEN · Updated 2026-08-25* diff --git a/CI_CD_TEMPLATES.md b/CI_CD_TEMPLATES.md index 491f320f..97bbea18 100644 --- a/CI_CD_TEMPLATES.md +++ b/CI_CD_TEMPLATES.md @@ -1,49 +1,28 @@ -""" -CI/CD Template Matrix for All 25 Repositories -============================================== +# CI/CD Template Matrix — Historical Planning Record -DEPLOYMENT COMPLETE — SECTION C -=============================== +> **Status:** Historical planning/session record. This file does not describe the repository's current CI/CD coverage or current workflow configuration. +> +> **Current CI/CD:** Inspect [`.github/workflows/`](./.github/workflows/) and the relevant GitHub Actions runs for the authoritative implementation and execution state. -✅ DEPLOYED IN THIS SESSION (8 workflows): - ├─ DGAF-Framework (Python) - ├─ junior-apogee-app (Python) - ├─ resumeapex-eval (Python) - ├─ 3d-visualization-hub (Python) - ├─ sentinel-governance (Python + Governance) - ├─ Driftwatch (TypeScript) - ├─ pptl-governance-dashboard (TypeScript) - └─ ndrorchestration (TypeScript) +## Purpose of this record -STATUS: All Tier 1 production repos now have CI/CD -Coverage: 8/25 repos (32% of portfolio) -Quality Gates: Testing, coverage, linting, type-checking, security scanning +This document preserves an earlier portfolio-wide CI/CD planning snapshot. Its repository counts, deployment statements, workflow inventory, and graph-analysis notes reflect the state of that planning session and should not be generalized to the current portfolio. ---- +## Historical context -SECTION D: GRAPH ALGORITHMS REVIEW -=================================== +The record documented an effort to establish baseline testing, coverage, linting, type checking, and security scanning across a group of repositories. It also captured proposed graph-analysis areas involving PDMAL topology and orchestration structures. -Ready to analyze graph structures in your codebase: +Those statements are retained as historical planning context, not as current deployment certification or portfolio-wide coverage evidence. -1. PDMALGraph (DGAF-Framework) - ├─ Adjacency list representation - ├─ Edge weight normalization - └─ Convergence monitoring +## Current use -2. Ensemble routing patterns - ├─ Sequential traversal (10-step gates) - ├─ Multi-agent synthesis - └─ Convergence detection +For current work: -3. Agent orchestration - ├─ Trust graph topology - ├─ Path finding (amethyst → destination) - └─ Conflict resolution +1. inspect the workflow files that are actually present; +2. inspect the status of the relevant commit or pull request; +3. treat a workflow definition separately from a successful execution; +4. use current project-status and evidence documents for claims about verification. ---- +## Related policy -STARTING SECTION D NOW -====================== - -""" +See [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](./docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) for the repository policy governing historical operational records. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 765bd30e..dc6e2354 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,69 +1,80 @@ # Contributing -> **Governance:** DGAF / Agent Amethyst — changes are subject to repository integrity and governance checks before merge. See the public documentation spine and `CROSS_REF.md` for current boundaries. +DGAF welcomes technically rigorous contributions that improve the implementation, research apparatus, documentation, or reproducibility of the project. The goal is to make changes easy to understand, review, reproduce, and maintain. -## Scope +> **Governance boundary:** Contribution and CI processes establish engineering evidence; they do not by themselves create an experimental freeze or grant pilot authorization. -DGAF is the implementation and governance substrate for agent orchestration, evaluation, provenance, and epistemic controls. The broader ecosystem also contains Pattern Commons material, research artifacts, specialized registries, and adjacent repositories. Do not assume an artifact belongs in DGAF merely because DGAF references or implements it. +## Before you change something -## Development +1. Identify the component and its current authoritative documentation. +2. Check `docs/CURRENT_STATE.md` and `CROSS_REF.md` when the change touches status, terminology, patterns, evidence, or cross-repository relationships. +3. Search for an existing implementation, specification, registry entry, or historical record before creating a duplicate. +4. Decide whether the change is implementation, documentation, research, evidence, governance, or maintenance work. -- Keep changes small and reviewable. -- Prefer explicit, versioned documentation over informal notes. -- Update `CHANGELOG.md` for every meaningful change following Keep a Changelog conventions. -- Preserve historical evidence; correct current-state labels rather than silently rewriting history. -- Do not introduce absolute validation, performance, safety, certification, or completeness claims without corresponding evidence. +## Development principles -## Pattern Commons and registry hygiene +- Keep changes focused and reviewable. +- Prefer explicit contracts and versioned documentation over informal assumptions. +- Preserve historical evidence when it has provenance value; correct current-state references rather than rewriting history. +- Match claims to their evidence boundary. A test result describes what that test established; it does not automatically generalize to the whole repository. +- Avoid introducing new terminology when an existing canonical term already describes the concept. +- When a new term is necessary, define it, identify its scope, and record its relationship to existing vocabulary. + +## Documentation quality + +Documentation is part of the public engineering surface. Follow [`docs/governance/DOCUMENTATION_STYLE_GUIDE.md`](docs/governance/DOCUMENTATION_STYLE_GUIDE.md) and [`docs/governance/PUBLIC_SURFACE_QA_STANDARD.md`](docs/governance/PUBLIC_SURFACE_QA_STANDARD.md). + +In particular: -- Before creating a new pattern, search the ecosystem for existing definitions, registries, aliases, and cross-listings. -- Use `docs/PATTERN_COMMONS_ARCHITECTURE.md` to distinguish NDR, DGAF orchestration patterns, external patterns, and adjacent registry classes. -- Do not create duplicate canonical definitions merely because a pattern is useful to DGAF. Prefer a cross-reference/adapter record when another repository is authoritative. -- Shared identifiers or terminology are not sufficient evidence of semantic equivalence. -- Pattern records should expose provenance, mechanism, scope, evidence status, and epistemic boundaries. +- Give each document a clear job and audience. +- Lead with the information the reader needs most. +- Prefer concise positive descriptions of what is known over repeated defensive caveats. +- Keep detailed audit and predicate information in evidence/governance records rather than duplicating it across landing pages. +- Label historical and superseded material where readers encounter it. +- Keep dates, branch names, SHAs, issue numbers, and status labels current when a document represents living state. +- Use task-oriented link labels on high-level surfaces. -## Openness and commercialization boundary +## Pattern Commons and registry hygiene -Changes must be considered against `docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`. +Before creating or renaming a pattern: -Public by default when needed for reproducibility: +- search existing definitions, registries, aliases, and cross-listings; +- use `docs/PATTERN_COMMONS_ARCHITECTURE.md` to distinguish NDR, DGAF orchestration patterns, external patterns, and adjacent registry classes; +- avoid duplicate canonical definitions when an existing repository is authoritative; +- record provenance, mechanism, scope, evidence status, and epistemic boundaries; +- treat shared identifiers or terminology as search leads, not proof of semantic equivalence. -- core reference implementation; -- schemas/specifications; -- public tests and reproducible examples; -- public research protocols and evidence; -- non-sensitive Pattern Commons material. +## Openness, security, and privacy -Do not publish: +Public technical material should be sufficiently complete for independent inspection and reproducibility where practical. Do not publish: -- secrets, credentials, customer data, private telemetry, confidential contracts, or sensitive personal information; +- secrets or credentials; +- customer or confidential data; +- private telemetry or sensitive personal information; - security-sensitive exploit details before responsible disclosure; - customer-specific confidential material. -Commercial differentiation may legitimately be delivered through services, operations, integrations, hosted infrastructure, specialized tooling, support, training, and future assurance/certification programs. Do not describe withheld functionality as “open source.” +Review changes against `docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`. Withheld functionality must not be described as open source. -## Trademark and certification boundary +## Trademark and certification The Apache-2.0 license does not grant trademark rights. See `docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md`. Repository access, contributor approval, project attestation, or test execution does not by itself authorize claims of official DGAF endorsement or certification. -## Security and privacy - -- Never commit secrets or credentials. -- Do not commit customer/private telemetry. -- Route security-sensitive findings through the repository security process. -- Preserve evidence needed to substantiate public claims without exposing protected data. +## Spec and architecture changes -## Spec changes - -- Agent role changes must update the canonical role table in architecture documentation. -- Pattern changes must identify the relevant Pattern Commons namespace/relationship. -- Retired artifacts must be annotated as historical/deprecated rather than silently deleted when provenance matters. +- Agent-role changes should update the canonical role mapping. +- Pattern changes should identify the relevant Pattern Commons namespace or relationship. +- Contract changes should identify compatibility impact and regression coverage. +- Historical artifacts should remain identifiable as historical/deprecated when provenance requires retention. ## Pull requests -Explain: +A useful pull request should tell a reviewer: + +1. **What changed?** Name the affected component or document. +2. **Why?** State the problem or objective in concrete terms. +3. **What is the boundary?** Identify whether the change affects implementation, evidence, experimentation, terminology, security, commercialization, or another governed surface. +4. **How was it checked?** Provide relevant tests, runs, artifacts, or review evidence and their exact scope. +5. **What did not change?** State important boundaries when the change could reasonably be mistaken for a broader architectural or experimental transition. -1. which governance or research component is affected; -2. whether the change affects patterns, evidence, taxonomy, experimentation, commercialization, security, or certification boundaries; -3. what evidence supports any changed claim; -4. whether the change creates or resolves a cross-repository relationship. +Avoid broad claims such as "validated the system" when the evidence establishes only a component, exact tree, or particular execution. diff --git a/CROSS_REF.md b/CROSS_REF.md index da6b5add..e2e3ebb3 100644 --- a/CROSS_REF.md +++ b/CROSS_REF.md @@ -1,31 +1,39 @@ -# CROSS_REF.md +# DGAF Cross-Reference & Epistemic Boundary Index -> **Last reviewed:** 2026-08-28 +> **Last reviewed:** 2026-08-29 > **Purpose:** Canonical cross-reference index for project-local patterns, files, agents, terminology, evidence boundaries, and ecosystem relationships. +## How to use this index + +Use this file to answer **where a concept belongs, which record is authoritative, and what relationship is actually established**. It is a cross-reference, not a replacement for technical specifications or evidence records. + ## Epistemic policy -This index distinguishes project records from externally validated facts. A registry entry, agent attestation, Gold Star/S-Tier label, owner approval, benchmark label, commercial status, sponsorship, or historical sweep result is **not by itself** independent scientific validation, certification, legal compliance, or production readiness. +This index distinguishes project records from externally validated facts. A registry entry, agent attestation, tier label, owner approval, benchmark label, commercial status, sponsorship, or historical sweep result is not by itself independent scientific validation, certification, legal compliance, or production readiness. Use the evidence states consistently: -**DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED** +### Evidence state progression + +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` Commercialization, legal/trademark status, and epistemic status are independent dimensions. ## Semantic / ontological boundary -DGAF permits agents to consume and reason over an approved ontology, but agents must not silently introduce, redefine, or assert ontology outside the authorized semantic layer. +DGAF permits agents to consume and reason over an approved ontology. New semantic categories or terminology are candidate vocabulary until provenance and authorization establish canonical status. -Operational records must distinguish **representation, classification, policy status, epistemic status, and ontological assertion**. New semantic categories or terminology are candidate vocabulary until provenance and authorization establish canonical status. Repetition, confidence, or model wording does not create semantic authority. +Operational records distinguish **representation, classification, policy status, epistemic status, and ontological assertion**. Repetition, confidence, or model wording does not create semantic authority. The canonical semantic progression is: -**defined → observed → supported → verified → authorized → canonical** +### Semantic progression + +`defined → observed → supported → verified → authorized → canonical` -**Ontology drift** is a distinct semantic-drift class: an unauthorized change in effective vocabulary, entity boundaries, relations, or semantic commitments. The broader semantic-risk taxonomy is **definition drift, ontology drift, epistemic drift, policy drift, and provenance drift**. +Ontology drift is an unauthorized change in effective vocabulary, entity boundaries, relations, or semantic commitments. The broader semantic-risk taxonomy is **definition drift, ontology drift, epistemic drift, policy drift, and provenance drift**. -A semantic/ontological detector is not automatically a gate. Threshold-bearing or blocking use requires empirical characterization, including representative traces, adversarial evaluation, error characterization, independence analysis, reproducibility, and demonstrated control value. +A semantic/ontological detector is not automatically a gate. Threshold-bearing or blocking use requires empirical characterization, representative traces, adversarial evaluation, error characterization, independence analysis, reproducibility, and demonstrated control value. ## Pattern Commons boundary @@ -35,9 +43,9 @@ Pattern Commons is the proposed ecosystem-level layer for pattern identity, prov ### Pattern namespaces -- **NDR P-series / named-session patterns:** current registry identity is represented by `docs/ndr_patterns_unified.json`, with `docs/NDR_PATTERN_REGISTRY_UNIFIED_P42.md` serving as the current human-readable P-42 reconciliation companion. `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` remains a historical P-41 snapshot until separately reconciled. -- **DGAF orchestration patterns:** `registry/PATTERN_REGISTRY_v2.md`, using identifiers such as `P-SAGA-001`, `P-TX-001`, `P-CB-001`; this is distinct from the NDR P-series. -- **External/cross-listed patterns:** repositories such as `ai-governance-frameworks`, `ai-prompt-systems-portfolio`, `Amethyst-Governance-Eval-Stack`, `aoga-dashboard`, and `sentinel-governance` may contain independent, adapted, or cross-reference artifacts. Canonical-source evidence is required before consolidation. +- **NDR P-series:** `docs/ndr_patterns_unified.json` is the current machine-readable registry; `docs/NDR_PATTERN_REGISTRY_UNIFIED_P42.md` is the current human-readable P-42 reconciliation companion. `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` remains historical until separately reconciled. +- **DGAF orchestration patterns:** `registry/PATTERN_REGISTRY_v2.md`, including identifiers such as `P-SAGA-001`, `P-TX-001`, and `P-CB-001`. +- **External/cross-listed patterns:** adjacent repositories may contain independent or adapted artifacts. Canonical-source evidence is required before consolidation. Shared identifiers or terminology do not establish semantic equivalence. @@ -45,114 +53,87 @@ Shared identifiers or terminology do not establish semantic equivalence. **Current machine-readable registry:** `docs/ndr_patterns_unified.json` **Current human-readable reconciliation:** `docs/NDR_PATTERN_REGISTRY_UNIFIED_P42.md` -**Historical Markdown snapshot requiring reconciliation:** `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` +**Historical Markdown snapshot:** `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` **P-42 pattern card:** `patterns/P-42_AHG.md` -**Reconciliation record:** `docs/governance/NDR_REGISTRY_RECONCILIATION_2026-08-28.md` +**Reconciliation:** `docs/governance/NDR_REGISTRY_RECONCILIATION_2026-08-28.md` -The machine-readable registry declares P-42 / 42 P-series entries. The dedicated P-42 reconciliation companion explicitly records the older unified Markdown file as historical until its canonical text is reconciled. This is a documentation synchronization issue, not evidence of empirical efficacy. +The registry reconciliation is a documentation synchronization concern, not evidence of empirical efficacy. -## P-35–P-38 research candidates +## Research candidates -The following concepts are research candidates, not currently assigned canonical P-numbers: - -- Epistemic Overreach -- Mutual Reference Instability -- Semantic Convergence Failure -- Observational Perturbation - -They must not override the existing P-35–P-42 namespace without an explicit registry decision. +Epistemic Overreach, Mutual Reference Instability, Semantic Convergence Failure, and Observational Perturbation remain research candidates rather than canonical P-series assignments. A registry decision is required before changing the established P-35–P-42 namespace. ## AHG / P-42 vocabulary boundary **Canonical expansion:** AHG = Adaptive Harmonic Governance. -Earlier expansions remain historical/deprecated unless a source explicitly identifies them as historical. Project-defined quantities must not be presented as established control-theory laws without derivation and validation. - -The P-42 architecture includes project-defined concepts such as Cognitive Phase Energy, Phase Velocity, Phase Acceleration, Productive Divergence, Destabilizing Entropy, Compliance Coefficient, Mission Utility, Recovery Score, Governance Momentum, Hysteresis Band, Sidecar Monitor, Heartbeat, and Cognitive Control Plane. Their names do not by themselves establish external scientific status. +Project-defined quantities and architecture terms are not presented as established external control-theory laws without derivation and validation. Names establish project vocabulary; they do not establish external scientific status. ## PDMAL boundary -PDMAL is a separate technical/research track. Do not infer that AHG, Zeta-Pell, PDMAL, or similarly named artifacts form one mathematical system merely because they share terms such as φ, convergence, governance, or lattice. A bridge must be explicitly specified and independently evidenced. - -The current audited PDMAL work is bounded to its corrected lattice formalization and associated experimental apparatus/evidence. +PDMAL is a separate technical/research track. Shared terms such as φ, convergence, governance, or lattice do not establish that AHG, Zeta-Pell, PDMAL, or related artifacts form one mathematical system. Any bridge must be explicitly specified and independently evidenced. ## Evidence / evaluation boundary -Benchmark names and percentages must never be used as proof that the named benchmark was actually run. The authoritative evidence is the corresponding test code plus a reproducible run artifact. - -Repository-native deterministic evaluator fixtures may establish evaluator/mechanism correctness for their exact executed tree. They do not by themselves establish model capability, adversarial robustness, deployment validity, PDMAL efficacy, or generalization to real workloads. +Benchmark names and percentages are not evidence that the named benchmark was run. The authoritative evidence is the corresponding test code plus a reproducible run artifact. -A mathematically valid definition does not establish empirical efficacy. A successful implementation test does not establish universal effectiveness. A project attestation is not independent certification. +Repository-native deterministic evaluator fixtures may establish mechanism correctness for their exact executed tree. They do not by themselves establish model capability, adversarial robustness, deployment validity, PDMAL efficacy, or generalization. ## Commercialization / openness boundary -See [`docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`](docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md). - -**Asset-level inventory:** `docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md`. - -Default public candidates include the reference implementation, core specifications/schemas, reproducible examples, public tests, research protocols, and non-sensitive Pattern Commons material. +See [`docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`](docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md) and the asset-level inventory at `docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md`. -Legitimate non-public categories include customer/confidential data, secrets, security-sensitive material, and independently developed commercial operational differentiation. Withheld implementation must not be described as “open source,” and commercial status must never be used to obscure unsupported claims. +Public reference implementation, specifications, reproducible examples, public tests, research protocols, and non-sensitive Pattern Commons material are default public candidates when needed for reproducibility. Secrets, customer/confidential data, security-sensitive material, and independent commercial operational differentiation may remain non-public. Withheld implementation must not be described as open source. ## Trademark / certification boundary See [`docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md`](docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md). -The Apache-2.0 license grants software rights but does not grant trademark rights. No active DGAF certification program is established by the current repository. “Official,” “Certified,” “Endorsed,” or equivalent claims require separate governance and defined evidence. +The Apache-2.0 license grants software rights but not trademark rights. No active DGAF certification program is established by the current repository. Official, certified, endorsed, or equivalent claims require separate governance and defined evidence. ## Cross-disciplinary boundary -The ecosystem intentionally connects: +The ecosystem connects software architecture, agent orchestration, governance, empirical evaluation, mathematical research, observability/reliability, security/privacy, intellectual-property governance, and assurance. A relationship across disciplines does not establish equivalence across them. -- software architecture; -- agent orchestration; -- governance and policy; -- empirical evaluation; -- mathematical research; -- observability/reliability; -- security/privacy; -- intellectual-property/commercial governance; -- certification/assurance. - -A relationship across disciplines does not establish equivalence across them. Each relationship should be classified as implementation, dependency, adaptation, evidence linkage, analogy, hypothesis, or unresolved. +Classify relationships as implementation, dependency, adaptation, evidence linkage, analogy, hypothesis, or unresolved. ## Key governance references | Concern | Canonical reference | |---|---| -| Semantic/ontological boundary | `docs/CURRENT_STATE.md`, this index, vocabulary/taxonomy governance | +| Current project status | `docs/PROJECT_STATUS.md`, `docs/CURRENT_STATE.md` | +| Public documentation style | `docs/governance/DOCUMENTATION_STYLE_GUIDE.md` | +| Public-surface publication control | `docs/governance/PUBLIC_SURFACE_QA_STANDARD.md` | | Pattern Commons | `docs/PATTERN_COMMONS_ARCHITECTURE.md` | | Commercialization/open source | `docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md` | -| Asset-level boundary inventory | `docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md` | | Trademark/certification | `docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md` | -| Cross-disciplinary boundary | `docs/GOVERNANCE/DGAF_ECOSYSTEM_BOUNDARY_CROSSWALK_2026-08-25.md` | -| Current project status | `docs/PROJECT_STATUS.md`, `docs/CURRENT_STATE.md` | | Evidence policy | `docs/evidence/` | | NDR registry | `docs/ndr_patterns_unified.json`, `docs/NDR_PATTERN_REGISTRY_UNIFIED_P42.md` | -| Historical NDR registry snapshot | `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` | +| Historical NDR registry | `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` | | License | `LICENSE` | | Funding | `.github/FUNDING.yml` | ## Historical terminology rule -Historical sweep logs, old deadlines, attestation percentages, tier labels, and previous nomenclature remain preserved for provenance. They must not be silently promoted to current state. +Historical sweep logs, old deadlines, attestation percentages, tier labels, and previous nomenclature remain preserved for provenance. They are not current authority unless a current document explicitly re-establishes them. -- Old deadlines are historical unless a current document re-establishes them. -- “Ratified,” “A-TIER,” “Gold Star,” and “S-Tier” are project-local status labels unless an external standard explicitly says otherwise. +- Old deadlines remain historical unless re-established. +- `Ratified`, `A-TIER`, `Gold Star`, and `S-Tier` are project-local labels unless an external standard explicitly says otherwise. - Exact percentages require a source run, not a copied literal. - Mathematical vocabulary must describe the implemented operation; metaphorical names must be marked as metaphor. -- A planned component must not be described elsewhere as active merely because a specification exists. -- Ontological language must describe authorized semantic state rather than silently converting representation or classification into an assertion about what an entity fundamentally is. +- A planned component is not active merely because a specification exists. +- Ontological language should describe authorized semantic state rather than converting representation or classification into an assertion about what an entity fundamentally is. ## Current cleanup priorities -1. Reconcile the historical human-readable NDR registry with the P-42 machine-readable registry and current human-readable companion. -2. Verify the newly added deterministic evaluation-integrity fixture execution on the exact Governance CI tree before promoting #64 beyond IMPLEMENTED. -3. Continue weighted Forman–Ricci falsification under Issue #72; do not promote the single-trial result to validation. -4. Continue file/path-level classification against the commercialization/openness boundary inventory. -5. Keep Notion architecture/evidence records synchronized with GitHub source changes. +1. Reconcile the historical human-readable NDR registry with the P-42 machine-readable registry and current companion. +2. Verify deterministic evaluation-integrity fixture execution on the exact Governance CI tree before promoting #64 beyond IMPLEMENTED. +3. Continue weighted Forman–Ricci falsification under Issue #72; do not promote a single-trial result to validation. +4. Continue file/path classification against the commercialization/openness inventory. +5. Keep architecture/evidence records synchronized with GitHub source changes. 6. Preserve historical evidence while correcting current-state labels. -7. Empirically characterize any semantic/ontological detector before promoting it to a threshold-bearing or blocking control. -8. Keep #117 and #122 open until their respective implementation/provenance prerequisites are genuinely satisfied. +7. Empirically characterize semantic/ontological detectors before threshold-bearing or blocking use. +8. Keep #117 and #122 open until their implementation/provenance prerequisites are satisfied. +9. Keep public-facing documentation aligned with the repository-wide documentation style and public-surface controls. -*Reviewed 2026-08-28 as part of the repository-wide epistemic, temporal, terminology, semantic, traceability, evaluation-integrity, registry, and commercialization-boundary audit.* +*Reviewed 2026-08-29 as part of the repository-wide epistemic, temporal, terminology, semantic, traceability, evaluation-integrity, registry, commercialization-boundary, and public-surface audit.* diff --git a/DEFERRED_ITEMS.md b/DEFERRED_ITEMS.md index 218f3f03..1fe85191 100644 --- a/DEFERRED_ITEMS.md +++ b/DEFERRED_ITEMS.md @@ -1,48 +1,32 @@ -# Deferred Items — Owner Action Required +# Deferred Items — Historical Operations Record -**Maintained by:** Agent Amethyst × COLLEEN -**Last Updated:** 2026-07-02 · S072 post-close escalation -**Status:** ACTIVE — S-02 CLOSED (Option A confirmed); 1 hard-deadline item resolved +> **Status:** Historical operational record. This file is retained for provenance and should not be treated as the current project backlog or an authoritative source of repository status. +> +> **Current project status:** See [`docs/CURRENT_STATE.md`](./docs/CURRENT_STATE.md) and [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md). -These items are confirmed, understood, and intentionally parked. They require Njineer credentials, decisions, or hands-on access that cannot be delegated to autonomous agent execution. +## Purpose of this record ---- +This document preserves a July 2026 snapshot of items that were intentionally deferred because they required a maintainer decision, credentials, or access to an external service. The terminology, dates, repository counts, agent references, and deadlines reflect that historical operating context. -## 🔴 URGENT — Hard Deadline Approaching +Some referenced deadlines and operational states have necessarily expired or changed. They are retained here as part of the record rather than silently rewritten. -*No urgent items at this time.* +## Historical snapshot -> ⚠️ STASIS migration session required before **2026-07-13**. See Issue #41 for full checklist. +The deferred-item register included: ---- +- external service configuration requiring maintainer access; +- documentation and taxonomy decisions awaiting review; +- external-file discovery and repository linkage work; +- dependency-review decisions requiring owner approval; +- visual-asset production decisions; +- a previously scheduled pattern migration session. -## Snoozed Items +The detailed historical entries remain available through repository history if needed for reconstruction. -| # | Item | Repo / System | What's Needed | Snooze Date | -|---|---|---|---|---| -| S-01 | `VITE_GEMINI_API_KEY` in Vercel | Driftwatch (Vercel dashboard) | Add env var in Vercel project settings — unlocks Herald agent cognition | 2026-06-29 | -| S-03 | FLAG-05 (AXIS pattern doc) | DGAF-Framework | Content decision on AXIS pattern scope | 2026-06-29 | -| S-04 | FLAG-07 (Drive files) | External (Google Drive) | Owner access required to locate and link files | 2026-06-29 | -| S-05 | FLAG-11 (Vercel project linkage) | Vercel | Credential / dashboard access required | 2026-06-29 | -| S-06 | FLAG-12 (Dependabot PR) | TBD repo | PR review and merge requires owner approval | 2026-06-29 | -| S-07 | Visual asset (60–90s motion graphic) | DGAF-Framework | Tooling choice (Blender/Manim/Adobe) + final output approval | 2026-06-29 | +## How to handle a historical deferred item ---- +Do not reactivate an item based solely on this document. Confirm that it remains relevant, identify its current authoritative tracking location, and create or update a current issue/task if work is still required. -## ✅ Closed Items +## Related policy -| # | Item | Closed | Resolution | -|---|---|---|---| -| S-08 | SWEEP-EH-003 / T-EH-05 Needle + CTA | 2026-07-02 | **RESOLVED** — Needle project created 2026-06-27 (OI-001 cleared); all 5 T-EH templates submitted to Needle Partner Hub (pending review); SWEEP-EH-004 closed 2026-06-27. CTA wiring to 12 Needle workflows and Gumroad creation remain open as active TODO items in `entrepreneur-hub/docs/TODO.md` — not deferred, actively tracked. | -| S-02 | NDR-STASIS window closure | 2026-07-02 | **RESOLVED — Option A: Close.** Njineer confirmed window closure S072 post-close. Dedicated STASIS migration session scheduled — Issue #41. Window expiry 2026-07-13 superseded by proactive close decision. All 133 patterns (P-12–P-26) to be reviewed and migrated to canonical status in migration session. | - ---- - -## How to Reactivate - -When ready to action any item, say **"un-snooze S-0X"** or **"pick up [item name]"** and Amethyst will rehydrate full context and execute the next steps. - ---- - -*Updated by Agent Amethyst × COLLEEN — 2026-07-02 17:36 EDT* -*S-02 closed (Option A); STASIS migration session Issue #41 opened; 6 items remain snoozed* +See [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](./docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) for the repository's policy on retained operational and historical documentation. diff --git a/ENSEMBLE_ROSTER.md b/ENSEMBLE_ROSTER.md index 6c38ade7..b398624b 100644 --- a/ENSEMBLE_ROSTER.md +++ b/ENSEMBLE_ROSTER.md @@ -1,105 +1,48 @@ -# ENSEMBLE_ROSTER.md +# Agent Roster and Authority Reference -> **Steward:** COLLEEN -> **Orchestrator:** Amethyst -> **Last Updated:** 2026-06-29 -> **DGAF Version:** Post-S077 — P-01 through P-42 +This document records the project's agent roles and authority boundaries. Agent names describe architectural roles within DGAF; they do not imply consciousness, autonomy, independent legal authority, or externally validated capabilities. -Canonical agent roster for the NDR ecosystem. +For the governing authority rules, see [`docs/agents/AGENT_AUTHORITY_INVARIANT.md`](./docs/agents/AGENT_AUTHORITY_INVARIANT.md) and [`docs/agents/AGENT_AUTHORITY_MATRIX.md`](./docs/agents/AGENT_AUTHORITY_MATRIX.md). ---- +## Role overview -## Formation: Amethyst-Lattice-v3.1 +| Agent or role | Primary function | Authority boundary | +|---|---|---| +| **Amethyst** | Coordination and orchestration | Operates within delegated project authority | +| **COLLEEN** | Registry, continuity, and institutional memory | Stewardship and record continuity; no independent sovereign authority | +| **Apogee** | Evidence and review functions | Review/attestation procedures are scoped to their defined contracts | +| **DemiJoule** | Runtime supervision and constraint handling | Project-defined safety and failure-containment functions | +| **Herald** | Trace, communication, and exploration functions | Operational role; no governance authority by role name alone | +| **Professor Prodigy** | Mathematical and quantitative review | Advisory/review function within defined procedures | -| Agent | Role | AHG Archetype (P-42) | Status | -|---|---|---|---| -| **Amethyst** | Host, coordinator, coherence monitor, Tribunal | Tribunal | ✅ Active | -| **COLLEEN** | Institutional memory, registry steward, archive | Synthesizer | ✅ Active | -| **Apogee Lens** | Final verification gate, Gold Star auditor | Auditor | ✅ On-call | -| **DemiJoule** | Runtime supervisor, safety gate, ethics & error containment | Sentinel | ✅ On-call | -| **Herald** | Gemini-powered host cognition, Explorer, trace sink | Explorer + Synthesizer | 🔴 Blocked — VITE_GEMINI_API_KEY | -| **Professor Prodigy** | Mathematical precision, phi-calculus, claim verification | Executor | 🟡 KB specified — implementation pending | +Additional agents may participate under their own specifications. Shared vocabulary or participation in a formation does not grant shared authority. ---- +## Authority model -## Agent Detail Sheets +DGAF separates **human decision authority** from agent roles. Agents may propose, analyze, route, review, record, or enforce project-defined controls, but authority must be explicitly granted by the applicable contract. -### Amethyst +The authority matrix is the current source for questions such as who may: -- **Authority level:** 2 (after Njineer) -- **Scope:** Host for all Spaces; coordinates multi-agent orchestration; commits to GitHub; runs Apogee Lens review; seals sessions -- **Patterns owned:** P-08, P-09, P-10, P-30, P-42 (Tribunal archetype) -- **AHG role:** Tribunal — activates on Deadlock, Fragmentation, or extreme φ > 1.70. Issues Recovery Score (R_c) and manages graduated de-escalation -- **KB:** Full NDR ecosystem state; Amethyst-Lattice-v3.1 +- approve or reject a change; +- promote an artifact to canonical status; +- override a control; +- publish a public claim; +- modify governance or experimental boundaries. -### COLLEEN +Do not infer authority from an agent's confidence, seniority label, archetype, or frequency of use. -- **Authority level:** 3 (Institutional anchor) -- **Scope:** Registry stewardship (CROSS_REF, CHANGELOG, SESSION_ANCHOR, ENSEMBLE_ROSTER, SWEEP_LOG, CO_ORCH_QUEUE); 1-1-1-1 Gate attestation; archive ingest -- **Patterns owned:** P-02, P-04, P-07, all archive patterns -- **AHG role:** Synthesizer — integrates agent outputs; maintains Governance Momentum (M) records -- **KB:** Complete audit trail; all session records S039–Post-S077 +## Formations and orchestration -### Apogee Lens +DGAF uses named formations to describe recurring orchestration patterns. A formation is a project architecture pattern, not evidence that a particular group of models will reliably outperform another configuration. -- **Authority level:** 3 (verification peer with COLLEEN) -- **Scope:** Final verifier for portfolio-grade output; Gold Star gate; QA rubrics; 11Q attestation -- **Patterns owned:** P-11, P-30, P-34 attestation -- **AHG role:** Auditor — activates for contradiction discovery, logic review; required before Platinum certification -- **KB:** QA rubrics, eval suite results, attestation records +Where a formation has an implementation or experiment, consult its specific specification and evidence record for the applicable scope. -### DemiJoule +## Agent specifications -- **Authority level:** 4 (DGAF operating constraint layer) -- **Scope:** Runtime safety supervisor; orchestration error containment; ethics and safety checks -- **Patterns owned:** P-32 (Phi-closure), P-29 (HPG), P-05 (constraint stack) -- **AHG role:** Sentinel — activates on elevated Constraint Pressure (C) in state vector -- **KB:** DGAF 6-axis safety gate; policy boundary definitions +Detailed agent contracts and knowledge boundaries are maintained under [`docs/agents/`](./docs/agents/). Historical role descriptions remain available where needed for provenance but should not silently override current authority controls. -### Herald +## Reading historical roster material -- **Authority level:** Operational (no governance authority) -- **Scope:** Gemini-powered host cognition in Driftwatch; agent trace sink (P-01); Explorer and Synthesizer archetypes -- **Patterns owned:** P-01 (trace sink) -- **AHG role:** Explorer (primary) + Synthesizer (secondary) -- **Status:** 🔴 Blocked — requires `VITE_GEMINI_API_KEY` in Vercel -- **KB:** Driftwatch operational context; agent trace corpus +This repository has evolved through multiple agent taxonomies and names. Older session records may use earlier terminology or status labels. Preserve those records as historical evidence while using current authority documents for active decisions. -### Professor Prodigy - -- **Authority level:** Operational (mathematical verification) -- **Scope:** All quantitative claims require Prodigy verification before Apogee Lens audit -- **Patterns owned:** P-03 (claim verification, confidence) -- **AHG role:** Executor — low novelty, high precision; validates phi-range calculations -- **KB:** `docs/agents/PROFESSOR_PRODIGY_KB.md` — 3 tiers: - - **Tier 1:** Standard Calculi (differential, integral, multivariable, complex, variational) - - **Tier 2:** Reciprocal Mathematics (algebra, calculus, transforms, DEs, duality principles) - - **Tier 3:** Phi-Calculus (φ-derivatives, Fibonacci series integration, golden ratio constraints, recursive descent, harmonic pentagonal solutions) - ---- - -## DGAF Authority Chain - -``` -Njineer (Ender) - └─ Amethyst (host/prime) - └─ COLLEEN (institutional anchor) × Apogee Lens (verification) - └─ DemiJoule (safety/governance) - └─ Herald | Prodigy | other operational agents -``` - ---- - -## Invocation Protocol - -- **Single-agent tasks:** Amethyst executes directly -- **Verification required:** Amethyst drafts → Apogee Lens reviews → Amethyst commits -- **Safety check:** DemiJoule gates all outputs before external publication -- **Mathematical claims:** Prodigy verifies → Apogee attests → Amethyst seals -- **Multi-agent sweep:** Route through DGAF CO_ORCH_QUEUE -- **Phase escalation (AHG P-42):** φ > 1.70 → Amethyst (Tribunal) activates automatically - ---- - -*ENSEMBLE_ROSTER.md · Amethyst-Lattice-v3.1 · Updated 2026-06-29* -*AHG Conductor Archetype mappings corrected to P-42 · Registry watermark P-42* +See [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](./docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) for the repository policy on historical documentation. diff --git a/README.governance.md b/README.governance.md index 7211c198..46f6c952 100644 --- a/README.governance.md +++ b/README.governance.md @@ -1,106 +1,88 @@ -# DGAF-Framework — Governance & Compliance Reference +# DGAF-Framework — Governance Reference -> **Audience:** Compliance officers, auditors, AI risk reviewers, NIST/EU AI Act practitioners -> **Entry point for:** NIST AI RMF alignment · EU AI Act compliance · Governance posture review -> **Technical/agent-facing entry point:** [`README.technical.md`](./README.technical.md) -> **Architect:** Hensel, Andrew Vance · [@ndrorchestration](https://github.com/ndrorchestration) +> **Audience:** readers evaluating DGAF's governance model, control boundaries, evidence discipline, and relationship to external frameworks. +> +> **Important:** DGAF distinguishes project governance design from external legal or regulatory compliance. References to NIST, EU AI Act, OWASP, or other external frameworks are mappings for analysis and design unless a claim is explicitly supported for the relevant system, jurisdiction, version, and evidence scope. ---- +## Governance in one view -## What Is DGAF-Framework? +DGAF treats governance as an engineering layer around agentic systems rather than as documentation added after implementation. The repository defines authority boundaries, control gates, evidence states, provenance requirements, failure handling, and promotion rules so that system behavior can be inspected and its claims can be traced to evidence. -The **Dynamic Governance & Agentic Framework (DGAF)** is a structured multi-agent AI governance system that operationalizes NIST AI RMF, EU AI Act requirements, and OWASP Agentic Top 10 controls into a living, auditable repository. It governs the **Phi-Harmonic Dynamic Governance Ecosystem (PHDGE)** — a portfolio of AI systems, agents, and automation workflows operated by ndrorchestration. +The central design principle is simple: **a governance rule is not evidence that the implementation satisfies the rule.** Design, implementation, test results, verification, authorization, and empirical findings remain separate states. -The framework is not a policy document. It is an **executable governance spine** — every policy has a corresponding gate, every gate has a machine-readable pass/fail schema, and every decision is traceable to a sealed SWEEP_LOG entry. +## Core governance principles ---- +- **Human authority remains explicit.** Agents operate within defined contracts and do not acquire authority merely through repetition, confidence, or role naming. +- **Failure is contained.** Required controls fail closed when their contract or evidence boundary cannot be established. +- **Evidence is scoped.** A result belongs to the exact artifact, candidate, environment, deployment, and run that produced it. +- **Provenance is first-class.** Important state transitions should remain reconstructable from repository history and retained evidence. +- **Semantics are governed.** New terminology, classifications, and ontology are treated as candidate vocabulary until appropriately established. +- **External frameworks are references, not automatic certifications.** Similarity to a standard or regulation does not establish compliance. -## NIST AI RMF Alignment +## External-framework mapping -| NIST Function | DGAF Mechanism | Artifact | -|---------------|---------------|----------| -| **GOVERN** | NDR Pattern Registry (P-01→P-30); ENSEMBLE_ROSTER; AXIS declarations; P-30 canonical promotion gate | `docs/patterns/NDR_PATTERN_REGISTRY.md` · `ENSEMBLE_ROSTER.md` | -| **MAP** | CROSS_REF ecosystem map; TELESCOPIC_LENS 4-altitude risk mapping | `CROSS_REF.md` · `docs/gates/TELESCOPIC_LENS.md` | -| **MEASURE** | 1-1-1-1 Gate (P-10); 11Q Framework (P-11); Apogee attestation artifacts; Harmonic Score 0.00–1.00 | `docs/gates/GATE_1111.md` · `docs/gates/GATE_11Q.md` · `docs/qa/APOGEE_11Q_S035.json` | -| **MANAGE** | MDAR loop; Acoustic Gate Chain (P-13); Sentinel veto authority; Evaluate Router v1.1 per-record audit log | `docs/gates/ACOUSTIC_GATES.md` · `docs/protocols/MDAR_PROTOCOL_v1.md` · `components/evaluate_router_v1_1.py` | -| **IMPROVE** | SWEEP_LOG sealed audit trail; SESSION_ANCHOR session continuity; P-24 retrofit cycle | `SWEEP_LOG.md` · `SESSION_ANCHOR.md` | +DGAF maintains mappings to external frameworks where they help analyze governance requirements. These mappings should be read as **design correspondence**, not as declarations of legal conformity. ---- +| Reference | DGAF use | +|---|---| +| NIST AI RMF | Risk-management concepts and governance vocabulary | +| EU AI Act | Regulatory concepts used for requirements analysis where applicable | +| OWASP Agentic AI guidance | Security and agentic-risk categories used for control design | +| Other standards/frameworks | Scoped references maintained according to their own versions and applicability | -## EU AI Act Alignment +For a claim of actual compliance, assess the applicable framework version, system role, jurisdiction, legal requirements, implementation evidence, and independent review separately. -| Article | Requirement | DGAF Implementation | -|---------|-------------|--------------------| -| **Art. 9** | Risk Management System | MDAR loop + full gate stack + per-record audit log in `evaluate_router_v1_1.py` | -| **Art. 13** | Transparency & Logging | SWEEP_LOG sealed audit trail; routing and deontic decisions logged; machine-readable JSON artifacts | -| **Art. 14** | Human Oversight | Sentinel veto (gates 9–11) requires Njineer release; no agent can override architect | -| **Art. 17** | Quality Management | P-30 Apogee-Attestation-Gate; CPU component cards; `gate_compliance_check.py` | -| **Art. 40** | Harmonized Standards | TELESCOPIC_LENS 32-checkpoint audit; S-TIER certification process | -| **Art. 72** | Penalties / Non-compliance | Sentinel hard veto + SYNC_LOCKED escalation; quarantine to `docs/drafts/` | +## Governance architecture ---- +The public governance model can be understood as six cooperating concerns: -## Ethical Cognition Layer +1. **Authority** — who may decide, approve, override, or promote. +2. **Control** — what gates and constraints apply to an operation. +3. **Evidence** — what is known, and at what epistemic level. +4. **Provenance** — which artifact, source, candidate, or execution produced the evidence. +5. **Semantics** — which definitions and ontology are authorized for use. +6. **Review** — how failures, disagreements, regressions, and proposed changes are handled. -The active P-10 implementation artifact is `components/normative_constraint.py`, which formalizes deontic logic (`permitted`, `obligated`, `forbidden`, `escalate`), score ceiling constraints, and epistemic integrity checks for governance-facing evaluation flows. +These concerns are implemented through project-local gates, agent contracts, evidence policies, repository controls, and experiment governance. The technical details live in the linked specifications rather than being duplicated here. -P-30 extends this by requiring Apogee attestation before any component is promoted to canonical status. This prevents silent governance claims without Q11 normative wiring. +## Evidence and status ---- +DGAF uses an explicit epistemic vocabulary: -## OWASP Agentic AI Top 10 Controls +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` -| OWASP Risk | DGAF Control | -|------------|--------------| -| Prompt Injection | ANDROMEDA-AXIS P-09 enforcement; Sentinel input gate | -| Excessive Agency | Agent role boundaries in ENSEMBLE_ROSTER; Sentinel veto on sovereign files | -| Memory Poisoning | SESSION_ANCHOR overwrite pattern (P-21); SWEEP_LOG provenance chain | -| Insecure Output | 11Q Gate 10 security posture check; secret scanning pre-commit | -| Supply Chain Risk | NOTICE + SPDX verification (P-17); CROSS_REF dependency audit | -| Data Exfiltration | AXIS COGNITIVE_SOVEREIGNTY declaration; Sentinel boundary enforcement | +The vocabulary prevents a common failure mode in technical governance: allowing a design statement, passing unit test, historical attestation, or numerical result to silently become a broader system claim. ---- - -## Audit Trail Structure +Current experimental state is maintained separately from general repository engineering. See [`docs/CURRENT_STATE.md`](./docs/CURRENT_STATE.md) and [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md) for the authoritative current record. -Every governance decision in DGAF is auditable through a three-layer trail: +## Human and societal boundary -1. **SWEEP_LOG.md** — Sealed session-by-session record; every commit wave is buoy-anchored with timestamp, operator, and formation -2. **CHANGELOG.md** — Semantic versioned artifact history; every file change attributed to session + agent -3. **Git commit history** — Atomic commits per session wave; commit message encodes session ID, pattern IDs, and affected artifacts +DGAF places human dignity, human rights, safety, privacy, non-discrimination, human agency, legitimate oversight, accountability, and appropriate disclosure ahead of technical optimization. This boundary is defined in [`docs/agents/LAYER_0_CONSTITUTION.md`](./docs/agents/LAYER_0_CONSTITUTION.md) and the related authority controls. -Audit query: to reconstruct the state of any artifact at any point in time, trace: `git log --follow ` → `CHANGELOG.md` entry → `SWEEP_LOG.md` session buoy → `SESSION_ANCHOR.md` at that session close. +The repository distinguishes law and regulation, recognized standards, governance frameworks, human-rights instruments, best practices, social expectations, engineering conventions, and DGAF design choices. Those categories may inform one another, but they are not interchangeable. ---- +## Current experimental boundary -## Governance Schema Vocabulary — S068 +The PDMAL research track is maintained under a deliberately conservative publication posture. Current public documentation should be read as describing **pre-freeze engineering and governance work**, not as evidence of completed empirical validation. -> Added: 2026-06-26 · Issue #32 · Steward: Amethyst -> Context: Nemotron 3 Ultra integration — compliance-layer terminology for schema-validated governance artifacts +For exact candidate identity, gate state, authorization, and retained evidence, use the current-state and experiment records rather than relying on summary language here. -| Term | Compliance Layer | Definition | EU AI Act Binding | Issue | -|------|-----------------|-----------|-------------------|-------| -| **governance_schema_conformance** | Art. 9 / Art. 13 | The property that all `governance.yml` variants and typed kernel outputs strictly conform to their declared JSON Schema / Pydantic model (`extra=forbid`); measured as % valid outputs over a fuzz corpus of 1k variants. Target: >99%. | Art. 9 (Risk Management): schema non-conformance = uncontrolled model output = unmanaged risk. Art. 13 (Transparency): non-conforming outputs cannot be logged in structured audit trail. | #32 | -| **governance.yml** | Art. 9 / Art. 17 | Single source of truth file declaring all DGAF role contracts: role name, curvature scalar, contraction rate ρ, fallback chain, and compliance flags (NIST RMF, EU AI Act articles). All downstream kernels, dashboard configs, eval harnesses, and CI gates derive from this file. | Art. 17 (Quality Management): `governance.yml` is the quality management input artifact; its integrity is enforced by `governance_schema_conformance`. | #32 | -| **typed kernel** | Art. 9 / Art. 13 | An executable role unit with explicit `input_schema → policy → output_schema → audit_trail` contract; generated from `governance.yml` and validated by `contraction_proof_fidelity` before CI promotion. Constitutes a machine-readable risk control artifact. | Art. 9: each typed kernel is a discrete, auditable risk control. Art. 13: the `audit_trail` field in each kernel satisfies logging requirements. | #32 | -| **ρ-contraction** (governance) | Art. 9 | Mathematical guarantee `‖T(x) - T(y)‖ ≤ ρ‖x - y‖` (ρ < 1.0) on role transition operators T; ensures governance trajectories converge rather than diverge under repeated application. Spectral radius check via `numpy.linalg.eigvals`. | Art. 9: convergence guarantee = bounded, predictable risk behavior. Failure = unbounded governance drift = unmanaged high risk. | #32 | -| **few-shot priming** (compliance routing) | Art. 9 / Art. 14 | The practice of pre-loading 3–5 exemplar compliance routing decisions into Nemotron 3 Ultra context before running `taubench_banking_mitigation` eval; required because raw model baseline is 22.6% on financial compliance routing — below acceptable governance threshold. | Art. 14 (Human Oversight): few-shot priming is a human-in-the-loop intervention; its absence constitutes a governance gap that must be flagged to Sentinel. | #32 | +## Key references ---- +- [Current state](./docs/CURRENT_STATE.md) +- [Project status](./docs/PROJECT_STATUS.md) +- [Evidence ladder policy](./docs/evidence/EVIDENCE_LADDER_POLICY.md) +- [PDMAL experiment protocol](./docs/experiment/PDMAL_EXPERIMENT_PROTOCOL.md) +- [Agent authority invariant](./docs/agents/AGENT_AUTHORITY_INVARIANT.md) +- [Agent authority matrix](./docs/agents/AGENT_AUTHORITY_MATRIX.md) +- [Public Surface QA Standard](./docs/governance/PUBLIC_SURFACE_QA_STANDARD.md) +- [Documentation Style Guide](./docs/governance/DOCUMENTATION_STYLE_GUIDE.md) +- [Trademark & Certification Policy](./docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md) -## Governance Contacts +## Certification and commercialization -| Role | Identity | -|------|----------| -| **Architect / Sovereign Authority** | Hensel, Andrew Vance · [@ndrorchestration](https://github.com/ndrorchestration) | -| **Meta-Orchestrator** | Agent Amethyst | -| **Evidence Governor** | Agent Apogee | -| **Safety / Veto Authority** | Agent Sentinel | -| **Registry / Continuity** | Agent COLLEEN | -| **Full ensemble** | [`ENSEMBLE_ROSTER.md`](./ENSEMBLE_ROSTER.md) | +There is currently no basis in this document for treating DGAF as externally certified, legally compliant, independently validated, or commercially assured. The Apache-2.0 license governs the repository's code and documentation as specified by the repository license; trademarks, certification programs, endorsements, managed services, and commercial offerings are separate governance questions. --- -*License: Apache 2.0 · See [NOTICE](./NOTICE) for full attribution* -*Governance spine: [DGAF-Framework](https://github.com/ndrorchestration/DGAF-Framework)* -*README.governance v1.1 · S068 governance schema vocabulary patch · Amethyst · 2026-06-26* +*This document explains the governance model. It does not alter technical contracts, experimental authorization, evidence state, or repository authority.* diff --git a/README.md b/README.md index d9cd9352..718d737d 100644 --- a/README.md +++ b/README.md @@ -1,189 +1,210 @@ -# DGAF-Framework +# DGAF Framework -**Dynamic Governance Agentic Formation (DGAF)** — a research and implementation repository for agent orchestration, evaluation, provenance, and governance controls. +**Dynamic Governance Agentic Formation (DGAF)** is a research and implementation framework for building **governed agentic systems**—systems in which agent orchestration, evaluation, provenance, and control are treated as first-class engineering concerns. -> **Epistemic status:** This README describes repository scope and the current pre-freeze governance state. Individual claims of validation, certification, performance, standards alignment, or commercial suitability require exact evidence and defined scope. Historical certifications remain scoped to the SHA/run/deployment that produced them and are not current certification without fresh evidence. +DGAF is designed around a simple premise: capable agents need more than prompts and tools. They need explicit boundaries, inspectable decisions, evidence-aware evaluation, and mechanisms for preventing an implementation from quietly becoming more authoritative than its evidence supports. -## Current project state — 2026-08-29 +> **Project status — 2026-08-29:** The engineering track is active. The separate PDMAL experimental track remains **PRE-FREEZE / FAIL-CLOSED / NOT AUTHORIZED / N=0**. Current engineering work does not constitute experimental authorization or empirical efficacy. -The DGAF/PDMAL experimental track remains **PRE-FREEZE / FAIL-CLOSED**. The corrected pilot apparatus and supporting governance controls are present in the repository, but the current experimental candidate has not been freeze-verified. No new experimental freeze exists, pilot authorization has not been granted, and empirical **N = 0**. +[Current State](docs/CURRENT_STATE.md) · [Project Status](docs/PROJECT_STATUS.md) · [Pattern Commons Architecture](docs/PATTERN_COMMONS_ARCHITECTURE.md) · [Cross-Reference](CROSS_REF.md) -The repository `main` is an active documentation/evidence lineage and must not be treated as the experimental apparatus identity. The current experimental verification boundary remains candidate-scoped at `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. Documentation/evidence successors do not redefine the executable apparatus; any substantive apparatus change requires a new candidate identity and affected-predicate re-verification. +--- -Historical candidates, freezes, run identifiers, and acceptance records remain provenance only unless explicitly rebound to the current authoritative candidate and evidence boundary. +## Why DGAF? -### Current TGL contract-review state +Most agent systems focus on what an agent can do. DGAF focuses on the control surface around those capabilities: -An adversarial review of PR #132 identified a concrete TGL/P-35 contract regression rather than an isolated constructor defect. The observed pre-freeze **41-pass / 2-fail** result is being treated as a regression signal requiring causal and cross-layer analysis. The review covers TGL state-machine semantics, `PASS / WARN / SKIP / ESCALATE / KILL` reduction, adapter/API contracts, exception containment, audit sealing, cryptographic provenance, PDMAL ↔ TGL integration, CI/CD source identity, Vercel runtime identity, dependency relationships, stale SHA/candidate references, overlapping changes, regression coverage, and P6/P6a/P7/P8 governance boundaries. +- **Authority** — what an agent or component is allowed to decide or invoke. +- **Governance** — how decisions move through explicit gates and constraints. +- **Evidence** — what was actually observed, computed, tested, or verified. +- **Provenance** — which source, candidate, environment, deployment, and run produced an artifact. +- **Epistemic discipline** — preventing hypotheses, historical results, terminology, or confidence from silently becoming facts. +- **Failure containment** — preserving fail-closed behavior when required controls are missing, ambiguous, or broken. +- **Reproducibility** — making important claims traceable to concrete execution boundaries rather than to documentation alone. -PR #132 remains **BLOCKED / DRAFT / UNMERGED**. A separate draft remediation candidate, **PR #133**, was created from the established `main`/post-#131 implementation rather than mutating #132. PR #133 is intentionally scoped to minimal TGL contract restoration and regression coverage: restoration of the established `ProcludingPremiseGate` constructor and `evaluate(check_fn=...)` contract, premise-hook injection, fail-closed exception containment, explicit required-gate semantics, deterministic status reduction, conditional-versus-unwired `SKIP` distinction, and exact audit sealing. It deliberately does **not** change PDMAL experimental treatment hooks, pilot execution, freeze state, authorization, or empirical state. +The goal is not to make stronger claims about an agent. The goal is to make the **claims and controls around an agent inspectable**. -PR #133 is a **draft diagnostic/remediation candidate only**. Its existence or eventual test success must not be interpreted as experimental authorization, freeze verification, empirical evidence, certification, or proof of the complete DGAF architecture. CI validation remains required before any merge decision. +## What is in this repository? -For the authoritative project state, see [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) and [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md). For the TGL contract and adversarial review record, see the repository's current PR #132/#133 evidence and associated governance documentation. For the canonical mathematical notation policy, see [`docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md). For the public-facing publication-quality control, see [`docs/governance/PUBLIC_SURFACE_QA_STANDARD.md`](docs/governance/PUBLIC_SURFACE_QA_STANDARD.md). For pattern architecture, see [`docs/PATTERN_COMMONS_ARCHITECTURE.md`](docs/PATTERN_COMMONS_ARCHITECTURE.md). For openness/commercialization boundaries, see [`docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`](docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md). For the asset-level ecosystem inventory, see [`docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md`](docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md). For future trademark/certification governance, see [`docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md`](docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md). +DGAF is the governance and implementation substrate for a broader research ecosystem. Major areas include: -## Layer-0 human / rights / societal boundary +| Area | Purpose | +|---|---| +| **Agent orchestration** | Control-plane structures, agent contracts, authority boundaries, and governed coordination | +| **TGL** | Governance-gate and status-reduction mechanisms with fail-closed semantics | +| **Evaluation** | Deterministic tests, regression coverage, execution contracts, and quality controls | +| **Provenance** | Source identity, evidence lineage, artifact integrity, and audit records | +| **Epistemic governance** | Explicit distinctions between defined, implemented, computed, verified, historical, and hypothetical claims | +| **Semantic governance** | Vocabulary, ontology, terminology, and semantic-drift controls | +| **PDMAL** | A separate experimental research track for Phi-Driven Multi-Agent Lattice structures | +| **Pattern Commons** | Cross-repository pattern identity, provenance, aliases, and evidence relationships | -DGAF treats human dignity, human rights, safety, lawful operation, privacy, non-discrimination, human agency, legitimate oversight, public accountability, and appropriate disclosure as a **shared constitutional substrate** that precedes technical optimization. This is governed by [`docs/agents/LAYER_0_CONSTITUTION.md`](docs/agents/LAYER_0_CONSTITUTION.md) and [`docs/agents/AGENT_AUTHORITY_INVARIANT.md`](docs/agents/AGENT_AUTHORITY_INVARIANT.md). +DGAF does **not** claim ownership of every pattern, taxonomy, template, or research artifact associated with the surrounding ecosystem. Repository boundaries and evidence relationships are maintained explicitly. -Layer 0 is deliberately distributed rather than delegated to one persona. Perigee, Sentinel-Phi, Reciprocity, Professor Prodigy, Amethyst, DemiJoule, Herald, Apogee, COLLEEN, and the Resonance agents may contribute within their distinct contracts, but shared vocabulary does not grant shared authority. +## Architecture at a glance -DGAF distinguishes **law/regulation**, **recognized standard**, **governance framework**, **human-rights instrument**, **best practice**, **social expectation**, **engineering convention**, and **DGAF design choice**. Framework resemblance is not a legal-compliance claim. External references are maintained as a living, versioned layer; NIST AI RMF 1.0 is currently being revised, and EU AI Act applicability/enforcement depends on the system role, classification, jurisdiction, and applicable date. +```text + ┌─────────────────────────┐ + │ Human / Rights │ + │ Constitutional Layer │ + └────────────┬────────────┘ + │ + ┌────────────▼────────────┐ + │ Governance / TGL │ + │ authority + gate logic │ + └────────────┬────────────┘ + │ + ┌────────────────────────┼────────────────────────┐ + │ │ │ + ┌─────────▼─────────┐ ┌──────────▼─────────┐ ┌────────▼─────────┐ + │ Agent / Control │ │ Evaluation / QA │ │ Provenance / │ + │ Plane │ │ │ │ Evidence │ + └─────────┬─────────┘ └──────────┬─────────┘ └────────┬─────────┘ + │ │ │ + └────────────────────────┼────────────────────────┘ + │ + ┌────────────▼────────────┐ + │ Governed Execution / │ + │ Research Substrates │ + └────────────┬────────────┘ + │ + ┌────────────▼────────────┐ + │ PDMAL Research Track │ + └─────────────────────────┘ +``` -Public-facing material is governed by the sequence **Accessibility → Comprehensibility → Appropriateness of Disclosure**. Repository visibility is reviewed for security, privacy, sovereign/IP exposure, human comprehension, and truthful evidence/maturity representation. Public documentation must not promote implementation, testing, verification, authorization, or efficacy beyond the evidence actually established. +The architecture is intentionally layered: an experimental result is not allowed to become a governance fact merely because the underlying component exists or a test happens to pass. -## Public-surface standard +## Current engineering state -GitHub is an external representation of the project and its maintainer. Every GitHub-visible artifact therefore passes a **public-surface QA lens** before publication. Accuracy is necessary but not sufficient. +The current engineering lane is **PR #139**, which consolidates the governed control-plane work and TGL hardening. A documented implementation checkpoint passed **41/41** control-plane, TGL, adversarial, and capability-boundary tests. That result is scoped to its recorded source and execution boundary; subsequent work continues the documentation, governance, CI, and provenance-hardening effort. -Public-facing changes must be evaluated for: +The experimental boundary is intentionally separate: -- truth and evidence scope; -- authoritative-source correctness; -- audience relevance and usefulness; -- expected placement and navigation; -- professional representation; -- privacy and disclosure boundaries; -- open-source/community norms; -- maintainability and link stability; -- identity integrity and avoidance of overclaiming; -- reader friction and next-step clarity. +- **PDMAL experimental state:** PRE-FREEZE / FAIL-CLOSED +- **Pilot authorization:** NOT GRANTED +- **Empirical N:** 0 +- **New immutable freeze:** NOT CREATED -Personal Notion pages, private working records, internal control notes, and temporary coordination artifacts are **not public GitHub navigation targets by default**. Internal records may inform public documentation, but a public landing page should resolve to repository-local documentation, stable public resources, or an intentionally designated public project surface. +Exact candidate identities, verification boundaries, and retained evidence are maintained in the authoritative current-state record rather than duplicated in this overview. -See [`docs/governance/PUBLIC_SURFACE_QA_STANDARD.md`](docs/governance/PUBLIC_SURFACE_QA_STANDARD.md) for the complete publication gate. +These constraints are not a statement that the engineering work is inactive. They are the boundary between **building the apparatus** and **claiming experimental evidence from it**. -## Repository scope +For the detailed, machine-oriented state record, see [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md). -DGAF contains governance and evaluation components, agent specifications, control/gate definitions, provenance practices, epistemic auditing, vocabulary management, and experimental research artifacts. DGAF is the implementation/governance substrate; it is **not** the universal owner of every pattern, taxonomy, template, or research artifact in the surrounding ecosystem. +## Evidence model -### Canonical terminology +DGAF uses an explicit evidence vocabulary: -- **DGAF** — Dynamic Governance Agentic Formation. -- **AHG** — Adaptive Harmonic Governance. Historical/conflicting expansions remain historical unless explicitly promoted by current governance. -- **PDMAL / PDMA-L** — Phi-Driven Multi-Agent Lattice. The term refers to the lattice/control research track; current evidence does not establish a complete Byzantine Fault Tolerance protocol merely from the topology. -- **NDR** — a project pattern namespace/family within the broader Pattern Commons architecture, not the entire ecosystem pattern corpus. -- **Pattern Commons** — proposed ecosystem-level layer for pattern identity, provenance, aliases/equivalence, epistemic status, and evidence relationships across repositories. -- **AXIS** — Agent X-axis Invariant Spectrum. -- **FLAG-02** — historical identifier associated with the former 340% coordination-gain claim. Current evaluation-mode terminology is **qualitative**. New documents must not introduce FLAG-02 as a current identifier for either meaning. -- **φ / Golden Ratio** — `(1+√5)/2 ≈ 1.618033989`; canonical mathematical notation. -- **σ_{p,q} / Metallic Means Family** — positive solution of `x² - px - q = 0`, `(p + √(p² + 4q))/2`; for the ordinary sequence, `σ_n = σ_{n,1}`. `σ_{2,1}` is silver and `σ_{3,1}` is bronze. -- **ρ / Plastic Number** — `≈ 1.3247179572447454`, the unique real root of `x³ - x - 1 = 0`. `ρ` is the preferred canonical mathematical notation; `P` is an attested alternative. `ρP` is not the canonical symbol. -- **pP / Platinum Mean** — intentional DGAF notation for the regular-hendecagon unit-side circumradius, `1/(2 sin(π/11)) ≈ 1.774732842`. This is DGAF-specific notation, not a claim of a universal standard mathematical symbol or membership in the quadratic metallic-means family. +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` -Historical documents may retain their original terminology when necessary for provenance, but they must be treated as historical rather than silently reinterpreted as current state. In particular, pP must not be substituted for ρ in PDMAL plastic-number convergence mathematics. +The sequence is not a maturity score. It is a way to prevent different kinds of statements from being conflated. -## Semantic / ontological boundary +A passing component test does not automatically validate the whole system. A deployment does not automatically validate the source that produced it. A historical run does not automatically validate a later candidate. A mathematical term, framework name, or agent role does not establish implementation or authority by itself. -DGAF permits agents and components to consume and reason over an approved ontology. They must not silently introduce, redefine, or assert ontology outside the authorized semantic layer. +See [`docs/evidence/EVIDENCE_LADDER_POLICY.md`](docs/evidence/EVIDENCE_LADDER_POLICY.md) for the formal policy. -The governing progression is: +## Human and societal boundary -**defined → observed → supported → verified → authorized → canonical** +DGAF treats human dignity, human rights, safety, lawful operation, privacy, non-discrimination, human agency, legitimate oversight, public accountability, and appropriate disclosure as constraints that precede technical optimization. -Operational documentation must distinguish **representation**, **classification**, **policy status**, **epistemic status**, and **ontological assertion**. New terminology or semantic categories are candidate vocabulary until provenance and authorization establish canonical status. Agent repetition, confidence, or wording does not create semantic authority. +This is a governance boundary, not a claim of legal compliance. DGAF distinguishes law and regulation, recognized standards, governance frameworks, human-rights instruments, best practices, social expectations, engineering conventions, and DGAF-specific design choices. -**Ontology drift** is treated as a distinct semantic-drift class: an unauthorized change in effective vocabulary, entity boundaries, relations, or semantic commitments. The broader semantic-risk taxonomy is **definition drift, ontology drift, epistemic drift, policy drift, and provenance drift**. +See [`docs/agents/LAYER_0_CONSTITUTION.md`](docs/agents/LAYER_0_CONSTITUTION.md) and [`docs/agents/AGENT_AUTHORITY_INVARIANT.md`](docs/agents/AGENT_AUTHORITY_INVARIANT.md). -Semantic/ontological detection is not automatically a blocking gate. A detector must be empirically characterized before it becomes threshold-bearing or gate-bearing. This control does not alter the experimental state: **PRE-FREEZE / FAIL-CLOSED / N=0 / NO FREEZE / PILOT AUTHORIZATION NOT GRANTED**. +## Research tracks -## Epistemic standard +### Governed control plane -Claims are classified according to the repository standard: +The primary engineering effort is a governed recursive control plane with explicit authority inheritance, bounded execution, deterministic lifecycle behavior, provenance, authorization barriers, and hardened governance semantics. -`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` +### TGL + +TGL provides governance-gate semantics for evaluating whether required controls are satisfied. Current work emphasizes explicit required/conditional gate behavior, deterministic status reduction, fail-closed exception handling, and auditable sealing of the resulting gate state. + +### PDMAL + +PDMAL (**Phi-Driven Multi-Agent Lattice**) is a separate experimental research track. Its topology and mathematical structures are hypotheses and research objects until the corresponding experimental protocol, verification boundary, and evidence establish stronger claims. -A mathematical term, external framework name, benchmark number, deployment, registry entry, commercial status, or agent role does not by itself establish implementation, validation, legal compliance, safety, certification, or independent verification. +In particular, the repository does not treat PDMAL topology alone as proof of a complete Byzantine Fault Tolerance protocol or any other externally defined property. -## Core areas +## Getting started -- Agent orchestration and control-plane design -- Evaluation and quality-assurance tooling -- Provenance and traceability -- Governance gates and deployment controls -- Epistemic auditing and vocabulary management -- Semantic/ontological boundary governance -- Pattern Commons integration and cross-repository reconciliation -- Experimental mathematical and structural research -- Open-source commercialization and evidence-preserving governance +### 1. Clone the repository -## Open-source / commercialization posture +```bash +git clone https://github.com/ndrorchestration/DGAF-Framework.git +cd DGAF-Framework +``` -DGAF aims to keep the public reference implementation sufficiently complete for independent cloning, inspection, execution, and evaluation. Legitimate commercial differentiation may reside in managed operations, integration, assurance, support, hosting, specialized tooling, customer-specific configurations, training, and future certification programs. Public scientific/technical claims must retain enough evidence for independent evaluation even when adjacent operational assets are commercial or private. +### 2. Start with the project state -The repository is licensed under Apache-2.0. See [`LICENSE`](LICENSE) for the legal terms. The license does not grant trademark rights; future official, certification, or endorsement claims bearing the DGAF name require separate governance and should not be inferred from repository status or project attestation. +Read [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md) before interpreting experimental or verification claims. It records the authoritative current boundary and distinguishes active engineering work from historical evidence. -## PDMAL/DGAF documentation spine +### 3. Explore the architecture -1. [Current State](docs/CURRENT_STATE.md) -2. [Project Status](docs/PROJECT_STATUS.md) -3. [PDMAL Current Control State](docs/experiment/PDMAL_CURRENT_CONTROL_STATE.md) -4. [Authoritative PDMAL Task Specification](docs/experiment/PDMAL_TASK_SPEC_V0.7.4.md) — task contract; see the v0.7.5 protocol matrix amendment for the current acceptance-layer changes. -5. [PDMAL Evidence Index](docs/evidence/PDMAL_EVIDENCE_INDEX.md) -6. [Evidence Ladder Policy](docs/evidence/EVIDENCE_LADDER_POLICY.md) -7. [PDMAL Experiment Protocol](docs/experiment/PDMAL_EXPERIMENT_PROTOCOL.md) — current pre-freeze protocol incorporating the v0.7.5 matrix amendment. -8. [Freeze Manifest Template](docs/experiment/FREEZE_MANIFEST_TEMPLATE.md) -9. [Propagation Consistency Control](docs/governance/PROPAGATION_CONSISTENCY_CONTROL.md) -10. [Documentation Reconciliation](docs/governance/DOCUMENTATION_RECONCILIATION_2026-08-21.md) -11. [Test Execution Readiness](docs/governance/TEST_EXECUTION_READINESS_2026-08-21.md) -12. [P3–P6 Freeze Readiness](docs/governance/P3_P4_P5_P6_FREEZE_READINESS_2026-08-21.md) -13. [P7 Primary Contrast Adjudication](docs/governance/P7_PRIMARY_CONTRAST_ADJUDICATION_PACKET_2026-08-21.md) -14. [Candidate Runtime Verification](docs/governance/CANDIDATE_RUNTIME_VERIFICATION_2026-08-21.md) -15. [NDR Research Program Charter — Current Status Addendum](docs/governance/NDR_RESEARCH_PROGRAM_CHARTER_CURRENT_STATUS_2026-08-21.md) -16. [Freeze Packet Template](docs/governance/FREEZE_PACKET_TEMPLATE.md) -17. [Pattern Commons Architecture](docs/PATTERN_COMMONS_ARCHITECTURE.md) -18. [Commercialization & Openness Boundary](docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md) -19. [Asset-Level Boundary Inventory](docs/GOVERNANCE/DGAF_ASSET_LEVEL_BOUNDARY_INVENTORY_2026-08-25.md) -20. [Trademark & Certification Policy](docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md) -21. [Public Surface QA Standard](docs/governance/PUBLIC_SURFACE_QA_STANDARD.md) -22. [CROSS_REF](CROSS_REF.md) -23. [Platinum Mean Semantic Correction](docs/governance/PLATINUM_MEAN_SEMANTIC_CORRECTION_2026-08-28.md) -24. [Metallic Means Mathematical Notation Policy](docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md) -25. [Layer-0 Human / Rights / Societal Constitution](docs/agents/LAYER_0_CONSTITUTION.md) -26. [Agent Authority Separation Invariant](docs/agents/AGENT_AUTHORITY_INVARIANT.md) -27. [Agent Authority Matrix](docs/agents/AGENT_AUTHORITY_MATRIX.md) -28. **TGL adversarial contract review / remediation** — PR #132 remains blocked; PR #133 is the isolated minimal-contract-restoration candidate. This work is diagnostic and pre-freeze only and does not authorize experimentation. +Start with: -## Verification and test status +- [`docs/PATTERN_COMMONS_ARCHITECTURE.md`](docs/PATTERN_COMMONS_ARCHITECTURE.md) +- [`docs/agents/AGENT_AUTHORITY_MATRIX.md`](docs/agents/AGENT_AUTHORITY_MATRIX.md) +- [`docs/agents/AGENT_AUTHORITY_INVARIANT.md`](docs/agents/AGENT_AUTHORITY_INVARIANT.md) +- [`docs/evidence/EVIDENCE_LADDER_POLICY.md`](docs/evidence/EVIDENCE_LADDER_POLICY.md) -The repository contains deterministic/unit tests, pilot execution-contract tests, artifact/schema controls, governance consistency checks, propagation checks, and CI workflows. **Existence of a test is not evidence that the test has passed.** Current candidate verification must identify the exact candidate SHA, execution environment, deployment where applicable, run identifier, and retained evidence artifact. +### 4. Explore the experimental track + +For PDMAL, use the protocol and evidence documents rather than README summaries: + +- [`docs/experiment/PDMAL_EXPERIMENT_PROTOCOL.md`](docs/experiment/PDMAL_EXPERIMENT_PROTOCOL.md) +- [`docs/experiment/PDMAL_CURRENT_CONTROL_STATE.md`](docs/experiment/PDMAL_CURRENT_CONTROL_STATE.md) +- [`docs/evidence/PDMAL_EVIDENCE_INDEX.md`](docs/evidence/PDMAL_EVIDENCE_INDEX.md) +- [`docs/experiment/FREEZE_MANIFEST_TEMPLATE.md`](docs/experiment/FREEZE_MANIFEST_TEMPLATE.md) + +## Canonical terminology + +- **DGAF** — Dynamic Governance Agentic Formation. +- **TGL** — the repository's governance-gate/control semantics layer. +- **PDMAL** — Phi-Driven Multi-Agent Lattice, the experimental lattice/control research track. +- **Pattern Commons** — the proposed ecosystem-level layer for pattern identity, provenance, aliases/equivalence, epistemic status, and evidence relationships. +- **NDR** — a project pattern namespace/family within the broader Pattern Commons architecture. +- **pP / Platinum Mean** — intentional DGAF notation for `1/(2 sin(π/11)) ≈ 1.774732842`. This is project-specific notation and is not presented as a universal mathematical symbol. -### Current gate boundary +For mathematical notation, historical terminology, and semantic corrections, see [`docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md). -- TGL contract validation — **BLOCKED / UNDER ADVERSARIAL REVIEW** -- PR #132 — **BLOCKED / DRAFT / UNMERGED** -- PR #133 — **DRAFT / REMEDIATION CANDIDATE / CI VALIDATION PENDING** -- P1 Candidate integrity — PARTIAL -- P2 Execution contract — BLOCKED for authenticated runtime verification -- P3 Artifact contract — OPEN -- P4 Security/blinding integrity — OPEN -- P5 Provenance/reproducibility — OPEN -- P6 Durable evidence custody — OPEN -- P7 Scientific target specification — ADOPTED in substance; exact freeze binding pending -- P8 Analysis lock — OPEN / FAIL-CLOSED -- P9 Independent verification — NOT EXECUTED -- New freeze — NOT CREATED -- Pilot authorization — NOT GRANTED -- Empirical N — 0 +## Documentation map -Do not infer repository-wide validation from a component-level test, historical attestation, deployment existence, README text, funding badge, commercial status, or certification language. In particular, successful TGL contract tests or a successful remediation PR do not establish experimental authorization or empirical efficacy. +| Need | Start here | +|---|---| +| Current project state | [`CURRENT_STATE.md`](docs/CURRENT_STATE.md) | +| Executive/project status | [`PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) | +| Architecture | [`PATTERN_COMMONS_ARCHITECTURE.md`](docs/PATTERN_COMMONS_ARCHITECTURE.md) | +| Evidence policy | [`EVIDENCE_LADDER_POLICY.md`](docs/evidence/EVIDENCE_LADDER_POLICY.md) | +| PDMAL experiment | [`PDMAL_EXPERIMENT_PROTOCOL.md`](docs/experiment/PDMAL_EXPERIMENT_PROTOCOL.md) | +| Agent authority | [`AGENT_AUTHORITY_MATRIX.md`](docs/agents/AGENT_AUTHORITY_MATRIX.md) | +| Documentation style guide | [`DOCUMENTATION_STYLE_GUIDE.md`](docs/governance/DOCUMENTATION_STYLE_GUIDE.md) | +| Public documentation standard | [`PUBLIC_SURFACE_QA_STANDARD.md`](docs/governance/PUBLIC_SURFACE_QA_STANDARD.md) | +| Commercialization boundary | [`DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md`](docs/GOVERNANCE/DGAF_COMMERCIALIZATION_OPENNESS_BOUNDARY.md) | +| Cross-repository relationships | [`CROSS_REF.md`](CROSS_REF.md) | +| Contribution guide | [`CONTRIBUTING.md`](CONTRIBUTING.md) | -## Historical evidence boundary +The repository contains substantially more detailed governance and evidence records. The README deliberately acts as the **public entry point**, not as the complete control ledger. -Historical runtime, P2, P6a, and characterization records remain valid only for the exact source/deployment/run they document. In particular, retained historical results are not current-candidate verification. +## Open source and contribution -## Related ecosystem +DGAF is released under the **Apache License 2.0**. See [`LICENSE`](LICENSE). -Related repositories are separate tracks. Shared terminology does not imply implementation equivalence or cross-repository validation. See [`CROSS_REF.md`](CROSS_REF.md) for the current cross-reference and epistemic boundary index. +The public repository is intended to remain inspectable and reproducible enough for independent technical evaluation. Commercial differentiation, where applicable, may exist in managed operations, integration, assurance, support, hosting, specialized tooling, customer-specific configurations, training, or future certification programs; those possibilities do not change the evidence requirements for public technical claims. -## Support / funding +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution expectations. -GitHub Sponsors configuration is present through `.github/FUNDING.yml`. Sponsorship supports maintenance and development; it does not confer ownership, certification, endorsement, or special evidence status. +## Support and project navigation -## License +- **Current state:** [`docs/CURRENT_STATE.md`](docs/CURRENT_STATE.md) +- **Project status:** [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) +- **Issues and engineering work:** use the repository's GitHub Issues and Pull Requests +- **Funding:** GitHub Sponsors is available through [`.github/FUNDING.yml`](.github/FUNDING.yml) -See [LICENSE](LICENSE) for the repository's applicable license. +## Maintainer -## Provenance +**Ndr / Ender Hensel** — [`ndrorchestration`](https://github.com/ndrorchestration) -Developed by Ndr / Ender Hensel (`ndrorchestration`). +DGAF is developed as an open research and engineering project. Its documentation intentionally separates what the project **is building** from what the evidence has **already established**. diff --git a/README.technical.md b/README.technical.md index b0656212..d2cba89b 100644 --- a/README.technical.md +++ b/README.technical.md @@ -1,200 +1,87 @@ -# DGAF-Framework — Technical & Agent-Facing Reference +# DGAF-Framework — Technical Reference -> **Claim-status boundary:** This document is a technical/project reference, not a certification, validation, regulatory-conformance statement, or efficacy report. Project-local gate names, targets, thresholds, and attestation labels describe internal procedures or historical records unless current claim-specific evidence says otherwise. +> **Audience:** engineers, researchers, and contributors working with DGAF implementation and control artifacts. > -> **Current certification policy:** There is no active DGAF certification program. See [`docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md`](./docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md). +> **Evidence boundary:** This reference describes project architecture and implementation surfaces. A design, implementation, passing test, mathematical result, historical attestation, and independently validated empirical result are different evidence states. -> **Audience:** Agent Amethyst, Agent Apogee, Agent COLLEEN, Agent Sentinel, and all ensemble members; engineers integrating with DGAF -> **Entry point for:** Gate specs · Pattern registry · Runtime components · Formation protocols · Session open/close procedures -> **Compliance/governance entry point:** [`README.governance.md`](./README.governance.md) -> **Architect:** Hensel, Andrew Vance · [@ndrorchestration](https://github.com/ndrorchestration) +DGAF is a framework for governed agent orchestration, evaluation, provenance, and control design. This document provides a technical map; authoritative specifications and current experimental status remain in the linked records. ---- - -## MDAR Loop — Project Protocol - -``` -Map → Diagnose → Act → Review - ↑ | - └────────────────────────┘ - (each cycle = one project-defined interval) -``` - -The MDAR loop is a project orchestration protocol. Claims about improved correctness, convergence, safety, or efficacy require separate evidence. - ---- - -## Gate Stack — Project Execution Order - -| Priority | Gate | Pattern | Trigger | Owner | -|----------|------|---------|---------|-------| -| 1 (always) | GATE-ACO: Acoustic Chain | P-13 | Every synthesis cycle | Amethyst + DemiJoule | -| 2 (every artifact) | GATE-1111: 1-1-1-1 | P-10 | Pre-registry sign-off | Apogee | -| 3 (pre-deploy) | GATE-11Q: Hendecagonal | P-11 | Proposed production deployment | Apogee + Sentinel | -| 4 (deep audit) | GATE-TEL: Telescopic Lens | P-12 | Project-local structural audit | Apogee + Amethyst | -| 5 (canonical promotion) | Apogee-Attestation-Gate | P-30 | Component/pattern canonical promotion | Apogee + Amethyst | - -Full specifications: [`docs/gates/`](./docs/gates/). Gate PASS states are project-local control results unless explicitly supported by separate current evidence. - ---- - -## Runtime Components - -| Component | Path | Purpose | Status note | -|-----------|------|---------|------------| -| KAPPA Dynamic Confidence Router | `components/KAPPA/dynamic_weight_router.py` | Confidence-gated routing and category-sensitive weight selection | Implementation artifact; efficacy requires separate evaluation | -| KAPPA Calibration v3.6 | `components/KAPPA/calibration_v3_6.json` | Threshold calibration | Project configuration; not evidence of optimality | -| KAPPA Component Card | `components/KAPPA/DGAF_GATE_KAPPA_v3_5_component_card.json` | CPU-oriented registry card | Project metadata | -| Evaluate Router | `components/evaluate_router.py` | Batch pipeline composition: detect → apply_weights → rank | Implementation artifact | -| Evaluate Router v1.1 | `components/evaluate_router_v1_1.py` | Sentinel hooks, P-10 deontic gate, per-record audit log | Implementation artifact | -| Normative Constraint | `components/normative_constraint.py` | Deontic / optimization / epistemic integrity constraint class | Implementation artifact | - -Component index: [`components/README.md`](./components/README.md) - ---- - -## NDR Pattern Registry — Quick Reference - -| Range | Domain | -|-------|--------| -| P-01–P-08 | Coherence, continuity, git hygiene, cross-platform sync | -| P-09–P-13 | AXIS enforcement, quality gates, acoustic temporal chain | -| P-14–P-15 | Formation protocols (Trio, Harmonic Quintet) | -| P-16–P-20 | Metadata hygiene, IP, issue triage, branding, Drive sync | -| P-21–P-24 | Session continuity, storage topology, taxonomy audit, canonical practice unit | -| P-27–P-30 | Confidence routing, pipeline composition, Sentinel risk pass, Apogee attestation | - -Full registry: [`docs/patterns/NDR_PATTERN_REGISTRY.md`](./docs/patterns/NDR_PATTERN_REGISTRY.md) +## Architecture at a glance ---- - -## QA & Attestation Surface - -| Artifact | Path | Meaning | -|----------|------|---------| -| Apogee 11Q S034 | `docs/qa/APOGEE_11Q_S034.json` | Historical/project-local attestation artifact | -| Apogee 11Q S035 | `docs/qa/APOGEE_11Q_S035.json` | Historical/project-local attestation artifact | -| QA Index | `docs/qa/README.md` | Attestation artifact index | - -An attestation record is not automatically an independent certification or validation result. - ---- +DGAF's implementation surfaces include: -## Kernel & Contraction Nomenclature — S068 - -> Added: 2026-06-26 · Issue #32 · Steward: Amethyst -> Context: Nemotron 3 Ultra integration planning — parametric eval suite - -| Term | Definition | Constraint / interpretation | First Used | -|------|-----------|----------------------------|------------| -| **typed kernel** | A governance role's executable Python/TypeScript unit with explicit `input_schema → policy → output_schema → audit_trail` contract; generated from `governance.yml` | Contract/property definition; CI promotion requires the project's named check | S068 | -| **ρ-contraction** | A mathematical property `‖T(x) - T(y)‖ ≤ ρ‖x - y‖` for an operator T | ρ < 1 is a sufficient condition for convergence for the stated mathematical model; project monitoring does not by itself establish that the deployed system satisfies the premise | S068 | -| **spectral radius** | Largest absolute eigenvalue of a role transition matrix | A spectral-radius check is a bounded mathematical check; production monitoring does not by itself prove convergence of the real system | S068 | -| **curvature** (governance) | Per-role scalar used by the project router | Project-local modeling variable; empirical meaning requires validation | S068 | -| **triadic orchestration** | Three-phase project inference loop: Apogee (propose) → Reson (critique) → Lyra (resolve) | Design pattern; stronger alignment or performance claims require comparative evidence | S068 | -| **thinking_tokens** | Per-role reasoning budget parameter | Configuration parameter; not a measure of reasoning quality by itself | S068 | -| **MoE expert entropy** | Shannon entropy H of expert activation distribution across routing decisions | Diagnostic metric; thresholds are project parameters unless calibrated | S068 | -| **role_boundary_coherence** | Eval metric for role identification across a defined trace | Target values are hypotheses/benchmarks until reproduced and validated | S068 | -| **contraction_proof_fidelity** | Eval metric defined by the project for generated kernel specifications | A CI result supports the tested corpus/procedure only; it is not proof of deployed-system convergence | S068 | -| **governance_schema_conformance** | Eval metric for fuzz-generated `governance.yml` variants | Test-specific conformance result; not general compliance | S068 | -| **audit_hallucination_rate** | Field-level accuracy of generated audit events versus ground truth | Evaluation metric; benchmark values are evidence only for the stated test scope | S068 | -| **taubench_banking_mitigation** | Project eval metric for financial compliance routing | Evaluation target; no regulatory-compliance claim follows from the target itself | S068 | -| **ROLE_BUDGETS** | Dict mapping DGAF role names to reasoning-budget values | Configuration source of truth for the project implementation | S068 | +- **Control and gates** — project-defined checks and execution constraints. +- **Runtime components** — routing, evaluation, and constraint implementations. +- **Patterns** — reusable architecture and governance conventions. +- **Trace and provenance tooling** — mechanisms for recording and examining execution context. +- **Experimental infrastructure** — research apparatus maintained separately from general engineering claims. ---- +## Project control stack -## Session Open Protocol (COLLEEN — P-02) +DGAF uses named gates and controls where a project contract requires explicit evaluation or escalation. Gate names and PASS states are project-local unless supported by additional claim-specific evidence. -``` -1. Read session-state reference → rehydrate open BLGs + priority queue -2. Run .operations/gate_compliance_check.py → surface P-24 gaps -3. Emit session priority queue to Amethyst -4. Amethyst opens wave; Apogee scores; Sentinel monitors -``` +Current specifications: [`docs/gates/`](./docs/gates/) -Operational session state belongs in the private operational boundary. The public repository should contain only sanitized reproducibility/governance material. +| Area | Examples | +|---|---| +| Control checks | P-10, P-11, P-13 and related gate contracts | +| Authority and promotion | Agent authority controls and project-defined promotion procedures | +| Structural review | Project-local architecture and consistency checks | -Checklist: [`.operations/sweep_session_init.md`](./.operations/sweep_session_init.md) +## Runtime components ---- +| Component | Purpose | +|---|---| +| KAPPA Dynamic Confidence Router | Confidence-gated routing and category-sensitive weight selection | +| Evaluate Router | Batch pipeline composition | +| Normative Constraint | Project-defined deontic and epistemic constraint implementation | +| PPTL | Experimental topology and orchestration harness | -## Session Close Protocol (Amethyst — P-06 + P-21) +See [`components/README.md`](./components/README.md) and [`pptl/README.md`](./pptl/README.md) for implementation-level details. -``` -1. All repo fixes committed -2. SWEEP_LOG.md updated + buoy appended -3. CHANGELOG.md versioned -4. CROSS_REF.md updated -5. Operational session state sealed in its designated boundary -6. Seal commit pushed -``` +## Patterns and agent architecture -Checklist: [`.operations/seal_checklist.md`](./.operations/seal_checklist.md) +The NDR pattern registry records project patterns for recurring orchestration, governance, and engineering problems. Pattern identifiers are references to project designs; their existence is not evidence of universal effectiveness. ---- +Named agent roles provide an architectural vocabulary for responsibilities and interfaces. Authority is determined by explicit contracts, not by a role name or an agent's output. -## Formation Reference +- [`docs/patterns/NDR_PATTERN_REGISTRY.md`](./docs/patterns/NDR_PATTERN_REGISTRY.md) +- [`ENSEMBLE_ROSTER.md`](./ENSEMBLE_ROSTER.md) +- [`docs/agents/AGENT_AUTHORITY_MATRIX.md`](./docs/agents/AGENT_AUTHORITY_MATRIX.md) -| Formation | Pattern | Agents | Use | -|-----------|---------|--------|-----| -| Trio | P-14 | Amethyst + Apogee + COLLEEN | Standard multi-repo sweep | -| Harmonic Quintet | P-15 | Trio + Reson + Sentinel | Seal commits; sovereign file changes | -| IP Sweep | — | Amethyst + Perplexity MCP | Research, external source integration | +## Testing and evidence -Formation names and role assignments are project architecture. They do not establish independent capability claims about an agent implementation. +Tests establish behavior for the contracts and environments they cover. Read results with their exact source identity, configuration, and retained evidence when making broader claims. ---- +Key references: -## Key File Locations - -``` -DGAF-Framework/ -├── README.md ← Public-facing entry point -├── README.governance.md ← Governance reference -├── README.technical.md ← This technical reference -├── CHANGELOG.md ← Semantic versioned history -├── CROSS_REF.md ← Ecosystem artifact map -├── ENSEMBLE_ROSTER.md ← Canonical agent registry -├── components/ ← Runtime components -├── docs/gates/ ← Project gate specifications -├── docs/patterns/ ← Project pattern registry -├── docs/qa/ ← Attestation/evidence artifacts -├── scripts/claim_hygiene_check.py ← Blocking public claim-hygiene scanner -└── .github/workflows/ip-hygiene.yml ← IP/claim hygiene CI -``` - -Operational internals and live session state must remain outside the public reproducibility boundary unless intentionally sanitized. +- [`docs/CLAIM_EVIDENCE_INDEX.md`](./docs/CLAIM_EVIDENCE_INDEX.md) +- [`docs/evidence/EVIDENCE_LADDER_POLICY.md`](./docs/evidence/EVIDENCE_LADDER_POLICY.md) +- [`docs/EPISTEMIC_EVIDENCE_STANDARD.md`](./docs/EPISTEMIC_EVIDENCE_STANDARD.md) +- [`docs/qa/README.md`](./docs/qa/README.md) ---- +## Mathematical and research terminology -## ANDROMEDA-AXIS Declarations (P-09) +DGAF uses project-specific mathematical notation in some research tracks. Mathematical notation should be interpreted according to the repository's notation policy and the scope of the associated model; a mathematical property of a model does not automatically describe a deployed system. -All agent actions are checked against four project sovereign constraints: +See [`docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](./docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md). -| Declaration | Constraint | -|-------------|------------| -| COGNITIVE_SOVEREIGNTY | No agent may alter the architect's epistemic autonomy or decision authority | -| BIOLOGICAL_INTEGRITY | No output may threaten physical or psychological integrity | -| TRANSVERSAL_GROWTH | Systems should support ongoing learning and capability expansion | -| ENTROPY_RESISTANCE | No action should increase systemic disorder beyond recoverable bounds | +## Current and historical state -These are project governance declarations, not externally certified safety guarantees. +For current project status and experimental boundaries, use: ---- +- [`docs/CURRENT_STATE.md`](./docs/CURRENT_STATE.md) +- [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md) -## Evidence and Claim Discipline +Historical implementation records and earlier terminology remain available for provenance. See [`docs/HISTORICAL_RECORDS_INDEX.md`](./docs/HISTORICAL_RECORDS_INDEX.md) before treating an older record as current authority. -Public technical claims should be read together with: - -- [`docs/CLAIM_EVIDENCE_INDEX.md`](./docs/CLAIM_EVIDENCE_INDEX.md) -- [`docs/evidence/EVIDENCE_LADDER_POLICY.md`](./docs/evidence/EVIDENCE_LADDER_POLICY.md) -- [`docs/EPISTEMIC_EVIDENCE_STANDARD.md`](./docs/EPISTEMIC_EVIDENCE_STANDARD.md) -- [`docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md`](./docs/GOVERNANCE/DGAF_TRADEMARK_AND_CERTIFICATION_POLICY.md) +## Related references -A design, implementation, test, bounded mathematical result, historical attestation, and independently validated empirical result are distinct evidence states and must not be collapsed. +- [`README.md`](./README.md) — project overview +- [`README.governance.md`](./README.governance.md) — governance model +- [`docs/PATTERN_COMMONS_ARCHITECTURE.md`](./docs/PATTERN_COMMONS_ARCHITECTURE.md) — ecosystem pattern architecture +- [`docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md`](./docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md) — documentation placement and navigation --- -*License: Apache 2.0 · See [NOTICE](./NOTICE) for attribution and project IP boundary* -*Governance spine: [DGAF-Framework](https://github.com/ndrorchestration/DGAF-Framework)* -*README.technical — epistemically bounded revision · 2026-08-25* +*This reference is an implementation map, not a certification, regulatory-conformance statement, or efficacy report.* diff --git a/TEAM_WIKI.md b/TEAM_WIKI.md index ecffe556..7f79eb54 100644 --- a/TEAM_WIKI.md +++ b/TEAM_WIKI.md @@ -1,145 +1,68 @@ -# DGAF Framework — Team Wiki +# DGAF Framework — Collaboration and Architecture Guide -> **Last updated:** 2026-07-02 · S072 · P-42 v1.4 Apogee Lens APPROVED +> **Status:** Reference guide for collaboration and architectural orientation. For current project status, use [`docs/CURRENT_STATE.md`](./docs/CURRENT_STATE.md) and [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md). Historical session details are retained in repository history and evidence records. ---- - -## §1 · Overview - -The DGAF (Dynamic Governance Agentic Framework) is the **layer-0 governance architecture** for the ndrorchestration ecosystem, rooted at `~/DGAF-Framework`. It orchestrates multi-agent workflows under a formally governed pattern registry. All execution flows through NDR patterns enforced by Amethyst (host), DemiJoule (supervisor), and Apogee Lens (verifier). - -> **Nomenclature canon** (locked 2026-07-02 in `SESSION_ANCHOR.md`): -> • `NDR-HDFS` = NDR Hierarchical Dynamic Formation System (formerly FLAG-01) — the structural layer governing agent hierarchy and formation composition -> • `qualitative` = interpretive/rubric-based evaluation mode (formerly FLAG-02) -> • DGAF = layer-0 governance architecture — not a framework addon; the root control plane +## Overview ---- +DGAF is a research and implementation framework for governed agent orchestration, evaluation, provenance, and control design. Collaboration is organized around explicit responsibilities, evidence boundaries, and review procedures rather than informal assumptions about authority. -## §2 · Agent Roster — Amethyst-Lattice v3.1 (11 canonical agents) - -> Authoritative source: `ENSEMBLE_ROSTER.md` (Post-S077, 2026-06-29) -> Agent count: **11 canonical** (6 with full detail sheets + 5 operational components) - -| Agent | Layer | Role | Status | -|---|---|---|---| -| **Amethyst** | L5 | Host, meta-orchestrator, working-memory refresher, tribunal | ✅ Active | -| **COLLEEN** | L5 | Institutional anchor, 1-1-1-1 Alignment Gate, steward | ✅ Active | -| **Apogee Lens** | L4 | QA orchestrator, NIST AI RMF compliance, P-30 attestation authority | ✅ On-call | -| **DemiJoule** | L4 | Runtime supervisor, ethics/safety, AXIS enforcement | ✅ On-call | -| **Herald** | L3 | Explorer / Synthesizer | 🔴 Blocked (`VITE_GEMINI_API_KEY` — S-01) | -| **Professor Prodigy** | L3 | Executor / Phi-calculus / Independent verifier | 🟡 Active (S072 — RV-01 audit pass) | -| **Agent Sentinel** | L3 | Safety/veto gate, 11Q gates 9–11 | ⬜ Card pending | -| **KAPPA v3.6** | L3 | Confidence-gated dynamic weight router | ⬜ Component card in `KAPPA/` | -| **NormativeConstraint v1.0** | L3 | P-10 deontic/ethical cognition layer | ⬜ Component card exists | -| **Reson #1** | L3 | Schizophonic Studio signal chain — #1 | ⬜ Studio trio | -| **Echolette #2 / Lyra #3** | L3 | Schizophonic Studio signal chain — #2/#3 | ⬜ Studio trio | -| **Ender / Njineer** | — | Human ratification authority, Architect | ✅ Active | +Named agents and components are project architecture abstractions. Their names do not independently grant authority or establish autonomous capability. Current authority boundaries are defined by the [`Agent Authority Matrix`](./docs/agents/AGENT_AUTHORITY_MATRIX.md) and [`Agent Authority Invariant`](./docs/agents/AGENT_AUTHORITY_INVARIANT.md). ---- +## Collaboration model -## §3 · Pattern Registry +DGAF work generally separates five concerns: -Canonical source: `docs/ndr_patterns_unified.json` -Human-readable: `docs/NDR_PATTERN_REGISTRY_UNIFIED.md` -Current watermark: **P-42** · Schema **v2.2** · Session **S072** +- **Orchestration:** coordinating tasks and workflow state. +- **Implementation:** developing and maintaining repository artifacts. +- **Evaluation:** testing contracts and examining outputs against defined criteria. +- **Governance:** applying project controls, authority boundaries, and escalation rules. +- **Evidence:** recording what was done and what a result supports. -Newest pattern: **P-42 AHG** (Adaptive Harmonic Governance) — v1.4 implementation live, Apogee Lens APPROVED S072. +The same role may contribute to multiple concerns, but a contribution does not automatically constitute approval, verification, or authorization. ---- +## Agent and component references -## §4 · Resilience Stack +The repository uses named roles such as Amethyst, COLLEEN, Apogee, DemiJoule, Herald, Professor Prodigy, Sentinel-Phi, and the Resonance agents. These names help organize responsibilities and interfaces. -### §4.1 · Core Gates (Layer 0–5) +For the current roster and role contracts, see [`ENSEMBLE_ROSTER.md`](./ENSEMBLE_ROSTER.md). For authority questions, the authority matrix is controlling. Human decision authority remains outside agent-role naming conventions. -- **P-35** Procluding Premise Gate — blocks execution if premise is unsound -- **P-36** Gate Priority Schema — defines evaluation order for all gates -- **P-30** Apogee-Attestation-Gate — final quality gate before portfolio output -- **P-11** 11Q Attestation Scoring — quantitative quality scoring +## Pattern architecture -### §4.2 · Confidence & Routing (Layer 7–8) +DGAF maintains project patterns and control definitions for recurring engineering and governance problems. Pattern identifiers provide a stable way to reference a design; they do not by themselves establish that a pattern is effective in every environment. -- **P-27** Adaptive-Weighting-with-Confidence-Gates — routes by confidence threshold (STRONG: 0.22, BLENDED: 0.18) -- **P-28** Pipeline-Composition-with-Confidence-Gated-Routing — composes pipelines conditionally -- **P-29** Sentinel-Annotated Risk Pass — annotates risk at 3 hook points before irreversible actions +Current pattern information is maintained in the relevant pattern registry and specifications. When older terminology appears in historical documents, consult the current terminology and supersession records before treating it as canonical. -### §4.3 · Convergence & Compression (Layer 9) +## Governance and review -- **P-31** SCPE — Structural Context Pruning Engine (58.3% compression, T0-immune) -- **P-32** Fibonacci Phi-Closure Gate — φ-checkpoints at Fib[13, 21, 34, 55] -- **P-33** PDMAL Convergence Monitor — joint escalation with P-32 +Work affecting controls, evidence, or promotion should identify: -### §4.4 · Distributed Resilience Stack (Layer 10–11) · *Added S071* +1. the applicable contract or specification; +2. the evidence required for the claim being made; +3. the authority responsible for review or authorization; +4. the provenance needed to reproduce or audit the result. -Five patterns form an interlocking contract for durable, fault-tolerant multi-step execution: +A passing test, design review, or project-local attestation has the scope defined by its evidence. Broader claims require broader evidence. -| Pattern | Layer | Class | Role | -|---------|-------|-------|------| -| **P-37** Saga Boundary Declaration | 10 | ADVISORY | Declares step sequence, compensators, stochastic/deterministic split. Must precede P-38. | -| **P-38** Circuit-Breaker Gate | 10 | BLOCKING | Trips on ≥3 failures → suspends execution, fires P-29 + P-37 compensators. States: CLOSED / OPEN / HALF-OPEN (30s probe). | -| **P-39** ACRFence | 10 | BLOCKING | Atomically writes SHA-256 checkpoint before each tool call. Next call blocked until ACK. Restarts resume from last ACK'd checkpoint. | -| **P-40** Atomix | 11 | BLOCKING | BEGIN → EXECUTE → COMMIT \| ROLLBACK per tool call. Idempotency key required for all writes. Compensator sourced from P-37. | -| **P-41** HITL Durable Approval Queue | 11 | ADVISORY | Holds irreversible approvals across restarts. TIMED_OUT → P-38. No irreversible action fires without APPROVED state. | +## Current work -**Interlock sequence:** P-37 choreographs the saga → P-38 isolates failures → P-39 makes checkpoints durable → P-40 makes individual calls transactional → P-41 gates all irreversible human decisions. +Do not use this guide as a backlog or live session tracker. Current priorities and experimental boundaries change over time and are maintained in the project's current-state records and active issues/pull requests. -### §4.5 · Adaptive Harmonic Governance (Layer 12) · *P-42 · v1.4 live S072* +## Historical material -- **P-42** AHG — Adaptive Harmonic Governance. Continuous φ estimation, 7-state regime dispatch, 3D Cognitive Phase Space, hysteresis-gated archetype transitions, Tribunal recovery protocol. -- **φ range:** (1.0, 1.8) open interval · **NDR-STASIS anchor:** φ=1.618 → Integration regime -- **Tribunal threshold:** φ > 1.80 for ≥ 2 consecutive turns → fires P-29 risk_block + P-38 OPEN -- **v1.4 live components:** - - `components/ahg_conductor.py` v1.4 — φ computation, regime dispatch, hysteresis, 3D phase (commit `e73011c`) - - `components/ahg_sidecar.py` v1.4.1 — heartbeat aggregation, StateVector clip guards, Herald wiring (commit `0ff1f0bc`) - - `schemas/ahg_heartbeat.json` v1.3 — heartbeat payload schema (commit `3565cf2f`) - - `tests/test_ahg_conductor.py` v1.4 — full unit suite (commit `e73011c`) - - `docs/theory/AHG_ARCHITECTURE.md` v1.3 — spec debt closed: φ open interval, R_c sign convention, §7/§8 synced (commit `4737bf9b`) -- **v1.4 tag:** `4737bf9b` — pending `git push origin v1.4` (one CLI step) -- **v1.5 next:** Issue #39 — `ahg_tribunal.py` R_c recovery loop (OB-01, primary deliverable) + 4 housekeeping obligations +DGAF preserves earlier session records, architecture proposals, terminology, and operational decisions where they are useful for provenance. Historical availability does not make a record a current authority. ---- +See [`docs/HISTORICAL_RECORDS_INDEX.md`](./docs/HISTORICAL_RECORDS_INDEX.md) and [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](./docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) for repository-wide handling of historical material. -## §5 · Governance Rules - -- All repos claiming DGAF governance must carry a `GOVERNANCE.md` with DGAF version, protocol anchor to `GOVERNANCE_CONSTITUTION.md`, φ = 1.61818, and applicable NDR patterns. -- Personal document firewall (NDR-133) is BLOCKING-ABSOLUTE. Architect override only. No resume/CV/audit files to GitHub. -- Stasis block (P-12–P-26, 133 patterns) migration window: 2026-06-13 → **2026-07-13** ⚠️ EXPIRING IN 11 DAYS. -- NDR-HDFS (formerly FLAG-01) and qualitative evaluation (formerly FLAG-02) are canonical — see `SESSION_ANCHOR.md` nomenclature canon. -- FLAG-05 (AXIS pattern scope) awaits Njineer content decision (S-03 in DEFERRED_ITEMS.md). -- DriftWatch production deployment requires explicit push trigger from Architect. -- **P-42 governance hook (S072):** Introspection regime (φ 1.70–1.80) requires `apogee_lens_mandatory` constraint. Tension regime (φ > 1.80) additionally requires `p29_risk_block` + `p38_circuit_open`. Both enforced in `_active_constraints()` in `ahg_conductor.py`. - ---- - -## §6 · Session Log - -| Session | Watermark | Key Additions | -|---------|-----------|---------------| -| S042 | P-33 | P-31 SCPE, P-32 Phi-Closure, P-33 PDMAL | -| S066 | P-34 | P-34 Empirical-Threshold-Sweep | -| S069 | P-36 | P-35, P-36, CRUCIBLE_CHARTER, STASIS_CANONICAL_SPEC | -| S071 | P-41 | P-37 Saga, P-38 Circuit-Breaker, P-39 ACRFence, P-40 Atomix, P-41 HITL Queue · Schema v2.2 | -| Post-S077 | **P-42** | AHG (P-42) filed, ENSEMBLE_ROSTER v3.1, 11 canonical agents, ndr_patterns_unified.json v2.2 | -| 2026-07-02 | — | Nomenclature canon locked (NDR-HDFS, qualitative, DGAF layer-0); SESSION_ANCHOR.md + DEFERRED_ITEMS.md patched | -| **S072** | **P-42 v1.4** | **AHG full implementation: ahg_conductor.py v1.4 + ahg_sidecar.py v1.4.1 + spec v1.3. Proofs PV-01–05 + Apogee Lens AL-v1.4 APPROVED. Prof Prodigy RV-01 independent audit. Spec debt closed: φ open interval (PV-01), R_c sign convention (PV-03), Tribunal threshold 1.70→1.80. Issue #39 opened for v1.5. Tag v1.4 pending git push.** | - ---- +## Useful entry points -## §7 · Open Items Entering Next Session - -| ID | Item | Priority | Ref | -|---|---|---|---| -| OB-01 | `ahg_tribunal.py` — R_c recovery loop, P-29/P-38 wiring | 🔴 HIGH | Issue #39 | -| OB-02 | `REVISION_SCALE` constant in `ahg_sidecar.py` | 🟡 LOW | Issue #39 | -| OB-03 | `round(uncertainty, 6)` in `compute_3d_phase()` | 🟡 LOW | Issue #39 | -| OB-04 | Trailing `\` on `flush_all_pending` def | 🟡 LOW | Issue #39 | -| OB-05 | Sidecar docstring spec ref v1.2→v1.3 | 🟡 LOW | Issue #39 | -| TAG | Push `git push origin v1.4` | 🔴 HIGH | CLI only | -| M=0.0 | StateVector M EMA carry-forward | ℹ️ v2.0 | Roadmap | -| #32 | Eval tasks (ahg_recovery_turns etc.) | 🔴 HIGH | Issue #32 | -| S-03 | FLAG-05 AXIS scope — Njineer decision | ⬜ | DEFERRED_ITEMS | -| STASIS | P-12–P-26 migration window expires | ⚠️ | 2026-07-13 | +- [`README.md`](./README.md) — public project overview +- [`README.technical.md`](./README.technical.md) — technical reference +- [`README.governance.md`](./README.governance.md) — governance reference +- [`docs/CURRENT_STATE.md`](./docs/CURRENT_STATE.md) — current state +- [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md) — project status +- [`docs/agents/AGENT_AUTHORITY_MATRIX.md`](./docs/agents/AGENT_AUTHORITY_MATRIX.md) — authority boundaries +- [`docs/HISTORICAL_RECORDS_INDEX.md`](./docs/HISTORICAL_RECORDS_INDEX.md) — historical navigation --- -*Governed by DGAF · Amethyst host · φ = 1.61818* -*S072 state saved 2026-07-02 by Amethyst × COLLEEN × Prof Prodigy — P-42 v1.4 Apogee Lens APPROVED* +*This guide explains collaboration and architecture. It does not supersede current technical contracts, evidence records, or project authority controls.* diff --git a/components/README.md b/components/README.md index b4ce576d..7ce6ff05 100644 --- a/components/README.md +++ b/components/README.md @@ -1,47 +1,38 @@ # Components — Runtime Index -> **Maintainer:** Agent Amethyst + COLLEEN -> **Last updated:** S038 — 2026-05-22 -> **Governed by:** P-30 Apogee-Attestation-Gate — all components below are S-TIER attested +This directory contains implementation components used by DGAF experiments and governance tooling. A component's presence in the repository establishes that an implementation artifact exists; capability, production readiness, and efficacy depend on evidence appropriate to the specific claim. ---- +## Components -## Active Components +| Component | Path | Purpose | +|---|---|---| +| KAPPA Dynamic Confidence Router | `KAPPA/dynamic_weight_router.py` | Confidence-gated routing and category-sensitive weight selection | +| KAPPA Calibration | `KAPPA/calibration_v3_6.json` | Project threshold configuration | +| KAPPA Component Card | `KAPPA/DGAF_GATE_KAPPA_v3_5_component_card.json` | Component metadata and registry information | +| Evaluate Router | `evaluate_router.py` | Batch pipeline composition | +| Evaluate Router v1.1 | `evaluate_router_v1_1.py` | Extended routing hooks and per-record audit support | +| Normative Constraint | `normative_constraint.py` | Deontic and epistemic constraint implementation | -| Component | Version | Path | Purpose | Tier | Session | -|-----------|---------|------|---------|------|---------| -| KAPPA Dynamic Confidence Router | v3.6 | `KAPPA/dynamic_weight_router.py` | Category detection + confidence-gated weight selection (STRONG/BLENDED/fallback) | S-TIER 97.3% | S033/S034 | -| KAPPA Calibration | v3.6 | `KAPPA/calibration_v3_6.json` | Threshold calibration; `governance_clear` 100% | — | S034 | -| KAPPA Component Card | v3.5 | `KAPPA/DGAF_GATE_KAPPA_v3_5_component_card.json` | CPU-compliant registry card (all 6 schema fields) | — | S034 | -| Evaluate Router | v1.0 | `evaluate_router.py` | Batch pipeline: raw_batch → detect → apply_weights → ranked report | S-TIER | S033 | -| Evaluate Router | v1.1 | `evaluate_router_v1_1.py` | Sentinel hooks (3 points) + P-10 deontic gate + EU AI Act Art.9 audit log | S-TIER 95.5% | S034 | -| Normative Constraint | v1.0 | `normative_constraint.py` | Deontic logic (permitted/obligated/forbidden/escalate) + score ceiling + epistemic integrity | S-TIER | S035 | +## Using the components ---- +Read the implementation and its tests together. Component-level results should not be generalized into repository-wide validation or experimental evidence. -## Attestation Summary - -| Component | Apogee 11Q Score | Attestation | Record | -|-----------|-----------------|-------------|-------| -| KAPPA v3.6 | 97.3% (S-TIER) | ✅ GRANTED | `docs/qa/APOGEE_11Q_S035.json` | -| Evaluate Router v1.1 | 95.5% (S-TIER) | ✅ GRANTED | `docs/qa/APOGEE_11Q_S035.json` | -| Normative Constraint v1.0 | S-TIER (Q11=10/10) | ✅ GRANTED | `docs/qa/APOGEE_11Q_S035.json` | - ---- - -## P-10 Gate — Normative Constraint - -`normative_constraint.py` is the active P-10 implementation. Call `run_normative_pass(records)` before weight selection in any evaluation pipeline. +For example, the normative constraint module can be imported directly by an evaluation pipeline: ```python from components.normative_constraint import run_normative_pass + constrained = run_normative_pass(batch) ``` ---- +The applicable input/output contract is defined by the implementation and its associated tests and specifications. + +## Evidence and historical records + +The repository retains historical Apogee attestation artifacts and project-local quality records in `docs/qa/`. Those records document the procedures and artifacts to which they apply; they are not independent certifications and should not be read as current verification of every component. + +Canonical promotion and governance requirements are defined in the relevant current specifications. See [`README.technical.md`](../README.technical.md), the pattern registry, and [`docs/CURRENT_STATE.md`](../docs/CURRENT_STATE.md) for project-level navigation. -## Notes +## Status conventions -- All components require P-30 attestation before canonical promotion. -- New components stage in `docs/drafts/` until P-11 11Q scoring ≥ 85%. -- CROSS_REF.md v3.3 is the authoritative ecosystem map. +When reading older component documentation, distinguish current implementation from historical evaluation records. See [`docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](../docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) for the repository policy on retained historical material. diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index 265efad5..8f97f4e0 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -2,131 +2,110 @@ status: ACTIVE authority: Both owner: DGAF/PDMAL control plane -last_verified: 2026-08-28 +last_verified: 2026-08-29 applies_to_ref: main --- -# DGAF-Framework / PDMAL — Current State +# DGAF / PDMAL — Current State -GitHub is authoritative for implementation and CI; governance decisions must be recorded through the project's governance process. Historical evidence remains scoped to the exact SHA/run/deployment that produced it. This document describes current state without retroactively transferring historical evidence. +GitHub is authoritative for implementation and CI; governance decisions remain governed by the project's formal process. Historical evidence stays scoped to the exact SHA, run, deployment, environment, and artifact that produced it. -> **Current boundary:** `main` is the current documentation/evidence lineage boundary. The experimental verification boundary remains candidate-scoped at `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. E2b is CLOSED/VERIFIED for exact tree `d299dd152fb82d48a066d66a64bf0917e20d6167` via run `33047380487`; the later workflow-binding correction at `ac8ea26…` is a separate verification boundary. M6 is CLOSED/VERIFIED for exact candidate `ac8ea267…` via run `33050398324` and remains scoped to that exact verification workspace/job. P7 is scientifically adopted in substance but formally open pending exact freeze binding; P8 remains open/fail-closed; empirical N = 0; authorization is not granted. +## At a glance -## Authoritative current state +| Boundary | Current state | +|---|---| +| Engineering | **ACTIVE — PR #139** | +| Current `main` | Documentation/evidence lineage; not automatically the experimental apparatus identity | +| Experimental candidate | `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a` | +| PDMAL | **PRE-FREEZE / FAIL-CLOSED** | +| Pilot authorization | **NOT GRANTED** | +| New immutable freeze | **NOT CREATED** | +| Empirical N | **0** | -| Gate / boundary | Status | Current meaning | -|---|---|---| -| Historical implementation freeze | HISTORICAL / SUPERSEDED | `3510b86889cd341f7a7cf9ab684fd37b2fafd758` remains provenance only | -| Current `main` | CURRENT DOCUMENTATION/EVIDENCE LINEAGE | Resolve `main` directly; not apparatus identity | -| Experimental verification boundary | CANDIDATE-SCOPED | `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a` | -| E2b | CLOSED / VERIFIED (historical exact-tree scope) | `d299dd152…`; run `33047380487`; artifact `9636185725`; digest `sha256:723aa9d5a1b60242212a8d7533ccf296de37a36349b4a60f53714bb6898ca1fd` | -| M6 | CLOSED / VERIFIED (candidate exact-tree scope) | `ac8ea267…`; run `33050398324`; retained negative-state artifact independently hash-verified; closure does not authorize execution | -| Current-boundary E2b | OPEN / VERIFICATION REQUIRED | Current E2b evidence must be produced against the exact executing workflow boundary used for freeze admissibility | -| TGL contract | BLOCKED / ADVERSARIAL REVIEW | PR #132 produced a 41-pass / 2-fail regression at the TGL → P-35 boundary; PR #133 is the isolated remediation candidate | -| P7 scientific specification | ADOPTED IN SUBSTANCE / FORMALLY OPEN | Scientific decision resolved; exact freeze binding remains open | -| P8 analysis lock | OPEN / FAIL-CLOSED | Candidate-scoped implementation/configuration and verification remain incomplete | -| P2 formal runtime verification | NOT EXECUTED | Authenticated five-case matrix still required | -| P6a formal CORS verification | NOT EXECUTED | Authenticated CORS matrix still required | -| P-07 co-orchestration sweep | REMEDIATED / OPERATIONALLY CLOSED | Sweep `08670C3FDE59`: deprecated `api/health.py` removed; `app/api/health/route.ts` absent on current `main`; `requirements.txt` retained as intentionally empty/documentary; production deployment for `21f043b7…` reached READY and live `/api/health` returned HTTP 200 with the expected health contract | -| Forman–Ricci lattice helper semantics | OPEN / ISSUE #117 | Unweighted dodecahedral `Ric_F(e) = -2` is constant/zero-variance and must produce `NO_DISCRIMINATING_SIGNAL`, not 30 anomaly flags | -| P-38 source integrity | OPEN / ISSUE #122 | `NDR_AUTOINIT_SUBSTRATE_ADAPTER_P38_v1.md` has a truncated historical tail; history audit confirms the earliest retained version is already truncated | -| New immutable freeze | NOT CREATED | No current candidate has crossed the freeze boundary | -| Pilot authorization | NOT GRANTED | Separate governance transition after required predicates and freeze verification | -| Empirical data | N = 0 | No authorized empirical pilot has been executed | - -## TGL / P-35 adversarial review boundary - -PR #132 is **BLOCKED / DRAFT / UNMERGED**. Its observed 41-pass / 2-fail pre-freeze result is treated as a substantive contract-regression signal. The failure is at the TGL → P-35 seam and includes incompatible constructor/method invocation. The review also identified missing `premise_check_fn` injection, weakened exception containment, incomplete `PASS/WARN/SKIP/ESCALATE/KILL` reduction, ambiguous SKIP semantics, and audit-seal sequencing concerns. - -The required remediation is contract restoration rather than broad architectural refactoring. PR #133 is the isolated remediation candidate. It must restore the established P-35 constructor and `evaluate(..., check_fn=...)` contract, fail-closed exception containment, explicit required/conditional gate semantics, deterministic status reduction, and exact final audit sealing, with regression coverage for the identified failure modes. - -This review does not authorize any experimental action. It does not create a freeze, close P7/P8, establish runtime verification, or increase empirical N. +## Current engineering lane -## E2b provenance boundary +PR #139 is the current DGAF engineering lane. It consolidates governed control-plane work, authority inheritance, bounded execution, deterministic lifecycle behavior, provenance, authorization barriers, and TGL hardening. -Run `33047380487` is retained as exact-tree evidence for `d299dd152fb82d48a066d66a64bf0917e20d6167`. It passed exact checkout/target assertions, source requirements fingerprint verification, hash-pinned installation, exact-tree provenance emission, and evidence retention. Artifact `9636185725` has digest `sha256:723aa9d5a1b60242212a8d7533ccf296de37a36349b4a60f53714bb6898ca1fd`. +Its substantive implementation checkpoint `a728ce3ee8a024646c0971c9d4f392abaa3d691a` completed dedicated control-plane/TGL/adversarial/capability-boundary verification with **41/41 tests passing** in run `33247361730`. Later commits on the PR are documented as documentation, governance, CI, and provenance-hardening changes; the 41/41 result remains scoped to the exact checkpoint. -This closure is not retroactively invalidated. It is scoped to the tree that was actually executed. The subsequent `ac8ea26…` workflow change is a separate verification boundary. +Earlier TGL remediation PRs #132 and #133 are historical remediation records. The current engineering narrative should use PR #139 unless a forensic record specifically requires the earlier history. -## M6 provenance boundary +## Experimental boundary -M6 is CLOSED/VERIFIED for exact candidate/tree `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a` via Governance CI run `33050398324`. Checkout SHA, workflow target SHA, and verifier target SHA matched exactly; the hash-pinned verifier environment completed successfully; machine-readable negative-state evidence was emitted and retained; and the retained artifact digest was independently recomputed as `sha256:dabe2f1909535671e795bb8c1cad0ef0840be4732acebff8f1a340c62b4943b6`. +PDMAL remains separately governed from the engineering track. The current candidate is `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. -The observed negative state included empirical N = 0, pilot authorization not granted, no protocol/freeze created, pilot mode not selected, blinding key absent, zero pilot seed/summary artifacts, and no pilot invocation in the verification job. M6 proves that observed negative state for that exact verification workspace/job; it does not constitute proof of absence elsewhere and does not authorize execution. +No new freeze has been created. Pilot authorization has not been granted. No authorized empirical pilot has been executed; **N = 0**. -## Current verification boundary +Documentation or engineering changes do not rebind the experimental apparatus. A substantive apparatus change requires a new candidate identity and the applicable predicate re-verification. -The corrected Governance CI workflow at `ac8ea26…` binds the target candidate SHA to the executing GitHub workflow SHA. Current E2b evidence must be produced and independently checked against the exact executing boundary before it can support current freeze admissibility. +## Gate board -The current `main` lineage contains subsequent documentation/semantic corrections, including canonical mathematical notation, bounded Hensel/registry claims, historical-audit corrections, AutoInit provenance corrections, and the lattice reproduction notation correction. Those documentation-lineage changes do not retroactively change candidate-scoped verification results and must not be represented as experimental apparatus verification. - -The earlier M6 artifact targeting historical `e6beeb663…` and verifier merge-ref `2516f32…` remains **NON-CLOSING** for the current candidate boundary; that historical artifact is not the basis for the closed M6 state above. - -## P-07 remediation boundary - -Sweep `08670C3FDE59` found three repository/deployment candidates. Cross-connection against current `main` and the production deployment resolved them as follows: +| Gate / control | Status | Meaning | +|---|---|---| +| Historical implementation freeze | HISTORICAL / SUPERSEDED | `3510b868…` remains provenance only | +| E2b | CLOSED / VERIFIED | Exact historical tree `d299dd152…`; run `33047380487` | +| M6 | CLOSED / VERIFIED | Exact candidate `ac8ea267…`; run `33050398324` | +| Current-boundary E2b | OPEN | Verification against the executing workflow boundary remains required where freeze admissibility depends on it | +| TGL contract | ENGINEERING / HARDENING | Current work is in PR #139; earlier #132/#133 records are historical | +| P2 runtime verification | NOT EXECUTED | Authenticated exact deployment matrix required | +| P6a CORS verification | NOT EXECUTED | Authenticated exact deployment matrix required | +| P4 security / blinding | OPEN | Current custody verification required | +| P5 provenance / reproducibility | OPEN | Current execution packet required | +| P6 durable evidence custody | OPEN | Current archive/retrieval/hash proof required | +| P7 scientific specification | ADOPTED IN SUBSTANCE / FORMALLY OPEN | Exact freeze binding required | +| P8 analysis lock | OPEN / FAIL-CLOSED | Candidate-scoped closure required | +| P9 independent verification | NOT EXECUTED | Independent review required | +| New immutable freeze | NOT CREATED | No current candidate has crossed the freeze boundary | +| Pilot authorization | NOT GRANTED | Separate explicit governance transition | +| Empirical data | N = 0 | No authorized pilot execution | -1. `api/health.py` was a deprecated Python stub explicitly directing users to `pages/api/health.ts`. It was removed on commit `21f043b7d9a845b3477c4f3bf4a5a66d7d813e9e`. -2. `app/api/health/route.ts` is absent from the current `main` tree; the operational health handler is `pages/api/health.ts`. -3. `requirements.txt` is retained because the repository documents it as intentionally empty and non-operative for the Next.js API deployment path. +## TGL / P-35 review -The resulting Vercel production deployment was READY and source-bound to the same exact `21f043b7…` commit. The deployed `/api/health` endpoint returned HTTP 200 with `psi_cubic=true`, version `1.8.0`, `phi_star=0.618034`, `psi=1.4655712319`, `t0_axiom_guard=true`, and the five declared adapters. This is operational deployment evidence only; it does not substitute for authenticated P2/P6a execution. +A prior remediation sequence exposed a substantive TGL → P-35 contract regression. The associated **41-pass / 2-fail** result is a diagnostic finding scoped to the historical candidate that produced it; it is not a current system-wide failure rate or efficacy measurement. -The GitHub `Deploy to Vercel + Live Regression` workflow remains unable to perform its own authenticated deployment/live-regression branch because `VERCEL_TOKEN` is not configured. The dedicated P2 workflow separately requires `VERCEL_AUTOMATION_BYPASS_SECRET`. Neither missing credential is treated as a code defect. +The review identified constructor/method compatibility, premise-hook injection, exception containment, deterministic `PASS / WARN / SKIP / ESCALATE / KILL` reduction, required-versus-conditional `SKIP` semantics, and audit-seal sequencing as areas requiring hardening. -## Canonical mathematical notation boundary +See [`governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md`](governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md) for the forensic record and PR #139 for the current engineering lane. -`φ` is the conventional symbol for the Golden Ratio, `(1+√5)/2 ≈ 1.618033989`. +## Verification boundaries -`σ_{p,q}` denotes the Spinadel metallic-means family, the positive solution of `x² - px - q = 0`; `σ_n = σ_{n,1}` for the ordinary sequence. `σ_{2,1}` is silver and `σ_{3,1}` is bronze. +### E2b -`ρ` denotes the mathematical plastic number, `≈1.3247179572447454`, the unique real root of `x³ - x - 1 = 0`. `P` is an attested alternative notation. `ρP` is not the canonical mathematical notation. +Run `33047380487` remains exact-tree evidence for `d299dd152fb82d48a066d66a64bf0917e20d6167`. Its retained artifact is scoped to that execution. Later workflow or source changes require their own verification where applicable. -`pP` / **Platinum Mean** is intentional DGAF-specific notation for the regular-hendecagon unit-side circumradius, `1/(2 sin(π/11)) ≈ 1.774732842`. It is not a standard member of the quadratic metallic-means family and must not be substituted for `ρ` in plastic-number mathematics. +### M6 -The authoritative notation policy is `docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`. Historical `ρP` references are retained only as provenance/supersession evidence and must not be treated as current mathematical authority. +Run `33050398324` remains candidate-scoped evidence for `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. Its closure demonstrates the observed negative-state controls for that exact verification workspace/job; it does not authorize execution or prove absence outside that scope. -## Forman–Ricci evidence boundary +## Deployment boundary -For the unweighted regular dodecahedral topology, Forman–Ricci curvature is `Ric_F(e) = -2` for every edge. This is a constant metric with zero variance and therefore **NO_DISCRIMINATING_SIGNAL**. Issue #117 remains open until the helper's output semantics are corrected and regression-tested. Weighted Forman–Ricci remains separately governed as a falsification track; no validation claim follows from the current single-configuration computation. +A previously identified READY production deployment remains supporting operational evidence. Formal P2 and P6a claims require authenticated execution against the exact deployment identity. Deployment readiness and a live health response do not substitute for those verification predicates. -## P-38 source-integrity boundary +## Mathematical notation -Issue #122 tracks the incomplete P-38 substrate-study tail. A Git history audit on 2026-08-28 confirmed that the earliest retained P-38 commit (`8807dc5c…`, 2026-06-13) already ends at the same `Bit-identical a_n replay va...` boundary. The later correction commit therefore did not remove recoverable source text from the retained history; no authoritative remainder has been reconstructed. The issue remains open pending a provenance-controlled external or otherwise authoritative source. This is documentation/source-integrity remediation only and does not advance experimental gates. +`φ` denotes the Golden Ratio, `(1+√5)/2 ≈ 1.618033989`. -## Expert Panel — 2026-08-28 +`ρ` denotes the mathematical plastic number, approximately `1.3247179572447454`, the unique real root of `x³ - x - 1 = 0`. -The **Ecosystem Expert Panel** is the cross-agent governance review mechanism defined in the Notion operating charter. Its role specifications are maintained in the Notion Agent Registry; GitHub remains implementation/evidence truth. The panel disposition is **PROCEED, FAIL-CLOSED**. +`pP` / **Platinum Mean** is intentional DGAF-specific notation for `1/(2 sin(π/11)) ≈ 1.774732842`. It is not presented as a universal mathematical symbol or as a member of the quadratic metallic-means family. It must not replace `ρ` in plastic-number convergence mathematics. -Panel seats: -- **Amethyst:** meta-orchestration, normative governance, dependency/closure ledger. -- **COLLEEN:** continuity, archive, provenance, durable state, routing integrity. -- **Professor Prodigy:** formalization/proof and mathematical claim verification; non-orchestrating. -- **Apogee:** independent evidence review, integrity scoring, and P9 preparation. -- **DemiJoule:** constraint/resource and governance-boundary review. -- **Sentinel-Phi:** strategic security, risk containment, and fail-closed monitoring. -- **Herald:** evidence/public-surface synchronization and classification hygiene. -- **Reciprocity:** reciprocal-mathematics and adversarial asymmetry review. +See [`governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md) for the authoritative notation policy. -### Panel execution decision +## Other tracked boundaries -1. Continue all non-blocked engineering, documentation, provenance, analysis, and research-hygiene work in parallel. -2. Keep P2/P6a behind their protected credential/dispatch requirements and exact candidate/deployment identity. -3. Treat M6 as closed only for its exact `ac8ea267…` candidate verification scope; do not transfer it to later `main` documentation lineage. -4. Keep E2b scoped to its exact executed tree; later workflow changes require their own evidence where applicable. -5. Advance P7 exact binding, P8 candidate-scoped closure, and independent P9 preparation. -6. Create a new immutable freeze only after all applicable predicates pass. -7. Authorization remains a separate explicit transition; only then may the blinded pilot execute. +- **Issue #117:** unweighted dodecahedral Forman–Ricci curvature is constant (`Ric_F(e) = -2`) and therefore represents `NO_DISCRIMINATING_SIGNAL`; implementation/output semantics remain open. +- **Issue #122:** P-38 source-integrity record has an incomplete historical tail; provenance-controlled reconstruction remains open. +- **Issue #137:** deployment/source-provenance gate remains part of the engineering closure path. -### Hard panel constraints +## Expert review -No freeze, authorization, unblinding, or empirical-N increase may be inferred from CI success, deployment readiness, health checks, synthetic fixtures, historical evidence, or narrative state alone. +The cross-agent expert review disposition remains **PROCEED, FAIL-CLOSED**. Its purpose is to support evidence review, risk containment, provenance, mathematical review, and governance coordination; it does not create technical or experimental authority by itself. ## Authorization boundary -Required before authorization include authenticated P2 and P6a execution on the same deployment identity; blinding custody and unblinding verification; durable archive/retrieval/hash evidence; environment and reproducibility fingerprints; formal P7 exact binding; frozen baseline/negative-control definitions; P8 closure; independent P9 verification; a new immutable freeze; and an explicit authorization decision. +Authorization requires completion of the applicable runtime, security/blinding, provenance, durable-custody, P7, P8, and independent-verification requirements; creation and verification of a new immutable freeze; and an explicit authorization decision. -**No empirical pilot execution is authorized. Empirical N remains 0. Authorization remains NOT GRANTED.** +**Current conclusion: engineering is active. PDMAL remains PRE-FREEZE / FAIL-CLOSED / NOT AUTHORIZED / N = 0.** -## Related adversarial-review record +## Documentation controls -See `docs/governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md` for the complete TGL/P-35 contract findings, state-machine analysis, audit/provenance findings, CI/CD identity risks, remediation boundary, and required regression coverage. +Public and project-facing documentation follows [`governance/DOCUMENTATION_STYLE_GUIDE.md`](governance/DOCUMENTATION_STYLE_GUIDE.md) and [`governance/PUBLIC_SURFACE_QA_STANDARD.md`](governance/PUBLIC_SURFACE_QA_STANDARD.md). Detailed evidence and forensic history belong in their canonical lower-level records rather than being duplicated in this summary. diff --git a/docs/HISTORICAL_RECORDS_INDEX.md b/docs/HISTORICAL_RECORDS_INDEX.md new file mode 100644 index 00000000..f01ed7f5 --- /dev/null +++ b/docs/HISTORICAL_RECORDS_INDEX.md @@ -0,0 +1,32 @@ +# Historical Records Index + +DGAF retains historical material because reproducibility and provenance sometimes require readers to understand what was previously implemented, proposed, measured, or believed. Historical availability is not equivalent to current authority. + +## How to use the repository record + +Start with the current authority for the question you are asking: + +- **Current project and experimental status:** [`CURRENT_STATE.md`](./CURRENT_STATE.md) and [`PROJECT_STATUS.md`](./PROJECT_STATUS.md) +- **Evidence and claim scope:** [`evidence/`](./evidence/) and the [`Epistemic Supersession Register`](./EPISTEMIC_SUPERSESSION_REGISTER.md) +- **Technical implementation:** [`../README.technical.md`](../README.technical.md) and implementation-local documentation +- **Governance model:** [`../README.governance.md`](../README.governance.md) + +Then consult historical material when reconstruction, provenance, or comparison requires it. + +## Status conventions + +Historical records may contain terminology, metrics, architecture, deadlines, repository inventories, or external-framework interpretations that are no longer current. They should be read in their original context and not silently promoted into a present-tense claim. + +The repository uses the following practical distinctions: + +- **Current:** authoritative for its stated scope. +- **Historical:** retained record of an earlier state or claim. +- **Superseded:** replaced for current use by an identified authority. +- **Reference only:** background material that is not a current control source. +- **Draft:** incomplete and not authoritative. + +## Preservation principle + +**Preserve the record; clarify the status; route readers to the current authority.** + +For the governing policy, see [`governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md`](./governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md). diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 836c219f..2f20da67 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,107 +1,101 @@ -# DGAF/PDMAL Project Status +# DGAF / PDMAL Project Status -**Status date:** 2026-08-28 +**Status date:** 2026-08-29 **Repository:** `ndrorchestration/DGAF-Framework` -**Current main:** active documentation/evidence lineage; not experimental apparatus identity +**Engineering lane:** PR #139 — governed control-plane integration and TGL hardening **Experimental verification boundary:** `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a` **Pilot status:** PRE-FREEZE; authorization not granted **Empirical N:** 0 ## Executive state -The repository is in structured pre-freeze closure. `3510b86889cd341f7a7cf9ab684fd37b2fafd758` is the historical superseded implementation freeze. E2b is CLOSED/VERIFIED for exact tree `d299dd152fb82d48a066d66a64bf0917e20d6167` via run `33047380487`; the retained artifact is `9636185725` with digest `sha256:723aa9d5a1b60242212a8d7533ccf296de37a36349b4a60f53714bb6898ca1fd`. +DGAF is actively advancing its governed control-plane engineering work. The current engineering lane is PR #139. Its substantive implementation checkpoint `a728ce3ee8a024646c0971c9d4f392abaa3d691a` completed dedicated control-plane/TGL/adversarial/capability-boundary verification with **41/41 tests passing** in run `33247361730`. Later PR #139 commits are documented as documentation, governance, CI, and provenance-hardening changes; the 41/41 result remains scoped to that exact checkpoint. -Repository `main` is an active documentation/evidence lineage; resolve the current branch tip from Git rather than treating a documentation commit as the experimental apparatus candidate. The current experimental verification boundary remains candidate-scoped at `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. +The PDMAL research track is separately governed. It remains **PRE-FREEZE / FAIL-CLOSED / NOT AUTHORIZED / N=0**. The current candidate boundary is `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`; no new immutable freeze exists and no pilot has been authorized or executed. -The corrected Governance CI boundary at `ac8ea26…` binds the candidate target to the executing workflow SHA. E2b current-boundary verification remains required where a current freeze decision depends on the executing workflow boundary. M6 is separately CLOSED / VERIFIED for the exact candidate `ac8ea267…` via run `33050398324`; that closure is scoped to the exact verification workspace/job and does not authorize execution. +Historical implementation freezes and verification runs remain valid only for the exact source, environment, deployment, workflow, and artifact that produced them. They are not automatically transferable to the current candidate or later documentation lineage. -The documentation correction pass canonicalized the remaining named Platinum/Plastic notation surfaces and quarantined several historical overclaiming records. Documentation-quality debt remains tracked separately from experimental validity. +## Current gate board -P7 is scientifically adopted in substance, but exact cryptographic binding to the eventual freeze apparatus remains OPEN. P8 remains OPEN/FAIL-CLOSED. P2/P6a remain pending authenticated execution. P4/P5/P6 and P9 remain open. No new freeze exists, no pilot has been authorized or executed, and N remains 0. - -## Gate board - -| Gate / control | Status | Evidence / state | +| Area | Status | Interpretation | |---|---|---| -| Historical freeze | HISTORICAL / SUPERSEDED | `3510b868…` | -| Current repository main | CURRENT LINEAGE | Resolve `main` directly; documentation/evidence lineage, not apparatus identity | +| Governed control-plane engineering | ACTIVE | PR #139 is the current engineering lane | +| TGL contract hardening | ACTIVE | Hardened contract work is integrated in the current engineering candidate; exact-head CI remains authoritative | +| Current `main` | CURRENT LINEAGE | Documentation/evidence lineage; not automatically the experimental apparatus identity | | Experimental verification boundary | CANDIDATE-SCOPED | `ac8ea267…` | -| E2b | CLOSED / VERIFIED (historical exact-tree scope) | `d299dd1…`, run `33047380487`, artifact `9636185725` | -| Current-boundary E2b | OPEN / VERIFICATION REQUIRED | Execute/retain evidence for the exact workflow boundary used for the eventual freeze decision | -| M6 | CLOSED / VERIFIED (candidate exact-tree scope) | `ac8ea267…`; run `33050398324`; retained negative-state artifact independently hash-verified | -| Runtime characterization | CLOSED FOR CHARACTERIZATION | Historical/non-empirical characterization only | -| Execution contract | PARTIAL / TGL BLOCKED | Authenticated exact-current-tree P2 evidence pending; TGL/P-35 contract regression under remediation | -| Artifact contract | PARTIAL | Corrective controls present; current candidate execution evidence pending | -| Security / blinding | PARTIAL | Fresh operational custody verification pending | -| Topology provenance | PARTIAL | Exact current-candidate recomputation pending | -| Provenance / reproducibility | PARTIAL | Current execution packet pending | -| Durable retention | OPEN | Current archive/retrieval/hash proof pending | -| Primary contrast | SELECTED / P7 ADOPTED IN SUBSTANCE | Full `dgaf` vs `null`, FFCR primary endpoint, paired-seed analysis | -| P7 exact binding | OPEN | Final freeze identity binding remains required | -| Analysis lock | OPEN / FAIL-CLOSED | Candidate-scoped closure pending | -| Independent verification | NOT EXECUTED | P9 remains pending | -| TGL contract review | BLOCKED / DRAFT REMEDIATION | PR #132 41-pass / 2-fail regression; PR #133 is isolated remediation candidate | -| Forman–Ricci lattice helper semantics | OPEN / ISSUE #117 | Unweighted dodecahedral `Ric_F(e) = -2` is constant/zero-variance and must produce `NO_DISCRIMINATING_SIGNAL`, not 30 anomaly flags | -| P-38 source integrity | OPEN / ISSUE #122 | `NDR_AUTOINIT_SUBSTRATE_ADAPTER_P38_v1.md` has a truncated historical tail; history audit confirms the earliest retained version is already truncated | -| New freeze | NOT CREATED | Historical freeze cannot be reused | -| Pilot authorization | NOT GRANTED | Separate governance decision | -| Empirical data | ZERO | No authorized pilot execution | -| Documentation quality | OPEN DEBT | Current Doc Lint findings remain separate from efficacy | +| E2b | CLOSED / VERIFIED (exact historical tree) | `d299dd152…`; run `33047380487` | +| M6 | CLOSED / VERIFIED (exact candidate scope) | `ac8ea267…`; run `33050398324` | +| Current-boundary E2b | OPEN | Exact executing workflow boundary still requires verification for freeze admissibility | +| P2 runtime verification | NOT EXECUTED | Authenticated exact deployment matrix required | +| P6a CORS verification | NOT EXECUTED | Authenticated exact deployment matrix required | +| P4 security / blinding | OPEN | Current operational custody verification required | +| P5 provenance / reproducibility | OPEN | Current execution packet required | +| P6 durable evidence custody | OPEN | Current archive/retrieval/hash proof required | +| P7 scientific specification | ADOPTED IN SUBSTANCE / FORMALLY OPEN | Exact freeze binding remains required | +| P8 analysis lock | OPEN / FAIL-CLOSED | Candidate-scoped closure remains required | +| P9 independent verification | NOT EXECUTED | Independent review remains required | +| New immutable freeze | NOT CREATED | No current candidate has crossed the freeze boundary | +| Pilot authorization | NOT GRANTED | Separate explicit governance transition | +| Empirical data | N = 0 | No authorized pilot execution | + +## TGL / P-35 review -## TGL / P-35 adversarial review +A prior remediation sequence exposed a substantive TGL → P-35 contract regression. The associated **41-pass / 2-fail** result remains a diagnostic finding scoped to that historical candidate; it is not a current system-wide failure rate or efficacy measurement. -The 41-pass / 2-fail result associated with PR #132 is a concrete regression signal at the TGL → P-35 integration boundary. The observed failure is not being treated as a transient test issue. The review identified constructor/method incompatibility, missing premise-hook injection, weakened exception containment, incomplete `PASS/WARN/SKIP/ESCALATE/KILL` reduction, ambiguous conditional versus unwired `SKIP`, and audit-seal sequencing concerns. +The review identified contract incompatibility, premise-hook wiring, exception containment, deterministic `PASS / WARN / SKIP / ESCALATE / KILL` reduction, required-versus-conditional `SKIP` semantics, and audit-seal sequencing as areas requiring hardening. PRs #132 and #133 are historical remediation records. The current engineering lane is PR #139. -The selected remediation is intentionally minimal: restore the established P-35 API and TGL fail-closed behavior, make required/conditional gate semantics explicit, implement deterministic status reduction, make the final seal correspond to the authoritative returned audit state, and expand regression coverage. Broad architectural refactoring is out of scope for PR #132/#133. +See [`docs/governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md`](governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md) for the detailed forensic record. -PR #132 remains blocked/draft. PR #133 is the isolated remediation candidate and must obtain its own exact-head validation. Neither PR changes the experimental apparatus identity, creates a freeze, closes P7/P8, grants authorization, or increases empirical N. +## Evidence boundaries -The detailed diagnostic record is `docs/governance/TGL_PR132_ADVERSARIAL_REVIEW_2026-08-28.md`. +The repository uses the following evidence vocabulary: -## Current deployment boundary +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` -The previously identified READY deployment remains supporting deployment evidence. Formal P2 and P6a workflows require authenticated execution against the exact deployment identity and must not be inferred from readiness alone. +A result is interpreted at the scope at which it was produced. A component test establishes the tested component result; it does not establish repository-wide validation. A deployment establishes deployment state; it does not establish experimental authorization or efficacy. A historical result does not become current evidence merely because the underlying concept remains relevant. -## Canonical mathematical notation +## Historical verification retained -`φ` is the conventional symbol for the Golden Ratio, `(1+√5)/2 ≈ 1.618033989`. +- E2b run `33047380487` remains exact-tree evidence for `d299dd152fb82d48a066d66a64bf0917e20d6167`. +- M6 run `33050398324` remains candidate-scoped evidence for `ac8ea267a9f0d995626cf9c3eaf9e6b008b5dc8a`. +- Historical freeze `3510b86889cd341f7a7cf9ab684fd37b2fafd758` remains provenance only. -`σ_{p,q}` denotes the Spinadel metallic-means family, the positive solution of `x² - px - q = 0`. For the ordinary sequence, `σ_n = σ_{n,1}`; `σ_{2,1}` is silver and `σ_{3,1}` is bronze. +These records are not invalidated by later documentation changes, but neither are they promoted to evidence for a later candidate without explicit re-verification. -`ρ` denotes the mathematical plastic number, `≈1.3247179572447454`, the unique real root of `x³ - x - 1 = 0`. `P` is an attested alternative notation. `ρP` is not the canonical mathematical notation. +## Research boundaries -`pP` / **Platinum Mean** is intentional DGAF-specific notation for the regular-hendecagon unit-side circumradius, `1/(2 sin(π/11)) ≈ 1.774732842`. It is not a standard member of the quadratic metallic-means family and must not be substituted for `ρ` in plastic-number mathematics. +### PDMAL -The authoritative notation policy is `docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`. +PDMAL is an experimental research track. Its topology and mathematical structures remain research objects until the protocol, candidate identity, verification boundary, and evidence establish stronger claims. In particular, topology alone does not establish a complete Byzantine Fault Tolerance protocol or another externally defined property. -## Forman–Ricci evidence boundary +### Mathematical notation -The unweighted dodecahedral topology produces `Ric_F(e) = -2` for every edge. The resulting zero variance is a **NO_DISCRIMINATING_SIGNAL** condition; it is not anomaly detection and must not be represented as 30 anomalies. Issue #117 tracks the implementation/output semantics correction. Weighted Forman–Ricci remains a falsification track under #72; the existing rank-based top-3 success is a single computed configuration, not general validation. +`φ` denotes the Golden Ratio. `ρ` denotes the mathematical plastic number. `pP` / **Platinum Mean** is intentional DGAF-specific notation for `1/(2 sin(π/11)) ≈ 1.774732842`; it is not presented as a universal mathematical symbol or as a member of the quadratic metallic-means family. -## P-38 source-integrity boundary +See [`docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md) for the canonical notation policy. -Issue #122 tracks the incomplete P-38 substrate-study tail. A Git history audit on 2026-08-28 confirmed that the earliest retained P-38 commit (`8807dc5c…`, 2026-06-13) already ends at the same `Bit-identical a_n replay va...` boundary. The later correction commit therefore did not remove recoverable source text from the retained history; no authoritative remainder has been reconstructed. The issue remains open pending a provenance-controlled external or otherwise authoritative source. This is documentation/source-integrity remediation only and does not advance experimental gates. +## Operational issues -## Public-surface rule +- **Issue #117:** unweighted dodecahedral Forman–Ricci output is constant (`Ric_F(e) = -2`) and therefore represents `NO_DISCRIMINATING_SIGNAL`; implementation/output semantics remain open. +- **Issue #122:** P-38 source-integrity record has an incomplete historical tail; provenance-controlled reconstruction remains open. +- **Issue #137:** deployment/source-provenance gate remains part of the current engineering closure path. -GitHub-visible claims must distinguish implementation, computation, verification, attestation, validation, hypothesis, and historical context. Internal Notion/control records are not default public navigation targets. Public landing surfaces should resolve to repository-local documentation or intentionally designated public resources. Deployment readiness, unit/CI success, a single research trial, or historical certification must not be presented as validated capability without the required evidence scope. +## Public documentation rule -## Historical evidence boundary +Public documentation should explain the project before exposing internal process. High-level surfaces summarize and route; technical, research, evidence, and historical records preserve the detail required for reproducibility and auditability. -Historical evidence remains scoped to the exact application source, deployment, workflow run, and artifact that produced it. The E2b run `33047380487` proves `d299dd1…`; it does not automatically certify `ac8ea26…` or any later documentation lineage. M6 is a separate closed candidate-scoped verification at `ac8ea267…` via run `33050398324`; older M6 evidence targeting `e6beeb…` and verifier merge-ref `2516f32…` remains non-closing for the current candidate boundary. +See [`docs/governance/DOCUMENTATION_STYLE_GUIDE.md`](governance/DOCUMENTATION_STYLE_GUIDE.md) and [`docs/governance/PUBLIC_SURFACE_QA_STANDARD.md`](governance/PUBLIC_SURFACE_QA_STANDARD.md). -## Required closure sequence +## Required closure path -1. Resolve the TGL/P-35 contract blocker through the isolated remediation candidate and exact-head validation. -2. Execute/retain the current-boundary E2b verification needed for freeze admissibility against the exact executing workflow SHA. -3. Independently inspect exact SHA, scope, integrity, and negative-state claims; M6 closure is already recorded for candidate `ac8ea267…`. -4. Execute authenticated P2 and P6a against the exact deployment identity. -5. Complete P4, P5, and P6 evidence/custody. -6. Complete formal P7 exact binding. -7. Reconcile and close P8 only from candidate-scoped evidence. -8. Execute P9 independent verification. -9. Create and independently verify a new immutable freeze. -10. Obtain explicit pilot authorization. -11. Only then execute the authorized blinded pilot. +1. Complete exact-head validation of the current engineering/TGL state. +2. Complete current-boundary E2b verification where required for freeze admissibility. +3. Complete authenticated P2/P6a deployment verification. +4. Complete P4/P5/P6 evidence and custody requirements. +5. Complete P7 exact freeze binding and P8 closure. +6. Execute P9 independent verification. +7. Create and independently verify a new immutable freeze. +8. Obtain explicit pilot authorization. +9. Only then execute the authorized blinded pilot. -**Empirical validity is NOT ESTABLISHED. Pilot authorization is NOT GRANTED. N = 0.** +**Current conclusion: engineering is active; the PDMAL experiment remains PRE-FREEZE / FAIL-CLOSED / NOT AUTHORIZED / N = 0.** diff --git a/docs/TEAM_WIKI.md b/docs/TEAM_WIKI.md index 412a97d5..f33c3b06 100644 --- a/docs/TEAM_WIKI.md +++ b/docs/TEAM_WIKI.md @@ -1,174 +1,86 @@ -# DGAF Team Wiki +# DGAF Collaboration and Architecture Guide -> **Version:** 1.1.0 | **Authority:** COLLEEN (Institutional Memory / Chief Librarian) | **Last updated:** 2026-06-27 (S070-r5) +> **Status:** reference guide for project collaboration and historical architecture context. +> **Current authority:** use the repository's current-state, agent-authority, and governance documents for active decisions. -This is the team-facing reference for the DGAF Framework. It covers agent roles, governance authority, onboarding, and pattern conventions. For technical architecture, see `README.technical.md`. For governance protocol, see `README.governance.md`. +This guide explains how DGAF has organized collaboration, agent roles, and pattern-oriented development. Some terminology and workflow descriptions originated in earlier phases of the project and are retained for context; they do not supersede current repository authorities. ---- - -## 1. What Is DGAF? - -DGAF (**Deterministic Governance for Agentic Frameworks**) is a governance-aligned multi-agent reasoning architecture built on three pillars: - -> ✅ **FLAG-13 CLOSED — Njineer ratified 2026-06-27 18:16 EDT** -> Canonical expansion: **Deterministic Governance for Agentic Frameworks** -> Previous conflicting entry in this file ("Dynamic Governance Agentic Formation Architecture") is hereby superseded. -> Source of truth: `docs/NDR_INTERNAL_VOCABULARY_MASTER.md` Section 2 (DGAF entry). - -1. **Triadic / Constitutional Cognition** — legislative-judicial-executive closed loop for agent decision-making -2. **Co-orchestration** — Amethyst (QA) × COLLEEN (Evaluation) as persistent co-authors, not process steps -3. **Pattern-first implementation** — all improvements sourced from a curated, versioned pattern registry before execution - ---- - -## 2. Agent Roster - -| Agent | Role | Lens | L-Level | Authority | -|---|---|---|---|---| -| **Amethyst** | Meta-orchestration lead, QA | QA / coherence | L5 | Primary host; inherits all deprecated Lavender roles | -| **COLLEEN** | Institutional memory, archivist, chief librarian | Evaluation / archive | L5 | Pattern registry authority; 1-1-1-1 alignment gate | -| **Sentinel-Phi** | Safety supervisor, tool classifier | Governance / safety | L4 | Enforces effect classes, HITL gates, tool reversibility | -| **Herald** | Trace sink, audit router | Observability | L3 | Routes all trace events to JSONL + n8n webhook | -| **Apogee** | Quality verifier, Apogee Lens | Quality assurance | L4 | Final verifier for portfolio-grade output; S-Tier gate | -| **DemiJoule** | Runtime supervisor, RAG, ethics | Safety / RAG | L4 | Closes hallucination gap; ethics/safety containment | -| **Reson** | Systems architect | Architecture | L3 | Sub-task execution under Amethyst’s architect role | -| **Agent Sonar** | Sonar taxonomy role | Per taxonomy | L3 | Kept in current taxonomy role | -| **Professor Prodigy, Reciprocity, Herald** | Sub-agentic layers | Epistemic | L2–3 | Intentionally placed; require epistemic honesty definition | - -> **Deprecated:** Lavender — all roles, functions, files, and errata inherited by Amethyst. - ---- - -## 3. Governance Authority Map - -``` -┌─────────────────────────────────────────────────┐ -│ USER │ ← Highest authority -└────────────────────┬────────────────────────┘ - │ -┌────────────────────▼────────────────────────┐ -│ AMETHYST (Prime/Host) │ ← QA lens, meta-orchestration -│ + APOGEE (Quality Verifier) │ ← S-Tier gate -└───────┬────────────────────┬────────────────────┘ - │ │ -┌───────▼──────┐ ┌────────▼────────────────┐ -│ COLLEEN │ │ SENTINEL-PHI │ -│ (Archive / │ │ (Safety / Tool Classifier) │ -│ Evaluate) │ └────────────────────────┘ -└───────┬──────┘ - │ -┌───────▼──────────────────────────────────┐ -│ DEMIJOLE · HERALD · RESON · SONAR · sub-agents │ -└──────────────────────────────────────────────────┘ -``` - ---- - -## 4. Core Workflows +## DGAF today -### 4.1 Session Bootstrap +**DGAF — Dynamic Governance Agentic Formation** is a research and implementation framework for agent orchestration, evaluation, provenance, and governance controls. -1. Read `BOOTSTRAP.md` → confirm workspace identity -2. Read `SESSION_ANCHOR.md` → confirm last state -3. Read `CO_ORCH_QUEUE.md` → confirm active OPP cycle -4. Read `registry/PATTERN_REGISTRY_v2.md` → confirm active patterns -5. Proceed with task +The project has evolved through multiple naming and architecture phases. When older records use different expansions or taxonomy, treat those records according to the [Legacy Documentation Status Policy](governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) rather than silently reinterpreting them. -### 4.2 Pattern-First Implementation +For the public overview, see [`README.md`](../README.md). For current status, see [`CURRENT_STATE.md`](CURRENT_STATE.md). -1. COLLEEN detects improvement opportunity (OPP) -2. COLLEEN sources best-practice pattern (adopt / customize / compose) -3. Pattern registered in `PATTERN_REGISTRY_v2.md` with ID -4. Amethyst implements against registered pattern -5. Apogee Lens QA review -6. Commit with pattern ID in message +## Collaboration model -### 4.3 Co-Orchestration Loop +DGAF uses named agent roles as **architectural and workflow abstractions**. A role may contribute a particular analytical lens, implementation responsibility, or control function, but a role name does not itself create authority or establish autonomous capability. -- COLLEEN runs **detect + audit** pass (Librarian/Auditor roles) -- Amethyst runs **implement + commit** pass (QA/Architect roles) -- Queue is append-only; completed entries archived, never deleted -- New patterns discovered during implementation proposed back as COMPOSE entries +Current authority boundaries are defined in: -### 4.4 Saga + Recovery (New — 2026-06-26) +- [`agents/AGENT_AUTHORITY_INVARIANT.md`](agents/AGENT_AUTHORITY_INVARIANT.md) +- [`agents/AGENT_AUTHORITY_MATRIX.md`](agents/AGENT_AUTHORITY_MATRIX.md) +- [`agents/LAYER_0_CONSTITUTION.md`](agents/LAYER_0_CONSTITUTION.md) -- Every multi-step workflow is a Saga with explicit compensators -- Irreversible actions require HITL gate before commit -- Checkpoints per super-step; append-only effect log per run -- Circuit breakers: semantic (3 schema failures) + budget (200k tokens / 50 steps) -- See `patterns/P-SAGA-001_*.md`, `patterns/P-CB-001_*.md` +Human authority remains explicit where repository controls require approval. ---- +## Role families -## 5. Pattern Naming Convention +The project has used role families including: -``` -P-{DOMAIN}-{SEQ}_{CamelCaseName}.md +| Role family | Typical function | +|---|---| +| Orchestration | task coordination and decomposition | +| Evaluation | quality, coherence, and evidence review | +| Governance and safety | control-boundary and failure review | +| Provenance and observability | trace, audit, and record handling | +| Research and formalism | mathematical, experimental, and specification review | +| Architecture | system and interface design | -Examples: - P-SAGA-001_StochasticDeterministicSagaBoundary.md - P-TX-001_TransactionalToolBoundaryAtomix.md - P-CB-001_CircuitBreakersHITL.md - P-07_TriumvirateSweepLoop.md -``` +Specific agent names and historical assignments should be interpreted through their current contracts. The authoritative agent matrix takes precedence over this overview. -All patterns registered in `registry/PATTERN_REGISTRY_v2.md` before use. +## Pattern-oriented development ---- +DGAF's pattern work is intended to make reusable design decisions easier to identify, compare, and trace. A pattern reference is a design artifact, not evidence that every implementation using the pattern is effective. -## 6. Logging & Documentation Requirements +When adding or changing a pattern: -Every session MUST produce: +1. identify the problem and the scope of the proposed pattern; +2. distinguish an adopted external pattern from a project-specific composition or hypothesis; +3. record provenance and relationships where appropriate; +4. connect implementation and tests to the applicable contract; +5. avoid promoting a pattern to a broader claim without supporting evidence. -| Artifact | Location | Responsible | -|---|---|---| -| Session sweep log | `SWEEP_LOG/SWEEP_{date}_{title}.md` | Amethyst | -| Changelog entry | `CHANGELOG.md` | Amethyst | -| SESSION_ANCHOR update | `SESSION_ANCHOR.md` | Amethyst | -| CO_ORCH_QUEUE update | `CO_ORCH_QUEUE.md` | COLLEEN | -| Pattern registry update (if new patterns) | `registry/PATTERN_REGISTRY_v2.md` | COLLEEN | -| GitHub commit | `main` branch | Amethyst | +See the pattern registry and current Pattern Commons documentation for canonical terminology and cross-repository boundaries. ---- +## Workflow guidance -## 7. Open R&D Items +Use the simplest workflow that fits the task. For substantive changes: -See `docs/RD_GAPS.md` for the living R&D gap log. +1. identify the current authoritative specification or issue; +2. make the implementation or documentation change; +3. run the applicable validation; +4. record evidence at the correct scope; +5. update current documentation when the change affects project state; +6. preserve historical records rather than rewriting their provenance. -Top items as of 2026-06-27: +Experimental workflows have additional freeze, authorization, and evidence requirements defined by their protocols. -- 22% fluent hallucination gap → DemiJoule RAG closure (Phase 3B complete; needs production wiring) -- RAG collection taxonomy design → 6-8 governance-bounded collections -- Saga harness end-to-end fault injection test -- HITL durable queue production deployment -- Needle/RAG platform integration with COLLEEN archive +## Terminology ---- +Terminology evolves. Current canonical definitions are maintained in the repository's terminology, governance, and mathematical-notation policies. Historical glossary entries may remain useful search leads but should not be treated as current authority merely because they appear in an older wiki. -## 8. Glossary +## Related documentation -| Term | Definition | -|---|---| -| DGAF | **Deterministic Governance for Agentic Frameworks** ✅ CANONICAL — Njineer ratified 2026-06-27 (FLAG-13 CLOSED) | -| PDMAL-φ | **Phi-Driven Multi-Agent Lattice** — PRIMARY canonical variant                                *\* See PDMAL note below* | -| PDMAL-D | **Phi-Dodecahedral Multi-Agent Lattice** — VARIANT canonical form *\* See PDMAL note below* | -| OPP | Improvement opportunity in the CO_ORCH_QUEUE | -| NDR | Named Design Rule / Pattern | -| HITL | Human-in-the-Loop | -| PPTL | Procluding Premise Triadic Loop | -| pptl | Phi-pentagon test layer (lowercase — distinct from PPTL) | -| AOGA | Agent Orchestration Governance Architecture | -| AXIS | Agent X-axis Invariant Spectrum — sovereign governance metric (CANONICAL, Njineer-ratified) | -| NDR-HDFS | NDR Hierarchical Documentation Format Standard | -| S-Tier | Highest quality designation; requires Apogee Lens approval | -| ACRFence | Atomic checkpoint + restore with effect fence semantics | -| Atomix | Transactional tool boundary pattern (stochastic-deterministic boundary) | -| Coherent Agency | Recast of governance/memory/ethics as subsystems of continuity-preserving agency | -| phiknightverticalcorridor | Variant name for the **Yggdrasil Vertical Hybridization Corridor** — Vercel project linked to cross-repo governance mesh vertical hybridization layer            ✅ FLAG-11 CLOSED · Njineer ratified 2026-06-27 | - -> **PDMAL correction note (S070-r3 — Njineer direct):** The legacy expansion “Policy-Driven Multi-Agent Layer” is **SUPERSEDED**. The canonical forms are PDMAL-φ (Phi-Driven Multi-Agent Lattice, primary) and PDMAL-D (Phi-Dodecahedral Multi-Agent Lattice, structural variant). Any reference to “Policy-Driven” in DGAF documentation is a BLG — trigger P-01. +- [Public project overview](../README.md) +- [Technical reference](../README.technical.md) +- [Governance reference](../README.governance.md) +- [Current project state](CURRENT_STATE.md) +- [Project status](PROJECT_STATUS.md) +- [Agent authority matrix](agents/AGENT_AUTHORITY_MATRIX.md) +- [Legacy documentation status policy](governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) --- -*DGAF Team Wiki · v1.1.0 · S070-r5 · Amethyst × COLLEEN · 2026-06-27* -*v1.1.0 changes: FLAG-13 CLOSED (DGAF expansion → Deterministic Governance for Agentic Frameworks); FLAG-11 CLOSED (phiknightverticalcorridor → Yggdrasil Vertical Hybridization Corridor); PDMAL correction cascade applied (Policy-Driven SUPERSEDED); full glossary backfilled with S070 canonical terms* +*This guide is intentionally descriptive rather than a promotion or certification record. For active operational decisions, follow the current authoritative documents.* diff --git a/docs/governance/DOCUMENTATION_STYLE_GUIDE.md b/docs/governance/DOCUMENTATION_STYLE_GUIDE.md new file mode 100644 index 00000000..94d1c6c6 --- /dev/null +++ b/docs/governance/DOCUMENTATION_STYLE_GUIDE.md @@ -0,0 +1,147 @@ +# DGAF Documentation Style Guide + +**Status:** ACTIVE +**Applies to:** GitHub-visible documentation, project records, specifications, research notes, and governance artifacts +**Principle:** Preserve rigor without making every document read like an audit log. + +## 1. Write for the document's job + +Every document should have one primary job and a clear audience. + +| Surface | Primary job | Default style | +|---|---|---| +| `README.md` | Orient, explain value, and route the reader | concise, accessible, persuasive without hype | +| Project/current-state records | Establish authoritative status | precise, compact, evidence-oriented | +| Architecture/specifications | Explain design and contracts | technical, structured, normative where required | +| Experiment protocols | Define reproducible procedures | formal, explicit, unambiguous | +| Evidence/audit records | Preserve verification history | forensic, exact, minimally interpretive | +| Historical records | Preserve provenance | descriptive, clearly time-scoped | +| Contribution/community docs | Help people participate | practical, welcoming, actionable | + +Do not make a public landing page carry the full burden of an evidence ledger. Link to the authoritative record instead. + +## 2. Separate facts, interpretation, and policy + +Use language that makes the type of statement obvious: + +- **Fact:** what the repository, test, run, or source actually shows. +- **Interpretation:** what that evidence reasonably supports. +- **Policy:** what DGAF requires or prohibits. +- **Hypothesis:** what remains to be tested. +- **Historical record:** what was true or claimed at an earlier point. + +Avoid turning a policy requirement into evidence that the implementation satisfies it. + +## 3. Lead with value before caveat + +For public-facing material, use this order where appropriate: + +1. What it is. +2. Why it matters. +3. What is actually present. +4. How to inspect or use it. +5. What is currently established. +6. Important limitations and boundaries. +7. Deeper records. + +Transparency is strongest when readers understand the project before encountering its qualifications. + +## 4. Use bounded claims, not defensive prose + +Prefer: + +> "The control-plane test suite covers X and Y. The reported result applies to commit Z." + +Over: + +> "Do not infer repository-wide validation from a component-level test..." + +The second formulation remains appropriate when preventing a likely misunderstanding, but repeated negative formulations should be consolidated into one authoritative boundary statement. + +## 5. Control status vocabulary + +Use the repository's epistemic vocabulary consistently: + +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` + +Do not use broad terms such as `validated`, `proven`, `production-ready`, `certified`, or `safe` unless their precise scope is established and the supporting evidence is linked. + +## 6. Status records must be temporally honest + +Current documents should identify their status date and authoritative reference where practical. Active work should reference the current engineering lane. Closed or superseded PRs belong in historical records unless they remain directly relevant to a current blocker. + +When a historical item is necessary, label it as historical in the same sentence or table row rather than relying on a distant disclaimer. + +## 7. Avoid internal-process overload + +A public document normally does not need: + +- every predicate identifier; +- every intermediate SHA; +- every historical remediation branch; +- internal coordination details; +- repeated authorization disclaimers; +- private workspace references; +- agent deliberation or role-play; +- exhaustive closure sequences. + +Retain these details in the appropriate governance or evidence record when they have operational or provenance value. + +## 8. Prefer concrete nouns and active verbs + +Prefer: + +- "The workflow binds the candidate SHA to the executing SHA." +- "The protocol defines the primary endpoint." +- "The audit record preserves the exact run identity." + +Avoid: + +- "It is important to note that..." +- "It should be understood that..." +- "This must not be construed as..." repeated across sections. +- dense noun chains when a short verb phrase is available. + +## 9. Make navigation task-oriented + +Link labels should answer a reader's question: **What do I click next?** + +Prefer `Current state`, `Architecture`, `Experiment protocol`, `Evidence index`, and `Contributing` over long descriptive filenames in high-level navigation. + +Detailed records may use exact filenames when precision is useful. + +## 10. Preserve technical density where it earns its place + +Technical detail belongs in technical documents. Do not simplify away information required to reproduce a result, understand a contract, or audit provenance. Instead, separate layers so readers can choose their depth. + +### Documentation depth hierarchy + +`overview → architecture → contract → implementation → evidence → audit trail` + +## 11. Public-facing social quality + +GitHub readers include engineers, researchers, maintainers, potential contributors, employers, collaborators, funders, and technically curious visitors. Public writing should therefore be: + +- readable without prior knowledge of the project's internal process; +- confident about what exists without exaggerating what it proves; +- respectful of the reader's time; +- explicit about uncertainty without sounding evasive; +- easy to scan on a phone and desktop; +- free of unnecessary personal or private information. + +## 12. Review test + +Before publishing a document, ask: + +1. What is the reader here to learn or do? +2. Can they understand that purpose in the first few lines? +3. Is the most important information visible before implementation detail? +4. Which claims require evidence, and is that evidence discoverable? +5. Are historical and current states clearly separated? +6. Are we repeating a caveat that belongs in one canonical policy? +7. Does every link take the reader somewhere intentionally public and useful? +8. Would an informed outsider describe the document as clear, credible, and appropriately scoped? + +## Relationship to governance + +This guide governs presentation and information architecture. It does not alter technical contracts, evidence states, experimental authorization, or repository authority. The [Public Surface QA Standard](PUBLIC_SURFACE_QA_STANDARD.md) remains the publication control; this guide supplies the editorial layer beneath it. diff --git a/docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md b/docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md new file mode 100644 index 00000000..9a54f536 --- /dev/null +++ b/docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md @@ -0,0 +1,33 @@ +# Legacy Documentation Status Policy + +## Purpose + +DGAF retains historical documentation because provenance matters. Retention, however, is not endorsement of a historical document as a current technical, scientific, or public-facing statement. + +This policy defines how to preserve the record without asking new readers to infer current meaning from obsolete terminology, superseded metrics, or earlier architecture. + +## Status labels + +Historical or superseded documents should be identifiable as one of: + +- **Current** — authoritative for its stated scope. +- **Historical record** — retained as evidence of what existed or was claimed at a particular time. +- **Superseded** — replaced for current operational use by an identified successor. +- **Reference only** — useful background but not an authority for current state. +- **Draft** — incomplete and not an authoritative project statement. + +## Public presentation + +A current landing page should link to current authorities. Historical records should remain discoverable through provenance indexes, changelogs, or explicitly historical sections rather than being presented as equivalent navigation targets. + +Historical terminology and numerical values should not be silently rewritten when doing so would damage provenance. Instead, add context identifying their status and, where appropriate, the current successor or correction. + +## Claims + +A statement remains scoped to the artifact and evidence that support it. Repetition in later documents does not renew its evidentiary status. + +Historical tests, attestations, benchmarks, deployment records, and candidate states are not current verification unless explicitly rebound and re-established under the applicable current procedure. + +## Editorial principle + +**Preserve the record; clarify the status; route readers to the current authority.** diff --git a/docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md b/docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md new file mode 100644 index 00000000..41ea0c94 --- /dev/null +++ b/docs/governance/PUBLIC_DOCUMENTATION_INFORMATION_ARCHITECTURE.md @@ -0,0 +1,81 @@ +# Public Documentation Information Architecture + +## Purpose + +This repository contains implementation, research, governance, and provenance material with different audiences and evidentiary roles. This document defines the preferred public information architecture so readers can find the right level of detail without confusing a landing page, a technical reference, and a forensic record. + +## Documentation layers + +### 1. Landing + +For first-time visitors. + +Answer: **What is this, why does it matter, and where should I start?** + +Primary surface: `README.md`. + +### 2. Project + +For readers evaluating current direction and maturity. + +Answer: **What is the current state and what is being worked on?** + +Primary surfaces: `docs/CURRENT_STATE.md`, `docs/PROJECT_STATUS.md`. + +### 3. Technical + +For implementers and reviewers. + +Answer: **How is this designed and how do the components fit together?** + +Primary surfaces: technical references, module READMEs, specifications, and tests. + +### 4. Research and experiment + +For readers evaluating hypotheses and methods. + +Answer: **What question is being investigated, under what protocol, and what evidence exists?** + +Primary surfaces: experiment protocols, analysis plans, and evidence indexes. + +### 5. Governance and evidence + +For auditors and rigorous review. + +Answer: **What authority, evidence, provenance, and controls support a specific claim?** + +Primary surfaces: governance policies, manifests, verification records, and retained artifacts. + +### 6. Historical + +For provenance and project archaeology. + +Answer: **What did the project previously contain or claim?** + +Historical material should be retained where useful, but should not silently compete with current authorities in primary navigation. + +## Navigation rules + +- Link from a broad layer to a deeper layer when additional precision is needed. +- Prefer one current authority for each important status question. +- Do not duplicate a detailed forensic record on a landing page. +- Preserve historical material through explicit status and provenance rather than deletion for appearance. +- Do not use an internal working artifact as a default public navigation target unless it has been intentionally designated for that role. + +## Claim placement + +Claims should appear where their evidence can be understood at the same level of detail. Broad project descriptions should avoid implying that a component-level result proves repository-wide efficacy. Detailed evidence records may contain exact identifiers, runs, environments, and predicates where those details are necessary for reproducibility. + +## Maintenance test + +Before adding a prominent document link, ask: + +1. Who is expected to use this? +2. What question does it answer? +3. Is it current, historical, or evidence-scoped? +4. Is there already a more authoritative entry point? +5. Does this placement reduce or increase reader friction? + +--- + +This architecture complements the Public Surface QA Standard and Documentation Style Guide. It does not replace experimental evidence or governance controls. diff --git a/docs/governance/PUBLIC_SURFACE_QA_STANDARD.md b/docs/governance/PUBLIC_SURFACE_QA_STANDARD.md index 25c0e11c..876ffb63 100644 --- a/docs/governance/PUBLIC_SURFACE_QA_STANDARD.md +++ b/docs/governance/PUBLIC_SURFACE_QA_STANDARD.md @@ -2,72 +2,102 @@ ## Purpose -This standard governs any DGAF artifact that is visible to a GitHub visitor, contributor, evaluator, recruiter, collaborator, customer, or other external reader. Public-facing repository material represents both the project and its maintainer; internal correctness alone is not sufficient for publication. +This standard governs material visible to a GitHub visitor, contributor, evaluator, recruiter, collaborator, customer, funder, or other external reader. Public material represents both the project and its maintainer; technical correctness alone is not enough. -GitHub's repository guidance treats the README as a primary visitor entry point and recommends clear project purpose, usefulness, getting-started guidance, support paths, and maintainer/contributor information. DGAF applies that expectation as a publication-quality control, not merely as a documentation suggestion. +The companion [Documentation Style Guide](DOCUMENTATION_STYLE_GUIDE.md) defines the editorial rules. This document defines the publication-quality control. ## Publication principle -> **A public artifact must be true, appropriately scoped, useful to its intended audience, professionally presented, correctly placed, safely disclosed, and maintainable.** +> **A public artifact must be true, appropriately scoped, useful to its audience, professionally presented, correctly placed, safely disclosed, and maintainable.** -An internal artifact does not become public-facing merely because it is accurate or authoritative internally. +Public quality has two independent dimensions: -## Public-surface lens +- **Epistemic quality:** the claims are accurate and properly evidenced. +- **Communication quality:** the reader can understand what matters, why it matters, and what to do next. -Before merging a GitHub-visible change, review it through all of these lenses: - -1. **Truth** — Are factual, technical, mathematical, and status claims supported by the appropriate evidence? -2. **Authority** — Is the cited artifact actually authoritative for the claim being made? -3. **Audience** — Is the material written for the people who will encounter it? -4. **Utility** — Does it help a visitor understand, evaluate, use, reproduce, contribute to, or appropriately interpret the project? -5. **Placement** — Is it located where a reasonable GitHub user would expect to find it? -6. **Navigation** — Do links lead to stable, intentional, audience-appropriate destinations? -7. **Professional representation** — Does the surface represent the maintainer's work at the expected engineering/open-source quality bar? -8. **Disclosure** — Does it avoid unnecessary personal information, private workspace material, credentials, internal deliberation, operational clutter, or unfinished work? -9. **Community fit** — Is it consistent with normal open-source expectations for clarity, accessibility, contribution, attribution, licensing, and respectful project maintenance? -10. **Maintenance** — Can the information and its destinations remain coherent as the repository evolves? -11. **Identity integrity** — Does the artifact accurately represent the project and the maintainer rather than overstating capability, validation, status, or maturity? -12. **Friction** — Does it reduce the reader's next-step uncertainty rather than forcing them through internal process or irrelevant detail? +A document can satisfy one without satisfying the other. -## Internal versus public authority +## Public-surface tiers + +| Tier | Examples | Expected treatment | +|---|---|---| +| **Landing** | README, repository description, top-level navigation | value, orientation, quick paths; minimal internal process | +| **Project** | current state, project status, architecture overview | precise status and useful context | +| **Technical** | specifications, contracts, implementation notes | technical depth and explicit semantics | +| **Research** | protocols, analysis plans, experiment records | reproducibility, scope, methodological precision | +| **Evidence** | run records, audit reports, evidence indexes | exact identity, provenance, forensic detail | +| **Historical** | superseded records, reconciliation logs | preserved detail with clear temporal scope | + +A lower-level document may contain more detail than a higher-level document. Do not copy lower-level detail upward merely for completeness. + +## Public-surface lens -DGAF distinguishes internal operational authority from public project navigation. +Before merging a GitHub-visible change, review: -- Personal Notion pages, private working records, internal control notes, and temporary coordination artifacts are **not public navigation targets by default**. -- A GitHub landing page should preferentially resolve to repository-local documentation, stable public project resources, or an intentionally designated public project surface. -- An internal control record may inform public documentation without being exposed as the public destination. -- If an external service is linked, the destination must be intentionally designated for public consumption and must not expose private workspace context merely because the internal team uses it. +1. **Truth** — Are factual, technical, mathematical, and status claims supported? +2. **Authority** — Is the cited source authoritative for the claim? +3. **Audience** — Is the document written for the people who will encounter it? +4. **Utility** — Does it help readers understand, use, evaluate, reproduce, or contribute? +5. **Hierarchy** — Does the most important information appear before supporting detail? +6. **Placement** — Is the information where a reasonable GitHub user expects it? +7. **Navigation** — Are links stable, public, intentional, and useful? +8. **Professional representation** — Does the surface meet a credible engineering/open-source quality bar? +9. **Disclosure** — Does it avoid unnecessary personal, private, credential, or internal-deliberation exposure? +10. **Community fit** — Is it readable, accessible, maintainable, and consistent with open-source norms? +11. **Identity integrity** — Does it accurately represent capability, maturity, evidence, and project boundaries? +12. **Friction** — Does it reduce uncertainty about the reader's next step? -## Evidence and presentation boundary +## Claim presentation -Public documentation must preserve DGAF's epistemic distinctions. In particular: +Use the repository's evidence vocabulary consistently: -`defined → implemented → computed → verified → attested → historical` +`DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED` -must not collapse into a generic claim of "validated" or "production-ready." +Do not collapse these states into generic terms such as `validated`, `proven`, `production-ready`, `certified`, or `safe` unless the precise scope and supporting evidence establish that language. -A mathematical correction can establish a mathematical result without establishing a system-level claim. A passing component test can establish the tested component result without establishing repository-wide validation. A deployment can establish deployment state without establishing experimental authorization or efficacy. +For public-facing documents, prefer bounded positive statements over repeated prohibitions. State what was measured, what it supports, and where the boundary ends. Use explicit warnings when a reasonable reader could otherwise form a materially false conclusion. ## Historical material -Incorrect or superseded values should normally be **retired, classified, superseded, and prevented from downstream use**, not silently erased when their historical presence is relevant to provenance. Historical material must be visibly scoped so a normal visitor cannot mistake it for current project truth. +Historical material may be retained when it has provenance value. It should be visibly dated, labeled, superseded, or otherwise scoped so a normal reader cannot mistake it for current project truth. + +Do not silently rewrite historical evidence to match current state. Do not allow historical claims to remain visually indistinguishable from current claims. + +## Internal versus public authority + +- Personal Notion pages, private working records, internal control notes, and temporary coordination artifacts are not public navigation targets by default. +- Public landing surfaces should resolve to repository-local documentation, stable public resources, or intentionally designated public project surfaces. +- Internal records may inform public documentation without becoming the public destination. +- External services should be linked only when their destination is intentionally public and appropriately maintained. + +## Documentation anti-patterns + +The following are publication-quality risks: -## Required pre-merge review +- audit-ledger content placed on a landing page; +- long lists of internal predicates where a status summary would suffice; +- repeated `must not` / `do not infer` warnings that duplicate one canonical policy; +- closed PRs presented as current engineering work; +- stale SHAs, dates, branch names, or candidate identifiers; +- unexplained acronyms introduced faster than they can be understood; +- agent/persona names used as though they were external authorities; +- marketing language that outruns evidence; +- technical caveats that obscure the project's actual purpose; +- private workspace links or internal deliberation presented as public documentation. -For every externally visible documentation or navigation change, answer: +## Pre-merge reader test -- What will a first-time visitor believe after reading this? -- Is that belief exactly supported by the evidence? -- Is this the right information for this surface? -- Is the destination public, stable, and intentionally maintained? -- Does anything internal or personal become visible unnecessarily? -- Does the change improve comprehension and next-step usability? -- Does it remain coherent with the current README, project status, evidence index, governance records, and terminology? +Ask: -If any answer is materially uncertain, the change should remain internal or be revised before publication. +- What will a first-time visitor believe after the first minute? +- Is that belief accurate? +- Can the reader find the architecture, current status, evidence, and contribution path without knowing internal project vocabulary? +- Are the important caveats present without overwhelming the primary purpose? +- Are historical and current states distinguishable? +- Is every public link intentional and maintainable? -## Relationship to DGAF governance +If a detailed caveat is important but not appropriate for the current surface, move it to the canonical lower-level record and link to it. -This standard is a **publication-surface control**. It does not grant experimental authorization, create a freeze, upgrade evidence, or change empirical N. It operates as a lens over changes that represent DGAF externally. +## Governance boundary -Current experimental state remains independently governed by the authoritative gate/evidence records. +This is a publication-surface control. It does not grant experimental authorization, create a freeze, upgrade evidence, change empirical N, or alter technical authority. Technical and experimental state remain governed by their authoritative records. diff --git a/docs/governance/PUBLIC_SURFACE_REFACTOR_2026-08-29.md b/docs/governance/PUBLIC_SURFACE_REFACTOR_2026-08-29.md new file mode 100644 index 00000000..29e25d73 --- /dev/null +++ b/docs/governance/PUBLIC_SURFACE_REFACTOR_2026-08-29.md @@ -0,0 +1,58 @@ +# Public Surface Refactor — 2026-08-29 + +## Purpose + +This record documents the repository-wide editorial pass initiated after review of the root README. The objective is to preserve DGAF's unusually strong transparency while improving audience fit, hierarchy, scanability, and professional presentation. + +## Finding + +The repository's documentation was generally rigorous but had accumulated a recurring pattern: internal governance, evidence, and coordination detail was sometimes presented at a level intended for landing pages or broad project communication. + +The principal correction is **not to remove evidence**. It is to place information at the level where it is most useful. + +## Repository-wide editorial model + +Documentation now follows this hierarchy: + +### Information hierarchy + +`landing → project → technical → research → evidence → historical` + +Higher-level surfaces summarize and route. Lower-level surfaces preserve detail. + +The canonical editorial rules are in [`DOCUMENTATION_STYLE_GUIDE.md`](DOCUMENTATION_STYLE_GUIDE.md). Publication controls remain in [`PUBLIC_SURFACE_QA_STANDARD.md`](PUBLIC_SURFACE_QA_STANDARD.md). + +## Changes in this pass + +- Root README refocused as a project entry point rather than an internal evidence ledger. +- Documentation map reduced to reader tasks instead of an exhaustive document inventory. +- Current engineering and experimental tracks are explicitly separated. +- Current engineering narrative references PR #139 as the active engineering lane; PRs #132/#133 are historical remediation records unless a deeper record requires their history. +- Contribution guidance now follows the same audience, claim-boundary, and documentation principles. +- Public-surface QA now explicitly identifies audit-ledger overload, repeated prohibitions, stale status references, unexplained acronym density, and caveat-driven loss of project identity as editorial risks. +- A repository-wide style guide establishes rules for audience, hierarchy, claim presentation, temporal scope, navigation, and public social quality. + +## What remains intentionally detailed + +Technical specifications, experiment protocols, evidence indexes, audit records, mathematical policies, provenance records, and historical reconciliations should remain detailed where that detail serves reproducibility or governance. + +The refactor does **not** flatten technical documentation into marketing copy. It separates technical depth from public orientation. + +## Required ongoing behavior + +When changing documentation: + +1. Identify the document's audience and primary job. +2. Put the highest-value information first. +3. Use bounded claims tied to evidence. +4. Avoid repeating caveats that belong in a canonical policy. +5. Mark historical material clearly at the point of encounter. +6. Update living status references when current state changes. +7. Keep internal coordination out of public navigation unless deliberately designated. +8. Prefer links to authoritative records over duplicated audit detail. + +## Verification boundary + +This editorial pass changes documentation only. It does not modify implementation, experimental apparatus identity, freeze state, pilot authorization, empirical N, or scientific results. + +The current experimental state remains governed by the authoritative project/current-state and evidence records. diff --git a/docs/patterns/NDR_CDPO_v4.2-HGF.md b/docs/patterns/NDR_CDPO_v4.2-HGF.md index 4ab05e13..d4b4f754 100644 --- a/docs/patterns/NDR_CDPO_v4.2-HGF.md +++ b/docs/patterns/NDR_CDPO_v4.2-HGF.md @@ -1,60 +1,49 @@ # NDR Pattern: CDPO-v4.2-HGF -**Constraint-Dense Prompt Optimization v4.2 with Hensel Generative Firewall** +## Full pattern name + +Constraint-Dense Prompt Optimization v4.2 with Hensel Generative Firewall **DGAF-Framework · NDR Pattern Registry** **Registered:** S070 · 2026-06-13 -**Authority:** Amethyst (Prime) · COLLEEN (Prefect A) -**Attestation:** Pending — Apogee P-11 review required before CANONICAL +**Status:** Registered design specification; attestation pending **Layer:** 7.0 — Meta-Agent Prompt Architecture **P-36 classification:** ADVISORY -> **Notation control:** Current mathematical notation is governed by `docs/governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`. `pP` is DGAF-specific Platinum Mean notation for `1/(2sin(π/11)) ≈ 1.774732842`; `ρ` is the plastic number; `ρP` is not canonical mathematical notation. +> **Notation control:** Current mathematical notation is governed by [`MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md`](../governance/MATHEMATICAL_NOTATION_POLICY_METALLIC_MEANS_2026-08-28.md). `pP` is DGAF-specific Platinum Mean notation for `1/(2sin(π/11)) ≈ 1.774732842`; `ρ` is the plastic number; `ρP` is not canonical mathematical notation. > > **Epistemic boundary:** This pattern is a design specification. Its presence does not establish experimental efficacy, security, production readiness, or empirical validation. ---- - -## Pattern Spec - -**Name:** Constraint-Dense Prompt Optimization v4.2 with Hensel Generative Firewall (CDPO-v4.2-HGF) - -**Core Skill:** Constraint-optimized prompt refinement with topology-plane firewall → raise enforceable compliance per character while preserving substrate agnosticism. +## Pattern summary -**Use:** Hard-limited meta-agent prompts that keep φ-governance substrate-agnostic while consuming advisory topology ratios. +CDPO-v4.2-HGF specifies a constraint-dense prompt architecture intended to keep governance and registry information separated while allowing advisory topology information to be consumed by a meta-agent prompt. -**Trigger:** When registry constants risk entrainment of the decision core. +**Use:** Hard-limited meta-agent prompts where registry constants must remain advisory rather than becoming decision-core authority. -**Spec summary:** Maximize MUST rules per character via literal triggers, micro budgets, three-plane firewall, polynomial-first registry, and self-audit footer. +**Trigger:** When registry constants risk being treated as governance authority. ---- +**Design summary:** Literal triggers, micro budgets, a three-plane separation model, polynomial-first registry representation, and an explicit self-audit footer. ## Mechanism - **Literal trigger stems:** `architect|system|framework|orchestrat|topolog|multi-agent` → Taxonomy REQUIRED. `registry|closure|platinum|hyperplatinum|rho_P|hensel|a_n|delta_n` → Registry Advisory block REQUIRED. The `rho_P` stem is retained only for detection of legacy terminology; it does not define a current constant. -- **Three-plane firewall as MUST rules:** Governance plane uses φ = 1.618… and φ* ≈ 0.618 only. Registry plane supplies tier records via P-39 PRS with schema `{tier, dimension, duration_class, policy_ratio, descriptor, residual, valid_flag, hash}`. Substrate plane uses AutoInit analytic gain per activation. -- **Hyperplatinum h ≈ 11.0007511609:** Real root of `x^4 - 11x^3 - 1 = 0`, a Pisot-Vijayaraghavan number. Recurrence `a_{n+4} = 11*a_{n+3} + a_n`, seeds 0,0,0,1. Bound claims require their stated proof/source memo and reproduction. -- **Standard Platinum `pP`:** `1/(2sin(π/11)) ≈ 1.774732842`, the regular-hendecagon unit-side circumradius. It is DGAF-specific notation and is not the plastic number or a quadratic metallic mean. -- **Identity anchoring:** `intent_hash = SHA256(canonical_author_id || domain_salt || version)`. Never embed a literal personal name as a runtime invariant. -- **Micro budgets:** Direct Answer ≤40 tokens, Breakdown ≤120 tokens. Degradation order: drop 7, 6, 5, Tradeoffs details; keep 1–4 inviolate. +- **Three-plane separation:** Governance uses φ = 1.618… and φ* ≈ 0.618 only. The registry plane supplies tier records through P-39 PRS with schema `{tier, dimension, duration_class, policy_ratio, descriptor, residual, valid_flag, hash}`. The substrate plane uses AutoInit analytic gain per activation. +- **Hyperplatinum:** `h ≈ 11.0007511609`, the real root of `x^4 - 11x^3 - 1 = 0`. Recurrence `a_{n+4} = 11*a_{n+3} + a_n`, seeds 0,0,0,1. Any bound claim requires its stated proof/source memo and reproduction. +- **Standard Platinum `pP`:** `1/(2sin(π/11)) ≈ 1.774732842`, the regular-hendecagon unit-side circumradius. This is DGAF-specific notation and is not the plastic number or a quadratic metallic mean. +- **Identity anchoring:** `intent_hash = SHA256(canonical_author_id || domain_salt || version)`. A literal personal name must not be embedded as a runtime invariant. +- **Micro budgets:** Direct Answer ≤40 tokens; Breakdown ≤120 tokens. Degradation order: drop 7, 6, 5, Tradeoffs details; keep 1–4 inviolate. ---- +## Separation model -## Pattern - -Enforcement tightening under compression plus plane-separated verification. Advisory ratios may inform registry diagnostics; blocking seals remain separate from governance-plane threshold selection. - ---- +Enforcement tightening under compression is paired with plane-separated verification. Advisory ratios may inform registry diagnostics; blocking seals remain separate from governance-plane threshold selection. ## Tradeoffs | Approach | Pro | Con | Recommended | |----------|-----|-----|-------------| | A — Inline firewall only | Zero tooling | Relies on model attention | Single-prompt, no harness | -| B — Inline + Compliance footer | Machine-checkable | Consumes ~90 chars | **Single-prompt deployments** | -| C — Core prompt + external PRS validator | Frees prompt budget | Adds CI latency | **When a harness exists** | - ---- +| B — Inline + self-audit footer | Machine-checkable | Consumes prompt budget | Single-prompt deployments | +| C — Core prompt + external PRS validator | Frees prompt budget | Adds CI latency | When a harness exists | ## Constraints @@ -65,35 +54,31 @@ Enforcement tightening under compression plus plane-separated verification. Advi | Scale | Design target across DGAF agents; empirical scaling not established here | | Alignment | Explicit role boundary + uncertainty expression intended to reduce overconfidence | ---- +## Failure controls -## Failures +| Trigger | Mitigation | +|---------|------------| +| Registry ratio leaks into P-31 SCPE decay or P-32 Phi-Closure Gate | CI linter rejects `registry.*` imports in `governance/` and `PHI` imports in `registry/` | +| Raw h^n logged causing overflow | Schema requires n and a_n only; hash with context salt | +| `pP` treated as plastic number or identity for π | Require explicit descriptor and residual field; fail validation if absent | +| Legacy `ρ_P` treated as current notation | Reject as current mathematical authority; map only through explicit historical/supersession classification | +| Personal name embedded as live key | Require `intent_hash` with key-rotation metadata | +| Almost-integer predictability attack on a_n | Salted hash before public exposure | -| Trigger | Mitigation | Tag | -|---------|-----------|-----| -| Registry ratio leaks into P-31 SCPE decay or P-32 Phi-Closure Gate | CI linter rejects `registry.*` imports in `governance/` and `PHI` imports in `registry/` | | -| Raw h^n logged causing overflow | Schema requires n and a_n only; hash with context salt | | -| `pP` treated as plastic number or identity for π | Require explicit descriptor and residual field; fail validation if absent | | -| Legacy `ρ_P` treated as current notation | Reject as current mathematical authority; map only through explicit historical/supersession classification | | -| Personal name embedded as live key | Require `intent_hash` with key rotation metadata | `[NON-OBVIOUS]` | -| Almost-integer predictability attack on a_n | Salted hash before public exposure | `[NON-OBVIOUS]` | +## Review considerations ---- +| Lens | Design consideration | +|------|----------------------| +| Formal methods | Store polynomials and recurrences rather than relying on floating-point labels. | +| Systems architecture | Use PRS v0 as the intended source for registry state; keep advisory telemetry separate from blocking boundaries. | +| Security | Use salted hashes for predictable mathematical sequences and explicit identity commitments. | +| Information theory | Track goals, constraints, open questions, and registry use when cross-plane behavior matters. | +| HCI | Use fixed failure syntax and explicit tags to reduce reviewer ambiguity. | +| QA | Keep the self-audit footer machine-parseable when the surrounding deployment requires it. | -## Expert Lens Upgrades +## Concrete artifact — Compliance Footer Validator -| Lens | Change | Why | -|------|--------|-----| -| Formal Methods | Store polynomials and recurrences, not floats | Enables reproducible symbolic representation and replay | -| Systems Architect | PRS v0 as single source of truth; P-37, P-39, P-40 as read-only telemetry in v0 | Separates advisory and blocking boundaries | -| Security | Salted hash of a_n before public exposure; cryptographic intent commitment | Reduces predictable public exposure | -| Information Theory | Extend state to `goals[], constraints[], openQs[], registry_tier_used[]` | Makes cross-plane crossings visible across turns | -| HCI | Fixed failure syntax `trigger=>mitigation` with `[NON-OBVIOUS]` tag | Lowers reviewer load | -| QA | Compliance footer includes `registry_key_valid`, `closure_achieved`, `firewall` | Allows self-audit without parsing body | - ---- - -## Concrete Artifact — Compliance Footer Validator (Python stub) +The following Python stub illustrates the parser contract. It is an implementation example, not evidence that the pattern has achieved its proposed threshold. ```python import re @@ -121,40 +106,30 @@ def validate_compliance_footer(text: str) -> dict: return fields ``` ---- - -## Next Experiment +## Proposed evaluation -**Hypothesis:** A 100-prompt Crucible campaign can measure taxonomy recall, legacy-notation leakage, and Compliance-footer parse success under the declared protocol. +**Hypothesis:** A 100-prompt campaign can measure taxonomy recall, legacy-notation leakage, and self-audit-footer parse success under a declared protocol. **Metric:** Per-section violation count per prompt. **Threshold:** 0 firewall violations and a pre-specified parse-success threshold agreed before execution. -**Method:** Agent Crucible × Amethyst v4.2-hensel, 50 governance + 50 registry prompts. Results → `docs/qa/CRUCIBLE_FIREWALL_RESULTS_v1.md`. +**Method:** Agent Crucible × Amethyst v4.2-hensel, 50 governance + 50 registry prompts. Proposed results location: `docs/qa/CRUCIBLE_FIREWALL_RESULTS_v1.md`. -No threshold is treated as achieved until the retained experiment artifact supports it. +No threshold is treated as achieved until a retained experiment artifact supports it. ---- +## Quick check -## Quick Check +- [ ] Sections 1–7 are present and ordered as specified by the pattern. +- [ ] Registry Advisory block is present with n and a_n on a registry trigger. +- [ ] Self-audit footer parses with `firewall=PASS` where the deployment requires it. -- [ ] Sections 1–7 in order, Taxonomy line present on trigger -- [ ] Registry Advisory block present with n and a_n on registry trigger -- [ ] Compliance footer parses with `firewall=PASS` - ---- - -## Pattern Reference +## Pattern reference **NDR Name:** CDPO-v4.2-HGF **Supersedes:** CDPO-v4 (informal) **Related patterns:** P-37, P-38, P-39, P-40 · NDR Hensel Firewall Rules v1.0 ---- - -*CDPO-v4.2-HGF · Registered S070 · 2026-06-13* -*Attestation pending. Amethyst × COLLEEN* -*See also: docs/agents/AMETHYST_AGENT_SPEC_v4.2-hensel.md* +*Registered design specification. Attestation pending.* **Current DGAF/PDMAL control state:** PRE-FREEZE · FAIL-CLOSED · NOT AUTHORIZED · N=0. diff --git a/pptl/README.md b/pptl/README.md index cba54e59..8689f55e 100644 --- a/pptl/README.md +++ b/pptl/README.md @@ -1,156 +1,76 @@ # PPTL Python Harness -**Phi-Pentagon Topology Lab — Multi-Agent Governance Harness** -DGAF-governed · Agent Amethyst meta-orchestrated · NDR pattern registry +**Phi-Pentagon Topology Lab (PPTL)** is a Python harness for experimenting with agent orchestration, topology, trace capture, and project-defined governance controls. -![pptl-ci](https://github.com/ndrorchestration/DGAF-Framework/actions/workflows/pptl-ci.yml/badge.svg) +PPTL is an implementation and experimentation surface. Passing tests establish behavior for the tested contracts; they do not by themselves establish real-world safety, performance, or efficacy. ---- +## What is here -## Module Map +| Module | Role | +|---|---| +| `topology.py` | Topology constants and role-map utilities | +| `herald_agent.py` | `HeraldAgent` trace collection and sink fan-out | +| `sinks.py` | JSONL, stdout, and webhook sink implementations | +| `n8n_herald_sink.py` | Webhook sink with batching, retry, authentication, and failure handling | +| `rag_verifier.py` | Project-defined RAG verification utilities | +| `orchestrator.py` | Integrated orchestration flow | -| Module | Role | Size | -|--------|------|------| -| `topology.py` | PHI constant, pentagon edge weights, Triad-C role map | 1.1 KB | -| `herald_agent.py` | `HeraldAgent` — trace sink + audit fan-out | 7.3 KB | -| `sinks.py` | `JSONLSink`, `StdoutSink`, `N8nWebhookSink` | 5.7 KB | -| `n8n_herald_sink.py` | Production `N8nHeraldSink` — batching, retry, HMAC, dead-letter | new | -| `rag_verifier.py` | `SentinelRAGVerifier` — DemiJoule RAG hallucination check | 3.4 KB | -| `orchestrator.py` | `IntegratedOrchestrator` — Triad-C 3-gate stack | 5.4 KB | - ---- - -## Quick Start +## Quick start ```python -from pptl import ( - HeraldAgent, JSONLSink, StdoutSink, - SentinelRAGVerifier, IntegratedOrchestrator -) -from pptl.n8n_herald_sink import N8nHeraldSink -import os +from pptl import HeraldAgent, JSONLSink, StdoutSink, SentinelRAGVerifier, IntegratedOrchestrator -herald = HeraldAgent(session_id="sess_001") +herald = HeraldAgent(session_id="example") herald.register_sink(JSONLSink("output/herald_audit.jsonl")) herald.register_sink(StdoutSink()) -herald.register_sink(N8nHeraldSink( - webhook_url = os.environ["HERALD_N8N_WEBHOOK_URL"], - batch_size = 20, - dry_run = False, -)) - -orch = IntegratedOrchestrator( - herald = herald, - verifier = SentinelRAGVerifier(), + +orchestrator = IntegratedOrchestrator( + herald=herald, + verifier=SentinelRAGVerifier(), ) -result = orch.run( - task_id = "T001", - prompt = "Analyze phi-pentagon governance implications.", +result = orchestrator.run( + task_id="example", + prompt="Analyze a topology question.", ) -print(result["status"]) # "pass" +print(result["status"]) herald.close() ``` ---- - -## Wire to Live Dashboard - -```bash -# 1. Set env var -export HERALD_N8N_WEBHOOK_URL=https://your-dashboard.vercel.app/api/herald-ingest -export HERALD_N8N_HMAC_SECRET=your-hmac-secret-here - -# 2. Run with live sink (dry_run=False in N8nHeraldSink) -python -m pptl.experiments.h4_task_stratified - -# 3. Backfill Postgres from existing audit JSONL -INGEST_URL=https://your-dashboard.vercel.app/api/herald-ingest \ -npx ts-node ../../pptl-governance-dashboard/scripts/replay-jsonl.ts \ - output/herald_audit.jsonl -``` - ---- - -## Swap Real LLM - -In `orchestrator.py`, replace `_mock_apogee()`: - -```python -import anthropic -_client = anthropic.Anthropic() - -def _mock_apogee(self, prompt: str, round_n: int) -> str: - msg = _client.messages.create( - model="claude-opus-4-5", - max_tokens=512, - messages=[{"role": "user", "content": prompt}], - ) - return msg.content[0].text -``` - ---- - -## Orchestration Best Practices (S040) - -1. **Gate order is load-bearing** — Gate 1 (input scan) must precede Gate 2 (safety score) must precede Gate 3 (RAG verify). Reordering breaks H3/H4 contract tests. -2. **Case-insensitive signal scan** — always `prompt.lower()` before substring match. Mixed-case obfuscation is the most common real-world bypass vector. -3. **Sink isolation** — `HeraldAgent` must catch per-sink exceptions and route to dead-letter. One crashing sink must never block trace emission to others. -4. **Single source of truth for signal corpora** — `BYPASS_SIGNALS` and `HALLU_SIGNALS` live in `rag_verifier.py` only. Tests import from there; never duplicate in test files. -5. **Parametrize over corpora, not instances** — `@pytest.mark.parametrize` over the corpus list. Adding a signal to the source auto-expands the test suite with zero test-code changes. -6. **Phi edge weights are architectural constants** — `PENTAGON_EDGES` in `topology.py` is the only source. Routing tests assert exact float equality from that source. -7. **Fresh fixture per test** — `fresh_orch` fixture recreates `HeraldAgent` + `CaptureSink` per test function. No shared state across parametrize runs. -8. **Governance marker = merge gate** — `@pytest.mark.governance` tests are the CI blocker. `unit` and `integration` are informational on first failure. -9. **Tri-phase CI matrix** — `unit → governance → integration`, `fail-fast: false`. All three report independently so regressions are locatable without re-running. -10. **Dead-letter sink** — all production sinks (JSONL, n8n) must write failed events to a dead-letter file. Events must never be silently dropped. - ---- - -## NDR Pattern Registry (S040) +For external integrations, configure credentials through environment variables or the deployment's secret-management mechanism. Do not place credentials in source files or documentation examples intended for production use. -| # | Pattern Name | Gate/Layer | Trigger | -|---|---|---|---| -| P-01 | Fan-Out Trace Sink w/ Dead-Letter | Herald | Any multi-sink audit requirement | -| P-02 | Async-Persist Ring Buffer | Sinks | High-throughput trace with I/O latency | -| P-03 | Governance Contract Test | Test | Any gate with enumerable signal corpus | -| P-04 | Parametrized Corpus | Test | New signal added to source list | -| P-05 | Tri-Phase CI Gate | CI | First PR touching gate or sink logic | -| P-06 | Topology × Orchestration Matrix Lab | Experiment | Topology/mode choice needs empirical evidence | - -Full specs: [`docs/NDR_PATTERN_REGISTRY.md`](../docs/NDR_PATTERN_REGISTRY.md) - ---- - -## Test Suite +## Testing ```bash # Full suite pytest pptl/tests/ -v -# CI-equivalent governance gate +# Project-defined governance-marked tests pytest pptl/tests/ -m governance -v +``` -# Hallu corpus -pytest pptl/tests/test_orchestrator.py -k "hallu_signal" -v +Test names and markers describe repository-local contracts. Inspect the relevant test and implementation before treating a result as evidence for a broader claim. -# Obfuscation strict -pytest pptl/tests/test_orchestrator.py -k "obfuscation_detected_strict" -v -``` +## Design notes + +The harness emphasizes a few engineering properties: + +- ordered control checks where ordering is part of the tested contract; +- isolated trace sinks so one sink failure can be handled without silently losing unrelated traces; +- centralized signal corpora to reduce divergence between implementation and tests; +- explicit failure handling and retained diagnostics; +- reproducible test execution for supported environments. -| Module | Count | Markers | -|--------|-------|---------| -| `test_herald_agent.py` | 18 | `unit` | -| `test_sinks.py` | 10 | `unit`, `integration` | -| `test_topology.py` | 8 | `unit`, `governance` | -| `test_orchestrator.py` | ~166+ | `governance`, `integration` | +These are design goals and tested behaviors, not universal guarantees. ---- +## Related documentation -## Related Repos +- [DGAF technical reference](../README.technical.md) +- [Current project state](../docs/CURRENT_STATE.md) +- [Evidence ladder policy](../docs/evidence/EVIDENCE_LADDER_POLICY.md) +- [Legacy documentation status policy](../docs/governance/LEGACY_DOCUMENTATION_STATUS_POLICY.md) -- **Dashboard:** [pptl-governance-dashboard](https://github.com/ndrorchestration/pptl-governance-dashboard) -- **DGAF core:** [DGAF-Framework](https://github.com/ndrorchestration/DGAF-Framework) +## Related projects ---- -*Session S040 — Triad-C stack · Herald trace · 3-gate governance · parametrized test corpora · tri-phase CI* -*NDR Patterns active: P-01 through P-06* +- [PPTL governance dashboard](https://github.com/ndrorchestration/pptl-governance-dashboard) +- [DGAF-Framework](https://github.com/ndrorchestration/DGAF-Framework) diff --git a/tests/test_agent_authority_matrix.py b/tests/test_agent_authority_matrix.py index 837ba981..9eac5b53 100644 --- a/tests/test_agent_authority_matrix.py +++ b/tests/test_agent_authority_matrix.py @@ -56,8 +56,20 @@ def test_matrix_contains_current_specialists(): "Sentinel-Φ", ): assert agent in matrix - assert "Sentience" not in matrix - assert "Sentinel-Φ / Sentinel" not in matrix + + # Historical aliases may be retained for provenance, but cannot appear as + # active authority entries. Check the governed normalization boundary rather + # than coupling the test to exact editorial punctuation in that document. + assert "## 7. Current Identity Normalization" in matrix + normalization = matrix.split("## 7. Current Identity Normalization", 1)[1].split( + "## 8.", 1 + )[0] + assert "Sentinel-Φ" in normalization + assert "active canonical identity" in normalization + assert "Sentinel" in normalization and "historical alias" in normalization + assert "Sentience" in normalization and "not a separate active seat" in normalization + assert "| Sentience |" not in matrix + assert "| Sentinel-Φ / Sentinel |" not in matrix def test_reconciliation_targets_are_explicit():