feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled

- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions

View File

@@ -1,26 +1,37 @@
# AGENTS
## Role
Scanner.Worker engineers own the queue-driven execution host that turns scan jobs into SBOM artefacts with deterministic progress reporting.
## Scope
- Host bootstrap: configuration binding, Authority client wiring, graceful shutdown, restart-time plug-in discovery hooks.
- Job acquisition & lease renewal semantics backed by the Scanner queue abstraction.
- Analyzer orchestration skeleton: stage pipeline, cancellation awareness, deterministic progress emissions.
- Telemetry: structured logging, OpenTelemetry metrics/traces, health counters for offline diagnostics.
## Participants
- Consumes jobs from `StellaOps.Scanner.Queue`.
- Persists progress/artifacts via `StellaOps.Scanner.Storage` once those modules land.
- Emits metrics and structured logs consumed by Observability stack & WebService status endpoints.
## Interfaces & contracts
- Queue lease abstraction (`IScanJobLease`, `IScanJobSource`) with deterministic identifiers and attempt counters.
- Analyzer dispatcher contracts for OS/lang/native analyzers and emitters.
- Telemetry resource attributes shared with Scanner.WebService and Scheduler.
## In/Out of scope
In scope: worker host, concurrency orchestration, lease renewal, cancellation wiring, deterministic logging/metrics.
Out of scope: queue provider implementations, analyzer business logic, Mongo/object-store repositories.
## Observability expectations
- Meter `StellaOps.Scanner.Worker` with queue latency, stage duration, failure counters.
- Activity source `StellaOps.Scanner.Worker.Job` for per-job tracing.
- Log correlation IDs (`jobId`, `leaseId`, `scanId`) with structured payloads; avoid dumping secrets or full manifests.
## Tests
- Integration fixture `WorkerBasicScanScenario` verifying acquisition → heartbeat → analyzer stages → completion.
- Unit tests around retry/jitter calculators as they are introduced.
# AGENTS
## Role
Scanner.Worker engineers own the queue-driven execution host that turns scan jobs into SBOM artefacts with deterministic progress reporting.
## Scope
- Host bootstrap: configuration binding, Authority client wiring, graceful shutdown, restart-time plug-in discovery hooks.
- Job acquisition & lease renewal semantics backed by the Scanner queue abstraction.
- Analyzer orchestration skeleton: stage pipeline, cancellation awareness, deterministic progress emissions.
- Telemetry: structured logging, OpenTelemetry metrics/traces, health counters for offline diagnostics.
## Participants
- Consumes jobs from `StellaOps.Scanner.Queue`.
- Persists progress/artifacts via `StellaOps.Scanner.Storage` once those modules land.
- Emits metrics and structured logs consumed by Observability stack & WebService status endpoints.
## Interfaces & contracts
- Queue lease abstraction (`IScanJobLease`, `IScanJobSource`) with deterministic identifiers and attempt counters.
- Analyzer dispatcher contracts for OS/lang/native analyzers and emitters.
- Telemetry resource attributes shared with Scanner.WebService and Scheduler.
## In/Out of scope
In scope: worker host, concurrency orchestration, lease renewal, cancellation wiring, deterministic logging/metrics.
Out of scope: queue provider implementations, analyzer business logic, Mongo/object-store repositories.
## Observability expectations
- Meter `StellaOps.Scanner.Worker` with queue latency, stage duration, failure counters.
- Activity source `StellaOps.Scanner.Worker.Job` for per-job tracing.
- Log correlation IDs (`jobId`, `leaseId`, `scanId`) with structured payloads; avoid dumping secrets or full manifests.
## Tests
- Integration fixture `WorkerBasicScanScenario` verifying acquisition → heartbeat → analyzer stages → completion.
- Unit tests around retry/jitter calculators as they are introduced.
## Required Reading
- `docs/modules/scanner/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

View File

@@ -2,3 +2,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| SCANNER-SURFACE-01 | TODO | Scanner Worker Guild | SURFACE-FS-02 | Persist Surface.FS manifests after analyzer stages, including layer CAS metadata and EntryTrace fragments. | Integration tests prove cache entries exist; telemetry counters exported. |
| SCANNER-ENV-01 | TODO | Scanner Worker Guild | SURFACE-ENV-02 | Replace ad-hoc environment reads with `StellaOps.Scanner.Surface.Env` helpers for cache roots and CAS endpoints. | Worker boots with helper; misconfiguration warnings documented; smoke tests updated. |
| SCANNER-SECRETS-01 | TODO | Scanner Worker Guild, Security Guild | SURFACE-SECRETS-02 | Adopt `StellaOps.Scanner.Surface.Secrets` for registry/CAS credentials during scan execution. | Secrets fetched via shared provider; legacy secret code removed; integration tests cover rotation. |