Skip to content

Repository Governance (Public vs Source of Truth)

Publication Contract · Bidirectional Collaboration

ATLANTYQA operates with two planes:

  • atlantyqa-universe: private single source of truth (control-plane).
  • atlantyqa-universe: public surface for technical community, institutions, customers, and early adopters.
  • stack-tech-core/**: canonical governance path for adopted projects.

Publication rules for atlantyqa-universe

  1. Only sanitized, publicly reusable content.
  2. No negotiation playbooks, tactical pricing, or internal runbooks.
  3. No real customer operational data or sensitive traces.
  4. Public evidence must always be anonymized and explicitly marked as sample data.

Bidirectional collaboration

  • Public -> Universe:
  • issues/discussions feedback
  • bugs and roadmap requests
  • OSS technical contributions
  • Universe -> Public:
  • audience-curated documentation
  • public templates and anonymized examples
  • validated technical updates ready for publication

Main branch entry control

main is protected by a single-source-of-truth contract:

  • Only controlled sync PRs (sync/universe-*, sync/public-*).
  • Only allowed actors (sync bots).
  • Manual exception is limited to label + authorized actor.

The control is implemented in:

  • .github/workflows/main-source-of-truth-gate.yml
  • .github/contracts/main-source-of-truth-gate.json
  • scripts/verify/main_source_of_truth_guard.py

Never assume collaborator decisions without explicit approval

For any PR created from collab/<login>/** branches, collaborator decisions are not valid until explicit approval is provided by contract-authorized approvers.

The control is implemented in:

  • .github/workflows/collaborator-decision-approval-gate.yml
  • .github/contracts/collaborator-decision-approval-gate.json
  • scripts/verify/collaborator_decision_approval_guard.py

Operational rule:

  1. no explicit approval, no merge;
  2. validation runs automatically in CI for PRs to main;
  3. approver policy is versioned as an auditable contract.

Human decision protocol (daily + regulated operations)

Beyond review approvals, every in-scope governed PR must declare:

  1. decision type (daily operations or regulated process);
  2. accountable approver role;
  3. final decision state (approved, changes requested, blocked, waiting for evidence);
  4. residual risk, evidence, and traceability reference to issue/PR.

The control is implemented in:

  • .github/contracts/human-decision-protocol-gate.json
  • .github/workflows/human-decision-protocol-gate.yml
  • scripts/verify/human_decision_protocol_guard.py
  • .github/pull_request_template.md

For ATLANTYQA Sovereign Systems S.L. phase step-01-consultoria-agent-hilt, approval requires explicit decisions from 4 contract-defined actors.

Artifacts:

  • .github/contracts/sl-constitution-step1-approval-gate.json
  • .github/workflows/sl-constitution-step1-approval-gate.yml
  • scripts/verify/sl_constitution_step1_approval_guard.py
  • stack-tech-core/projects/atlantyqa-sovereign-systems-sl/legal/step-01-consultoria-agent-hilt/

Secrets and private industrial information protection

For publication paths (exports/public-repos/**), PRs are blocked when added lines include:

  1. Credential/token/key patterns.
  2. Private competitive strategy markers (pricebook, target margins, customer lists, private negotiation).
  3. Industrial secret or internal/confidential markers.

Private intelligence sync from workflows

ATLANTYQA allows synchronization of workflow-generated data as business intelligence under strict contract controls:

  1. allowed source: only allowlisted workflows;
  2. controlled destination: knowledge/private-intelligence/snapshots/**;
  3. mandatory traceability: manifest.json per snapshot;
  4. sensitive payload: encrypted (*.age) when applicable;
  5. sync PR: sync/universe-* branch and authorized sync actor.

Control artifacts:

  • .github/contracts/private-intelligence-sync-contract.json
  • .github/workflows/private-intelligence-sync.yml
  • scripts/private_intelligence_sync.py

Additional main guardrails:

  • only allowed extensions under knowledge/private-intelligence/**;
  • secret-pattern blocking for cleartext lines in that path.

Adopted-project lifecycle

atlantyqa-universe is now governed as an active core project:

  1. Detected and analyzed from inputs/repositories/**.
  2. Promoted and governed from the canonical path stack-tech-core/projects/*.
  3. Removed from inputs/repositories/GitHub/* after adoption.
  4. Exported into a governed public surface.
  5. Maintained bidirectionally from atlantyqa-universe.
  6. Continuously audited through main gates, secret controls, and traceable change evidence.

Living adopted catalogs:

  • trust/adopted-projects.en.md (public)
  • internal/adopted-projects-index.en.md (internal)