stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

docs consolidation

Browse Source
This commit is contained in:
master
2026-01-07 10:23:21 +02:00
parent 4789027317
commit 044cf0923c
515 changed files with 5460 additions and 5292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/modules/packs-registry/guides/authoring-guide.md
View File

@@ -62,7 +62,7 @@ stella pack init --name sbom-remediation
### 3.4 Configure approvals
- Add `spec.approvals` entries for each required review.
- Capture the metadata Authority enforces: `runId`, `gateId`, and `planHash` should be documented so approvers can pass them through `stella pack approve --pack-run-id/--pack-gate-id/--pack-plan-hash` (see `docs/task-packs/runbook.md#4-approvals-workflow`).
- Capture the metadata Authority enforces: `runId`, `gateId`, and `planHash` should be documented so approvers can pass them through `stella pack approve --pack-run-id/--pack-gate-id/--pack-plan-hash` (see `docs/modules/packs-registry/guides/runbook.md#4-approvals-workflow`).
- Provide informative `reasonTemplate` with placeholders.
- Set `expiresAfter` to match operational policy (e.g., 4 h for security reviews).
- Document fallback contacts in `docs/runbook.md`.

4
docs/modules/packs-registry/guides/registry.md
View File

@@ -171,12 +171,12 @@ Extensions must be deterministic and derived from signed bundle data.
## 11 · TP Gap Remediation (2025-12)
- **Signed registry record (TP7):** Every pack version stores DSSE envelopes for bundle + attestation, SBOM path, and revocation list reference. Imports fail-closed when signatures or revocation proofs are missing.
- **Offline bundle schema (TP8):** Registry exports offline artefacts that must satisfy `docs/task-packs/packs-offline-bundle.schema.json`; publish pipeline invokes `scripts/packs/verify_offline_bundle.py --require-dsse` before promotion.
- **Offline bundle schema (TP8):** Registry exports offline artefacts that must satisfy `docs/modules/packs-registry/guides/packs-offline-bundle.schema.json`; publish pipeline invokes `scripts/packs/verify_offline_bundle.py --require-dsse` before promotion.
- **Hash ledger (TP1/TP2):** Publish step writes `hashes[]` (sha256) for manifest, canonical plan, `inputs.lock`, approvals ledger, SBOM, and revocations; digests surface in audit events and `digestmap.json`.
- **Sandbox + quotas (TP6):** Registry metadata carries `sandbox.mode`, explicit egress allowlists, CPU/memory limits, and quota seconds; Task Runner refuses packs missing these fields.
- **SLO + alerting (TP9):** Pack metadata includes SLOs (`runP95Seconds`, `approvalP95Seconds`, `maxQueueDepth`); registry emits metrics/alerts when declared SLOs are exceeded during publish/import flows.
- **Fail-closed imports (TP10):** Import/mirror paths abort when DSSE, hash entries, or revocation files are absent or stale, returning actionable error codes for CLI/Task Runner.
- **Approval ledger schema:** Registry exposes `docs/task-packs/approvals-ledger.schema.json` for DSSE approval records (planHash must be `sha256:<64-hex>`); import validation rejects non-conforming ledgers.
- **Approval ledger schema:** Registry exposes `docs/modules/packs-registry/guides/approvals-ledger.schema.json` for DSSE approval records (planHash must be `sha256:<64-hex>`); import validation rejects non-conforming ledgers.
---

2
docs/modules/packs-registry/guides/runbook.md
View File

@@ -122,7 +122,7 @@ stella pack approve \
## 9 · Runbooks for Common Packs
Maintain per-pack playbooks in `docs/task-packs/runbook/<pack-name>.md`. Include:
Maintain per-pack playbooks in `docs/modules/packs-registry/guides/runbook/<pack-name>.md`. Include:
- Purpose and scope.
- Required inputs and secrets.

6
docs/modules/packs-registry/guides/spec.md
View File

@@ -131,7 +131,7 @@ spec:
| `metadata` | Human-facing metadata; used for registry listings and RBAC hints. | `name` (DNS-1123), `version` (SemVer), `description` ≤ 2048 chars. |
| `spec.inputs` | Declarative inputs validated at plan time. | Must include type; custom schema optional but recommended. |
| `spec.secrets` | Secrets requested at runtime; never stored in pack bundle. | Each secret references Authority scope; CLI prompts or injects from profiles. |
| `spec.approvals` | Named approval gates with required grants and TTL. | ID unique per pack; `grants` map to Authority roles. Approval metadata (`runId`, `gateId`, `planHash`) feeds Authority’s `pack_run_id`/`pack_gate_id`/`pack_plan_hash` parameters (see `docs/task-packs/runbook.md#4-approvals-workflow`). |
| `spec.approvals` | Named approval gates with required grants and TTL. | ID unique per pack; `grants` map to Authority roles. Approval metadata (`runId`, `gateId`, `planHash`) feeds Authority’s `pack_run_id`/`pack_gate_id`/`pack_plan_hash` parameters (see `docs/modules/packs-registry/guides/runbook.md#4-approvals-workflow`). |
| `spec.steps` | Execution graph; each step is `run`, `gate`, `parallel`, or `map`. | Steps must declare deterministic `uses` module and `id`. |
| `spec.outputs` | Declared artifacts for downstream automation. | `type` can be `file`, `object`, or `url`; path/expression required. |
| `success` / `failure` | Messages + retry policy. | `failure.retries.maxAttempts` + `backoffSeconds` default to 0. |
@@ -175,10 +175,10 @@ Packs must pass CLI validation before publishing.
- **Deterministic RNG/time (TP5):** RNG seed is derived from `plan.hash`; timestamps use UTC ISO-8601; log ordering is monotonic.
- **Sandbox + egress quotas (TP6):** Packs declare `sandbox.mode`, explicit `egressAllowlist`, CPU/memory limits, and optional `quotaSeconds`; missing fields cause fail-closed refusal.
- **Registry signing + revocation (TP7):** Bundles carry SBOM + DSSE envelopes and reference a revocation list enforced during registry import.
- **Offline bundle schema + verifier (TP8):** Offline exports must satisfy `docs/task-packs/packs-offline-bundle.schema.json` and pass `scripts/packs/verify_offline_bundle.py --require-dsse`.
- **Offline bundle schema + verifier (TP8):** Offline exports must satisfy `docs/modules/packs-registry/guides/packs-offline-bundle.schema.json` and pass `scripts/packs/verify_offline_bundle.py --require-dsse`.
- **SLO + alerting (TP9):** Manifests declare `slo.runP95Seconds`, `slo.approvalP95Seconds`, `slo.maxQueueDepth`, and optional `slo.alertRules`; telemetry enforces and alerts on breaches.
- **Fail-closed gates (TP10):** Approval/policy/timeline gates fail closed when DSSE, hash entries, or quotas are missing/expired; CLI surfaces remediation hints.
- **Approval ledger schema:** Approval decisions must conform to `docs/task-packs/approvals-ledger.schema.json`; planHash is `sha256:<64-hex>` and DSSE envelopes must reference ledger digest.
- **Approval ledger schema:** Approval decisions must conform to `docs/modules/packs-registry/guides/approvals-ledger.schema.json`; planHash is `sha256:<64-hex>` and DSSE envelopes must reference ledger digest.
---