Document package spec audit gaps

pkg/ctxutil/README.md

@@ -0,0 +1,30 @@
+# ctxutil Package
+
+> Small helpers for consistent `context.Context` handling.
+
+## Overview
+
+The `ctxutil` package centralizes context fallback conventions used across the repository. It currently exposes a single helper, `OrBackground`, for call sites that accept an optional context and need a non-nil `context.Context` before invoking context-aware APIs.
+
+## Public API
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `OrBackground` | `func(ctx context.Context) context.Context` | Returns `context.Background()` when `ctx` is nil; otherwise returns `ctx` unchanged |
+
+## Usage Examples
+
+```go
+ctx := ctxutil.OrBackground(ctx)
+```
+
+## Dependencies
+
+**External**:
+- None beyond the Go standard library (`context`).
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/intent/README.md

@@ -25,6 +25,8 @@ Resolution is performed by a `Resolver`, which holds a label matcher function an
 | `RootReference` | struct | Represents a referenced issue or artifact root (node ID, type, URL, labels) |
 | `PullRequestData` | struct | Input data for pull request resolution (node ID, URL, labels, explicit intent, closing issues) |
 | `Resolver` | struct | Stateless resolver that maps labels to intent records |
+| `PolicyRule` | struct | Pairs a match condition with the execution policy fragment to apply |
+| `PolicyCondition` | struct | Describes the intent labels and repository organization context that make a policy rule match |
 
 ### AttributionStatus constants
 
@@ -64,6 +66,12 @@ Resolution is performed by a `Resolver`, which holds a label matcher function an
 |--------|-----------|-------------|
 | `Compile` | `func (c PolicyCompiler) Compile(rec IntentRecord, repo RepositoryContext) ExecutionPolicy` | Compiles an `IntentRecord` and repository context into an execution policy |
 
+### Policy rule types
+
+`PolicyRule` configures a single policy fragment. Its `ID` identifies the matched rule in compiled policy output, `Scope` records the rule level (`"organization"`, `"repository"`, `"intent"`, or `"workflow"`), `When` holds the match criteria, and `Set` holds the `ExecutionPolicy` fields to merge when the rule applies.
+
+`PolicyCondition` matches rule criteria against an `IntentRecord` and `RepositoryContext`. Empty condition fields act as wildcards. `Domain`, `Priority`, and `Risk` match against intent labels; `Org` matches either the repository organization or owner.
+
 ## Usage Examples
 
 ```go