Restructure solution layout by module

src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/AGENTS.md

@@ -0,0 +1,32 @@
+# StellaOps.Scanner.EntryTrace — Agent Charter
+
+## Mission
+Resolve container `ENTRYPOINT`/`CMD` chains into deterministic call graphs that fuel usage-aware SBOMs, policy explainability, and runtime drift detection. Implement the EntryTrace analyzers and expose them as restart-time plug-ins for the Scanner Worker.
+
+## Scope
+- Parse POSIX/Bourne shell constructs (exec, command, case, if, source/run-parts) with deterministic AST output.
+- Walk layered root filesystems to resolve PATH lookups, interpreter hand-offs (Python/Node/Java), and record evidence.
+- Surface explainable diagnostics for unresolved branches (env indirection, missing files, unsupported syntax) and emit metrics.
+- Package analyzers as signed plug-ins under `plugins/scanner/entrytrace/`, guarded by restart-only policy.
+
+## Out of Scope
+- SBOM emission/diffing (owned by `Scanner.Emit`/`Scanner.Diff`).
+- Runtime enforcement or live drift reconciliation (owned by Zastava).
+- Registry/network fetchers beyond file lookups inside extracted layers.
+
+## Interfaces & Contracts
+- Primary entry point: `IEntryTraceAnalyzer.ResolveAsync` returning a deterministic `EntryTraceGraph`.
+- Graph nodes must include file path, line span, interpreter classification, evidence source, and follow `Scanner.Core` timestamp/ID helpers when emitting events.
+- Diagnostics must enumerate unknown reasons from fixed enum; metrics tagged `entrytrace.*`.
+- Plug-ins register via `IEntryTraceAnalyzerFactory` and must validate against `IPluginCatalogGuard`.
+
+## Observability & Security
+- No dynamic assembly loading beyond restart-time plug-in catalog.
+- Structured logs include `scanId`, `imageDigest`, `layerDigest`, `command`, `reason`.
+- Metrics counters: `entrytrace_resolutions_total{result}`, `entrytrace_unresolved_total{reason}`.
+- Deny `source` directives outside image root; sandbox file IO via provided `IRootFileSystem`.
+
+## Testing
+- Unit tests live in `../StellaOps.Scanner.EntryTrace.Tests` with golden fixtures under `Fixtures/`.
+- Determinism harness: same inputs produce byte-identical serialized graphs.
+- Parser fuzz seeds captured for regression; interpreter tracers validated with sample scripts for Python, Node, Java launchers.