# ORBIT RFC Publishing Operations Manual

**Version:** 1.0.0  
**Authority:** ZeroTrust ORBIT-CORE  
**Applies to:** Every ZeroTrust Platform product team  
**Audience:** Product leads, architects, engineers, reviewers, security, operations, and authorized ORBIT publishers

## 1. Purpose

This manual is the canonical operating procedure for proposing, reviewing, deciding, publishing, and maintaining Requests for Comments (RFCs) across the ZeroTrust Platform.

An RFC is a durable governance record. It must explain the problem, evidence, existing implementations, proposed decision, adoption plan, reviews, final decision, conditions, and implementation proof.

ORBIT-CORE is the platform authority for RFC governance and authoritative publication.

## 2. The two-record rule

Every significant RFC creates two linked records.

### Governance record

The ORBIT RFC API and Observatory record:

- RFC key;
- submission;
- reviews and recommendations;
- final decision and conditions;
- event timeline;
- publisher identity;
- request identifiers.

### Authoritative document

The complete Markdown or approved artifact is published into the ORBIT document registry and receives:

- an ORBIT document code;
- version;
- SHA-256 checksum;
- product associations;
- publication state;
- download and integrity evidence.

**The governance record says what was decided. The authoritative document preserves the complete RFC and evidence.**

## 3. When an RFC is mandatory

An RFC is required for changes that:

- alter platform architecture or authority boundaries;
- introduce a shared framework, SDK, protocol, package, or design standard;
- change security, trust, authentication, encryption, privilege, or key management;
- change a public or inter-product API;
- affect multiple ZeroTrust products;
- introduce a new product or major product identity;
- change deployment, update, rollback, recovery, or compatibility policy;
- promote a tested implementation into an official production standard.

Routine bug fixes, typo corrections, and internal refactoring that do not change contracts normally do not require an RFC.

## 4. Lifecycle

```text
Idea
  ↓
Evidence collection
  ↓
Working draft
  ↓
Product-team review
  ↓
ORBIT submission
  ↓
Cross-team review
  ↓
Decision: ADOPT | ADAPT | EXPERIMENT | REJECT
  ↓
Authoritative document publication
  ↓
Implementation and release evidence
  ↓
Verification, supersession, or retirement
```

A decided RFC must never be silently rewritten. A new RFC supersedes it.

## 5. RFC key convention

```text
RFC-<PRODUCT>-<NNNN>
```

Examples:

```text
RFC-WIRESHIELD-0001
RFC-ATLAS-0007
RFC-ALOQU-0012
RFC-ORBIT-0003
```

Use uppercase product codes and a four-digit sequence. Never reuse a key.

Good title:

```text
Production Adoption of the WireShield Native Linux Client
```

Weak title:

```text
Linux App Work
```

## 6. Required ORBIT API fields

The submission API requires:

- `rfc_key`
- `title`
- `summary`
- `problem`
- `evidence` — array with at least one item
- `existing_implementations` — array with at least one item
- `proposed_decision`
- `adoption_plan`

Reviews require:

- `recommendation`: `adopt`, `adapt`, `experiment`, or `reject`
- `rationale`
- optional `evidence` array

Final decisions require:

- `decision`: `adopt`, `adapt`, `experiment`, or `reject`
- `rationale`
- optional `conditions` array

## 7. Evidence standard

Every major claim should answer:

```text
What was tested?
Where was it tested?
Which branch and commit were tested?
Which commands were run?
What was expected?
What was observed?
Who observed it?
When was it observed?
Where is the durable artifact?
What is its checksum?
```

For a native Linux client, include:

- repository, branch, and exact commit;
- OS, architecture, compiler, CMake, Qt, and dependencies;
- clean build;
- package or executable SHA-256;
- install and launch;
- authentication;
- tunnel establishment;
- gateway selection;
- routing and DNS;
- reconnect and disconnect;
- logout and secret cleanup;
- privilege boundary;
- secret storage;
- logs and redaction;
- upgrade, uninstall, and rollback;
- screenshots where useful;
- known limitations;
- acceptance-test matrix.

Never write only “tested successfully.”

## 8. Roles and tokens

ORBIT publisher scopes are:

```text
read
submit
review
decide
```

Prefer separation of duties:

- proposing team submits;
- another qualified party reviews;
- an authorized authority decides.

Publisher tokens are secrets. Never commit or include them in documents.

```bash
export ORBIT_URL="https://orbit.btsbackbone.com"
export ORBIT_PUBLISHER_TOKEN="<publisher-token>"
```

## 9. Required RFC document structure

Create the RFC in the product repository:

```text
docs/rfcs/RFC-WIRESHIELD-0001-production-adoption-linux-client.md
```

Required sections:

1. Metadata
2. Executive summary
3. Decision requested
4. Context
5. Problem
6. Goals
7. Non-goals
8. Existing implementations
9. Proposed decision
10. Architecture
11. Security model
12. Tested implementation
13. Evidence
14. Acceptance matrix
15. Alternatives
16. Compatibility
17. Observability
18. Adoption plan
19. Rollback plan
20. Risks and mitigations
21. Known limitations
22. Decision conditions
23. Review questions
24. References and appendices

## 10. Pre-submission gate

```text
[ ] RFC key is unique
[ ] Title asks for a decision
[ ] Problem is specific and measurable
[ ] Evidence is reproducible
[ ] Existing implementations are described
[ ] Proposed decision is explicit
[ ] Adoption plan is operational
[ ] Security implications are documented
[ ] Rollback is documented
[ ] Known limitations are honest
[ ] Exact commit is recorded
[ ] Artifact checksum is recorded
[ ] Product team reviewed the draft
[ ] No credentials or sensitive customer data are present
```

## 11. Submit an RFC

Create the payload:

```bash
nano /tmp/rfc-wireshield-0001.json
```

Example:

```json
{
  "rfc_key": "RFC-WIRESHIELD-0001",
  "title": "Production Adoption of the WireShield Native Linux Client",
  "summary": "Authorize the recently tested WireShield Linux client as the production reference client for supported Linux workstations, subject to defined security, packaging, observability, rollout, and rollback controls.",
  "problem": "WireShield requires a supported native Linux client that preserves tested VPN behavior while providing a stable desktop framework, secure privilege separation, deterministic packaging, observable connectivity state, and a documented rollback path.",
  "evidence": [
    "The client compiled successfully with the recorded C++17, Qt 6, and CMake toolchain.",
    "The tested build launched successfully on the designated Debian 12 environment.",
    "Existing VPN connection behavior remained functional during the tested implementation.",
    "Detailed build, connectivity, security, and rollback evidence is attached to the RFC document."
  ],
  "existing_implementations": [
    "The recently tested WireShield native Linux application.",
    "Previous ZeroTrust VPN Qt client stages and the existing control-plane and gateway services."
  ],
  "proposed_decision": "ADAPT the tested WireShield native Linux client architecture into the production reference implementation after all RFC conditions and acceptance gates are satisfied.",
  "adoption_plan": "Freeze the tested baseline; reproduce the build from a clean environment; complete security and packaging review; publish signed packages and checksums; run staged internal deployment; monitor connectivity, routing, DNS, reconnect, and failure behavior; verify rollback; then authorize wider production distribution."
}
```

Validate:

```bash
python3 -m json.tool \
  /tmp/rfc-wireshield-0001.json \
  >/dev/null
```

Submit:

```bash
REQUEST_ID="$(cat /proc/sys/kernel/random/uuid)"

curl -sS \
  -X POST \
  "${ORBIT_URL}/api/platform/presence/v1/rfcs" \
  -H "Authorization: Bearer ${ORBIT_PUBLISHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Request-ID: ${REQUEST_ID}" \
  --data-binary @/tmp/rfc-wireshield-0001.json \
  | tee /tmp/rfc-wireshield-0001-response.json
```

Expected: HTTP `201`.

## 12. Verify submission

```bash
curl -sS \
  "${ORBIT_URL}/api/platform/presence/v1/rfcs/RFC-WIRESHIELD-0001" \
  -H "Authorization: Bearer ${ORBIT_PUBLISHER_TOKEN}" \
  -H "Accept: application/json" \
  | python3 -m json.tool
```

Browser:

```text
https://orbit.btsbackbone.com/observatory
```

Confirm the key, title, summary, publisher, and submission event.

## 13. Submit a review

```json
{
  "recommendation": "adapt",
  "rationale": "The client architecture is suitable after signed package publication, privilege-separation verification, and a tested update rollback mechanism.",
  "evidence": [
    "Clean build reproduced from the recorded commit.",
    "Connection, routing, DNS, disconnect, and reconnect tests passed."
  ]
}
```

```bash
curl -sS \
  -X POST \
  "${ORBIT_URL}/api/platform/presence/v1/rfcs/RFC-WIRESHIELD-0001/reviews" \
  -H "Authorization: Bearer ${ORBIT_REVIEWER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @/tmp/rfc-wireshield-0001-review.json \
  | python3 -m json.tool
```

Expected: HTTP `201`.

## 14. Record the decision

```json
{
  "decision": "adapt",
  "rationale": "WireShield will adopt the tested Linux client as the production reference architecture after the listed controls are completed and verified.",
  "conditions": [
    "Publish reproducible build instructions and exact dependency versions.",
    "Produce signed packages and SHA-256 checksums.",
    "Verify the privileged service and desktop process boundary.",
    "Document secret storage, log redaction, update, rollback, and uninstall behavior.",
    "Pass staged deployment acceptance tests."
  ]
}
```

```bash
curl -sS \
  -X POST \
  "${ORBIT_URL}/api/platform/presence/v1/rfcs/RFC-WIRESHIELD-0001/decision" \
  -H "Authorization: Bearer ${ORBIT_DECIDER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @/tmp/rfc-wireshield-0001-decision.json \
  | python3 -m json.tool
```

Expected: HTTP `201`.

## 15. Publish the authoritative document in ORBIT

### Server

```text
ztvpn-control-01
```

### Application

```text
/opt/zerotrust-orbit-core/reference-service
```

Copy the completed RFC:

```bash
cd /opt/zerotrust-orbit-core/reference-service

install -d \
  storage/app/orbit/rfcs/wireshield
```

Target:

```text
storage/app/orbit/rfcs/wireshield/RFC-WIRESHIELD-0001-production-adoption-linux-client.md
```

Verify:

```bash
sha256sum \
  storage/app/orbit/rfcs/wireshield/RFC-WIRESHIELD-0001-production-adoption-linux-client.md
```

Publish:

```bash
php artisan orbit:document:publish \
  "rfcs/wireshield/RFC-WIRESHIELD-0001-production-adoption-linux-client.md" \
  --title="RFC-WIRESHIELD-0001 — Production Adoption of the WireShield Native Linux Client" \
  --summary="Governance RFC for adoption of the tested WireShield native Linux application, including security boundary, packaging, rollout, observability, and rollback requirements." \
  --type=rfc \
  --document-version=1.0.0 \
  --language=en \
  --visibility=public \
  --product=WIRESHIELD \
  --product=VPN
```

Record the returned ORBIT document code.

```text
RFC-WIRESHIELD-0001 = governance identity
ZT-RFC-0001         = authoritative document identity
```

## 16. Publish this operations manual itself

Place this manual at:

```text
storage/app/orbit/governance/ORBIT-RFC-Publishing-Operations-Manual-v1.0.0.md
```

Publish it:

```bash
php artisan orbit:document:publish \
  "governance/ORBIT-RFC-Publishing-Operations-Manual-v1.0.0.md" \
  --title="ORBIT RFC Publishing Operations Manual" \
  --summary="Canonical operating manual for proposing, reviewing, deciding, publishing, verifying, superseding, and retiring RFCs across all ZeroTrust Platform product teams." \
  --type=manual \
  --document-version=1.0.0 \
  --language=en \
  --visibility=public \
  --product=ORBIT \
  --product=WIRESHIELD \
  --product=ATLAS \
  --product=ALOQU \
  --product=HOSTIVA \
  --product=CNOS \
  --product=RECOVERYOS \
  --product=DARKREALM \
  --product=VALASHI \
  --product=VOIP-SHIELD \
  --product=GEOCLOUD \
  --product=VPN
```

Then verify it at:

```text
https://orbit.btsbackbone.com/downloads
```

## 17. Portal publication checklist

```text
[ ] Manual appears in Downloads
[ ] Document type is Manual
[ ] Version is 1.0.0
[ ] Status is Published
[ ] All product associations are present
[ ] SHA-256 verification succeeds
[ ] Download works
[ ] Download count increments
[ ] WireShield RFC appears in Observatory
[ ] Governance record and published RFC cross-reference each other
```

## 18. Security scan before publication

```bash
grep -RInE \
  'password|secret|token|private.key|BEGIN .*PRIVATE KEY|cookie|authorization:' \
  docs/rfcs/RFC-WIRESHIELD-0001-production-adoption-linux-client.md
```

Review every match manually.

## 19. Failure handling

### 401

Invalid, missing, expired, rotated, or inactive token.

### 403

Publisher lacks the required scope.

### 409

Duplicate RFC key, or a review/decision was attempted after final decision.

### 422

Missing or invalid payload fields.

Never retry blindly. Preserve the response and request identifier.

## 20. Version and supersession

- Typo/editorial correction: `1.0.0 → 1.0.1`
- Compatible operational clarification: `1.0.0 → 1.1.0`
- Decision-changing revision: submit a new RFC that supersedes the old RFC

Never erase or rewrite historical decisions.

## 21. Definition of done

```text
[ ] Governance submission exists
[ ] Qualified review exists
[ ] Final decision exists
[ ] Conditions are recorded
[ ] Full RFC document is published
[ ] ORBIT document code exists
[ ] SHA-256 verification passes
[ ] Product associations are correct
[ ] Portal download works
[ ] Evidence is durable
[ ] Implementation commit is identified
[ ] Rollout owner is identified
[ ] Superseded RFCs are linked
[ ] No secret is exposed
```

## 22. Canonical links

```text
ORBIT Home:
https://orbit.btsbackbone.com/

RFC Observatory:
https://orbit.btsbackbone.com/observatory

RFC API:
https://orbit.btsbackbone.com/api/platform/presence/v1/rfcs

Authoritative Documents:
https://orbit.btsbackbone.com/downloads

System Status:
https://orbit.btsbackbone.com/health/ready

Release Identity:
https://orbit.btsbackbone.com/version
```

# Operating principle

**Search before designing. Prove before proposing. Review before deciding. Decide before publishing. Verify after publishing. Never erase history.**