oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-security/resources/ci.md

@@ -0,0 +1,134 @@
+# Security scan gates
+
+Load only for CI or an explicitly requested gate. Keep native execution outcome, candidate severity, independent validation, and gate acceptance separate.
+Use the findings contract for `run.json`, `findings.json`, `runtime.json`, and `gate.json`; this file owns native exit interpretation and gate policy.
+
+## Native contracts
+
+Verify the installed/pinned version before applying this table. Preserve actual exit codes and native output; an exit alone cannot establish that every required analyzer completed.
+
+| Engine/mode | Native behavior | OMA interpretation |
+|---|---|---|
+| Deepsec direct diff/files mode | Official documentation describes 0 for no net-new finding, 1 for a net-new finding; other failures are runtime errors | Read this run's native receipts and errors; a finding exit is not independent proof and zero does not clear unresolved stored findings |
+| Cisco AI Deep SAST | `deepscan.py` exits 0 when its summary `success` is true, otherwise 1 | Parse produced reports and coverage separately; 0 can coexist with vulnerabilities, and dry-run success is not an LLM security scan |
+| Cisco Skill Scanner | Current official results guide: 0 below selected threshold, 1 threshold findings, 2 setup/policy/requested-analyzer construction error | Use the actual `--fail-on-severity` setting and inspect per-skill coverage; a setup error is not a finding |
+| Cisco MCP Scanner | Output and error handling depend on command/mode/version; no common severity exit contract is assumed here | Verify its actual interface and parse native results plus analyzer completion; do not borrow another scanner's exit mapping |
+| Cloudflare local validation | Structured verifier records and observed evidence; no native severity exit is assumed | Accept only validated current records; validator success proves format, not exploitability |
+| ARTEX | Autonomous platform/task interface; no assumed scanner CLI, headless mode, severity exit, or CI support | Require verified adapter or validated manual/external task receipts and evidence; never derive acceptance from service-process exit |
+
+Deepsec's documentation labels runtime errors separately but its numeric table is not sufficient to distinguish every implementation failure. If exit 1 has no usable finding receipt, preserve the ambiguity as error/incomplete rather than synthesizing a vulnerability.
+Cisco Skill Scanner's `LLM_ANALYSIS_FAILED` and `LLM_CONTEXT_BUDGET_EXCEEDED` can appear as INFO coverage notes that do not trigger the severity gate. Treat failed or truncated required judge coverage as incomplete.
+An explicitly selected analyzer that cannot start or cannot complete cannot be silently replaced by a smaller analyzer set.
+
+## Policy receipt
+
+Write `gate.json` using the recorded required receipt identities (`engine:target_id:mode`), policy name/revision, blocking record IDs, and reasons.
+Resolve severity thresholds and whether native candidates gate from the user's/team's existing policy. Do not turn an engine rating into an OMA confirmed vulnerability merely to evaluate the gate.
+If no existing policy resolves an outcome-changing choice, prepare the concrete alternatives and ask only for that missing choice under shared policy.
+
+Apply these outcomes in order while retaining every reason:
+
+1. `error`: required engine execution or result parsing failed; preserve logs/native code.
+2. `incomplete`: required operation, target identity, coverage unit, candidate review, runtime receipt, or proof check is missing/partial/stale; required planned/running/skipped receipts are also incomplete.
+3. `findings`: required checks completed and the policy blocks on the recorded confirmed findings or explicitly selected native candidate threshold.
+4. `pass`: required checks and evidence are complete/current and the selected policy has no blocker.
+
+A partial/error run may also contain confirmed findings; list them and their blocking IDs even when the gate status reflects incomplete execution.
+Reviewed `needs_validation` leads remain distinct from confirmed findings. A policy may require their resolution before passing; do not assign them a normalized severity to make that decision.
+An empty findings array is insufficient for pass: inspect the engine receipts, required coverage, pending candidates, and runtime completion.
+
+Example of a valid gate receipt:
+
+```json
+{
+  "schema_version": 1,
+  "run_id": "20261010-example",
+  "status": "incomplete",
+  "policy": "team-high-plus-v1",
+  "required_engines": ["deepsec:app-source:diff", "artex:test-site:manual_external"],
+  "blocking_records": [],
+  "reasons": ["The requested ARTEX task has no validated completion and traffic receipt."]
+}
+```
+
+## Deepsec diff gate
+
+Use the selected installed runner from the source resource; do not bootstrap a new workspace or run `init` merely to set up a gate. Current `init` may start model-backed review, so it belongs inside the authorized execution plan.
+Resolve the exact baseline and fetched history; record the command, tool/config version, scoped paths, source identity, and persisted/stateless mode.
+The following shows native capture only; it is not the normalized OMA acceptance gate:
+
+```bash
+set +e
+deepsec process --diff "$security_base_ref" \
+  --comment-out "$security_run_dir/raw/deepsec/comment.md" \
+  >"$security_run_dir/raw/deepsec/stdout.log" \
+  2>"$security_run_dir/raw/deepsec/stderr.log"
+security_native_exit=$?
+set -e
+```
+
+Use only after the output directory, installed CLI, authorized backend/scope, and runtime/spend limits have been established. Add only flags verified against that version; the source-scanning resource owns current limit controls.
+Capture and upload receipts with an always-run CI step so a nonzero exit cannot hide failure evidence.
+`--comment-out` may produce no file when there are no new findings; absence of this optional artifact neither proves success nor supplies required scan evidence.
+
+Persisted Deepsec state excludes old findings from the net-new gate. Repeated execution can exit 0 while an unresolved issue remains.
+Choose the already established policy explicitly:
+
+- Net-new policy: evaluate only current direct-mode net-new candidates and preserve prior-state identity.
+- Unresolved-finding policy: inspect current valid stored findings as well; do not rely on the native net-new code alone.
+- Stateless policy: each run analyzes its scoped input again; record that behavior and its cost rather than presenting it as a cache hit.
+
+Running from the repository root versus inside `.deepsec/` can change config/context discovery; record the actual cwd/config and never imply custom matchers/INFO.md applied when they did not.
+
+## Cisco gates
+
+For AI Deep SAST, the verified CLI supports `--json-summary`; retain the summary and native reports, including needs-review records and coverage. Confirm flags for the selected commit before use.
+`--dry-run` indexes without the model analysis; record it as preparatory coverage, not a completed vulnerability pass.
+Check native `success`, phase outcomes, skipped/error counts, output validity, and the JSON findings selected by policy. Do not interpret exit 1 as severity.
+
+For Skill Scanner, preserve the configured policy and threshold. A locally installed version may use:
+
+```bash
+skill-scanner scan "$security_skill_path" \
+  --fail-on-severity high --format json \
+  --output "$security_run_dir/raw/skill-scanner/scan.json"
+```
+
+This example selects core analysis only; add `--use-llm` or other network analyzers only when the selected plan authorizes them. Core-only output does not imply that an LLM judge ran.
+Inspect `findings` and `suppressed_findings`; for `scan-all`, inspect each item under `results`. Preserve suppression reasons and native artifacts.
+Treat requested-analyzer setup errors and per-skill model failures/truncated context as incomplete/error even when severity is below the selected threshold.
+
+For MCP Scanner, the MCP resource owns the exact supported command, output shape, network/stdio effects, and version check.
+Preserve transport/discovery/analyzer errors separately; a discovered server with zero analyzed tools does not satisfy a nonempty requested tool scan.
+No arbitrary MCP tool execution or additional endpoint access follows from a CI gate request.
+
+## ARTEX runtime gates
+
+Do not add a guessed `artex scan`, headless flag, or severity-based exit wrapper. A running platform process says nothing about task completion or vulnerability severity.
+Before automation, verify the chosen snapshot's adapter/API, task lifecycle, scope enforcement, artifact export, and failure/budget-stop reporting.
+Otherwise use `integration: manual_external` and import the actual task/evidence receipt; label the integration external/manual, not native CI support.
+When runtime is required, a pending external task cannot produce a pass.
+
+Validate the runtime receipt's target URL/host/port, allowlist, account roles, allowed effects, bounded execution budget, backend egress, snapshot/tool/image digests, and deployment/session identity.
+Require observed completion/coverage and retained traffic/tool evidence; engine narrative, a screenshot, or “no successful attack” is insufficient.
+Independent replay must bind each confirmed runtime record to the same observed deployment/session; absent deployed revision limits the claim to that session.
+If proof is required and a target identity cannot be established, keep the gate incomplete rather than mapping the checked-out commit onto the deployment.
+Redirects/discovered hosts cannot expand the allowlist; scope violations or budget stops remain visible in receipts and coverage.
+
+## CI trust and artifacts
+
+Keep PR-controlled code in a job without repository-write permissions. A separate PR-comment/report job consumes only a bounded sanitized artifact and never checks out or runs PR code.
+Pin production action references and tool snapshots. Never run untrusted fork code with repository secrets by switching to a privileged event or job.
+Use existing credential exposure policy; adding a scanner does not authorize sending the entire repository or traffic to another provider.
+Keep raw traffic/logs restricted. Upload redacted derivatives and the normalized receipt/report, with defined retention and access; omit cookies, authorization headers, keys, and private data.
+The workflow's final process failure/success implements the recorded OMA gate decision; native tool exit codes stay in evidence rather than being overwritten.
+
+## Sources and version checks
+
+- [Deepsec direct-mode contract](https://github.com/vercel-labs/deepsec/blob/main/docs/reviewing-changes.md).
+- [Cisco AI Deep SAST CLI success exit](https://github.com/cisco-open/ai-deep-sast/blob/main/deepscan.py).
+- [Cisco Skill Scanner results, exit codes, and incomplete judge notes](https://cisco-ai-defense.github.io/docs/skill-scanner/results-and-tuning).
+- [Cisco MCP Scanner supported interfaces](https://github.com/cisco-ai-defense/mcp-scanner).
+- [Cloudflare independent local validation](https://github.com/cloudflare/security-audit-skill/blob/main/skills/security-audit/VALIDATION-AND-REPORTING.md).
+
+These are source references, not version pins. Record the installed release/commit and verify drift before execution; if its behavior disagrees, preserve the observation and update the mapping rather than guessing.

package/skills/oma-security/resources/cisco-source.md

@@ -0,0 +1,108 @@
+# Cisco AI Deep SAST
+
+Load for an explicitly selected Cisco application-source pass, its setup, or troubleshooting.
+Application-source scans otherwise use Deepsec. Do not add Cisco after an empty result without a selected plan.
+Use [findings-contract.md](findings-contract.md) for receipts and [validation.md](validation.md) for independent proof.
+
+## Resolve the artifact and mode
+
+- Upstream is [cisco-open/ai-deep-sast](https://github.com/cisco-open/ai-deep-sast), licensed Apache-2.0.
+- Record the exact source commit, local modifications, Python environment/dependency digest, rule/model artifacts, and selected mode.
+- The public repository has an early history; vendor ownership does not establish production maturity or detection accuracy.
+- `CISCO_SAST_ROOT` is the reviewed scanner checkout; `SCANNER_PYTHON` is its existing isolated Python interpreter.
+- `SOURCE_TARGET` and `RUN_DIR` are absolute paths. Keep the scanner checkout separate from the scanned repository.
+- `TARGET_COMMIT` identifies the scanned source; also retain its dirty-tree content digest and scope in `run.json`.
+- Missing tools, models, or dependencies leave this engine skipped/failed. Installation, model downloads, and builds are separate setup operations.
+
+Inspect the selected checkout and help before composing a scan:
+
+```bash
+git -C "$CISCO_SAST_ROOT" rev-parse HEAD
+git -C "$CISCO_SAST_ROOT" status --short
+"$SCANNER_PYTHON" "$CISCO_SAST_ROOT/aideepsast.py" --help
+"$SCANNER_PYTHON" "$CISCO_SAST_ROOT/deepscan.py" --help
+```
+
+Capture help/version evidence with the engine receipt; the commands below require matching installed flags.
+Do not replace an unavailable pinned dependency or model with a floating release.
+
+| Mode | Work performed | Prerequisites and boundary |
+|---|---|---|
+| Fast, rules only | Semgrep findings without LLM triage | Existing Semgrep and reviewed rules; `--skip-llm` |
+| Fast, local triage | Semgrep plus Foundation-Sec-8B triage | Existing llama.cpp/model; upstream documents about 8 GB model storage and 16 GB RAM |
+| Deep, index only | Parse supported functions and create index/checklist state | `--dry-run`; no LLM phase, but local artifacts are written |
+| Deep, default | Function-oriented LLM detection plus exploratory analysis | Explicit OpenAI-compatible provider/model and budget |
+| Deep, guided | Send rule-matched functions or Semgrep candidates to the LLM | Explicit guide selection; filtered scope must be reported |
+
+The [upstream README](https://github.com/cisco-open/ai-deep-sast/blob/main/README.md) documents these distinct pipelines.
+Configure the selected backend through its documented settings. For deep mode these include `LLM_BASE_URL`, `LLM_MODEL`, and `LLM_API_KEY`.
+Resolve key values from existing credential references; retain only references and the permitted endpoint in receipts.
+A local OpenAI-compatible backend is possible; its availability and resource requirements still need checking.
+Remote deep analysis sends source context to that provider. Secret redaction is not a guarantee that all private data is removed.
+Do not enable a paid/provider fallback, remote rules download, or extra egress implicitly.
+
+## Canonical command path
+
+Run from the reviewed scanner root so its relative configuration/rule paths resolve; always pass an absolute target.
+Give every revision/mode/backend/configuration identity its own native output directory and database.
+The runner captures argv, cwd, timestamps, stdout, stderr, and native exit even when the command fails.
+
+Fast rules-only pass, when selected; `SEMGREP_RULES` is an existing reviewed local rules file/directory:
+
+```bash
+cd "$CISCO_SAST_ROOT"
+"$SCANNER_PYTHON" aideepsast.py --target "$SOURCE_TARGET" --skip-llm --semgrep-config "$SEMGREP_RULES" --output-dir "$RUN_DIR/cisco-fast"
+```
+
+For fast local triage, use the pinned checkout's reviewed scanner configuration and omit `--skip-llm` only after the model is available.
+Keep fast and deep native results separate; their exit contracts and finding states differ.
+
+Index-only deep preflight, when useful for the selected scan:
+
+```bash
+"$SCANNER_PYTHON" deepscan.py --target "$SOURCE_TARGET" --dry-run --output-dir "$RUN_DIR/cisco-index" --db-path "$RUN_DIR/cisco-index/state.db" --commit "$TARGET_COMMIT" --json-summary
+```
+
+An index-only run is preparation, not a completed vulnerability scan.
+For an authorized deep pass with the selected backend configured:
+
+```bash
+"$SCANNER_PYTHON" deepscan.py --target "$SOURCE_TARGET" --output-dir "$RUN_DIR/cisco-deep" --db-path "$RUN_DIR/cisco-deep/state.db" --commit "$TARGET_COMMIT" --show-needs-review --json-summary
+```
+
+Pass `--commit` explicitly: automatic Git discovery can reflect the scanner's cwd rather than the target checkout.
+For an explicitly chosen ASVS/CodeGuard-guided pass, add `--guided --guide-rules both` to a separate native workspace.
+Other documented choices are `asvs`, `codeguard`, and `semgrep`; inspect installed help before using them.
+`--skip-exploratory` narrows default deep coverage. Record it as a mode choice, never an invisible cost optimization.
+Semgrep-guided mode can fetch registry rules and reuses an existing `semgrep_report.json`; verify both egress and artifact identity.
+If missing guide rules cause an upstream fallback to broader LLM analysis, stop unless that scope and budget were already selected.
+The [deep entry point](https://github.com/cisco-open/ai-deep-sast/blob/main/deepscan.py) defines these flags and mode transitions.
+
+## Interpret coverage and resume
+
+- Deep analysis indexes supported function AST nodes; it does not establish review of every file, configuration, dependency, or runtime path.
+- The [indexer](https://github.com/cisco-open/ai-deep-sast/blob/main/indexer.py) excludes common dependency/build directories and supports a bounded language set.
+- The [detector](https://github.com/cisco-open/ai-deep-sast/blob/main/detector.py) uses function bodies and selected call-graph context; exploratory batches group functions from a file.
+- Guided ASVS/CodeGuard analysis skips unmatched functions; Semgrep-guided analysis starts from Semgrep findings. Report those omissions.
+- Retain indexed files/functions, analyzed/skipped functions, phase errors, refusals, and actual candidate counts as measured coverage.
+- A generated checklist or printed completion banner does not prove every coverage item was closed; inspect [coverage tracking](https://github.com/cisco-open/ai-deep-sast/blob/main/coverage_guide.py).
+- Resume is native state reuse, not an assumed `--resume` flag. Preserve the index, SQLite database, and native reports together.
+- The [finding store](https://github.com/cisco-open/ai-deep-sast/blob/main/finding_store.py) can reuse processed symbols without binding them to all revision/model/mode inputs.
+- Reuse that state only for the same recorded identity. A changed source/config/model/mode gets a new workspace; retain the old receipt.
+- Never import a previous `semgrep_report.json` merely because its filename matches.
+
+## Collect results and handle failure
+
+Retain the JSON summary, native JSON/Markdown reports, SQLite state, index, stderr, and stdout unchanged.
+Follow `phases.reports.json` from the summary rather than guessing the native report filename; validate the pinned output schema.
+The [reporter](https://github.com/cisco-open/ai-deep-sast/blob/main/deepscan_reporter.py) owns native finding serialization.
+Deep `0` means the orchestrator reported execution success; `1` means it did not. It is not a severity gate.
+Inspect `success`, `error`, phase error counters, skipped work, and required reports before marking a receipt `completed`.
+Usable output with missed intended work is `partial`; no usable result is `failed`; unavailable prerequisites are `skipped`.
+Do not borrow the fast scanner's severity exits or the fast-only [Jenkins example](https://github.com/cisco-open/ai-deep-sast/blob/main/Jenkinsfile).
+Parse findings and completion separately before applying [ci.md](ci.md).
+
+Upstream triage is another static LLM judgment; its TP/verdict/evidence strings do not supply independent observed reproduction.
+The [triager](https://github.com/cisco-open/ai-deep-sast/blob/main/triager.py) cannot replace the fresh verifier in `validation.md`.
+Import native candidates with origin and severity intact, then apply the common evidence contract.
+Missing sandbox, fixtures, or observed proof keeps candidates `needs_validation`; a static TP label cannot make them `confirmed`.

package/skills/oma-security/resources/deepsec-config.md

@@ -0,0 +1,45 @@
+# Deepsec configuration and recovery
+
+Load for backend selection, credentials, configuration or scanner failure. Read the effective workspace configuration without printing secrets.
+
+## Resolve the actual configuration
+
+Find the config selected by the installed CLI and inspect its project root/data directory. Record config and plugin digests. A config/plugin is executable code: review it before loading with credentials.
+
+Useful current fields include `projects`, `plugins`, `matchers`, `defaultAgent`, `defaultModel`, `defaultThinkingLevel`, `ai` and `dataDir`. Do not hardcode a default model or assume one vendor has better accuracy/cost.
+
+Keep model routing separate from the agent runner. Supported authentication paths depend on the installed version:
+
+| Route | Inspect |
+|---|---|
+| Vercel Gateway | linked-project OIDC or configured Gateway key; selected team/project |
+| Direct provider | provider/base URL and the name of its environment variable |
+| Local authenticated CLI | local runner session and its actual model; separate sandbox credentials |
+| Custom provider | supported runner, endpoint, credential/header handling |
+
+Use native `setup --model-auth …` to change and verify a supported route. Do not silently fall back to a paid provider after an authentication error. Store credential variable names in configuration, never key values in source or command arguments.
+
+For a supported direct OpenAI setup the non-secret flags are:
+
+```text
+--agent codex --model-auth direct --ai-provider openai --ai-api-key-env MY_OPENAI_KEY
+```
+
+Supply the actual secret through the approved environment/secret store. Existing local CLI login does not imply that a hosted sandbox can authenticate.
+
+## Recovery table
+
+| Observation | Next bounded action |
+|---|---|
+| Wrong/no project | Check resolved root/project ID and configuration precedence before any process pass |
+| Missing credential | Check variable presence without displaying value; verify configured route and account |
+| Expired linked token | Use the installed authentication flow within the existing account/scope |
+| Quota/provider refusal | Preserve exact redacted error, affected units and cost; resume after remediation |
+| Sandbox initialization failure | Check the selected platform credentials and supported environment; do not substitute production |
+| Empty matcher results | Inspect ignores, language support and inventory; empty output is not comprehensive coverage |
+| Coverage repair paused | Retain checkpoint and generated proposal evidence; follow the printed resume instruction |
+| Changed model/config/source | Preserve prior receipts; invalidate affected cache/evidence before reuse |
+
+`only`/`exclude`, per-project legacy configuration and CLI overrides can alter coverage. Record the effective selection rather than only the top-level file. Review generated matcher imports and additive plugins together.
+
+Debug logs can contain prompts or credentials. Keep originals access-controlled and redact report copies; avoid verbose auth output in the conversation.

package/skills/oma-security/resources/deepsec-matchers.md

@@ -0,0 +1,35 @@
+# Deepsec matcher and coverage work
+
+Load only for a concrete coverage gap or explicit matcher request. Matchers select source for investigation; a match alone is not a vulnerability.
+
+## Inspect before changing
+
+Read the installed matcher types/samples, the project's surface inventory, generated matchers and candidate counts. State the missed ingress primitive and representative source files. Distinguish unsupported language/parsing from a missing matcher.
+
+Prefer setup's validated declarative specs for bounded regex selection. Keep their schema validation, examples, unique slugs and breadth checks intact. Do not evaluate model-generated TypeScript as a declarative proposal.
+
+A hand-authored plugin is appropriate when the selection requires negative conditions, multiple contextual searches or syntax-aware organization rules. Review it as code. Use the installed `MatcherPlugin` and `regexMatcher` signatures rather than assuming a copied example still compiles.
+
+## Acceptance checks
+
+For each proposal retain:
+
+- The ingress/surface IDs and revision it intends to cover.
+- Narrow relative source globs, language/framework prerequisites and a unique slug.
+- Representative matching examples and nearby nonmatching controls.
+- The expected candidate family/count and measured results.
+- A rationale for its noise tier; this is candidate selection metadata, not finding severity or validation confidence.
+
+Add the plugin without dropping `generatedMatchersPlugin` or other selected plugins. Keep generated data separate from richer reviewed code. Avoid catch-all globs and expensive regexes.
+
+Use the installed focused scan syntax, for example:
+
+```bash
+npx deepsec scan --matchers project-rpc-ingress
+```
+
+Inspect actual candidates, including samples across each intended family and false-match controls. Reconcile full inventory coverage using the installed setup/resume procedure only when its model/cost effects are authorized. A focused scan cannot establish full coverage.
+
+If validation rejects a proposal or it floods the candidate set, retain the rejection/breadth evidence, narrow the rule and repeat the bounded check. Do not bypass safeguards, erase state or label the remaining surface checked.
+
+Store the accepted configuration/matcher digests in `run.json`, including intentionally excluded surfaces. Feed discovered candidates through the same independent validation contract as built-in matcher results.

package/skills/oma-security/resources/deepsec-scanning.md

@@ -0,0 +1,45 @@
+# Deepsec source analysis
+
+Load for source scan/diff, native finding triage, export or resume. Use the configured workspace and pinned native executable. Inspect command help before adding flags.
+
+## Scope and execution
+
+Bind the source revision, dirty/index contents, project root, exclusions, matcher configuration and budget to the receipt. A file-count limit bounds work, not money. Calibrate a large unknown scope within the existing spend limit and record measured usage before expanding.
+
+For a full-source pass, from the existing `.deepsec/` workspace:
+
+```bash
+npx deepsec scan
+npx deepsec status
+```
+
+The matcher pass selects candidates; it does not establish complete vulnerability coverage. Review the inventory against ingress families and sensitive code. An authorized bounded AI calibration may use:
+
+```bash
+npx deepsec process --limit 50 --concurrency 5
+```
+
+Honor tighter user limits. Confirm installed cost/time controls before execution and use them when supported. Keep actual files/batches/cost/time, refusals and unfinished candidates. Do not extrapolate as an exact quote or silently launch an unbounded continuation.
+
+## Diff and explicit files
+
+Direct mode can investigate changed files without a prior full scan. Choose one selector:
+
+```bash
+npx deepsec process --diff origin/main
+npx deepsec process --diff-staged
+npx deepsec process --diff-working
+npx deepsec process --files-from selected-files.txt
+```
+
+These are alternatives, not sequential steps. Resolve and record the baseline SHA and exact selected file identities. Explicit files are investigated even without matcher hits; default ignore filtering still affects scope. Use `--no-ignore` only for a deliberate scope change.
+
+Current diff/direct exit 1 means net-new findings; exit 0 can coexist with earlier unresolved findings. Preserve native results and compare current normalized evidence for the chosen gate policy. Never use the init exit map here.
+
+## Triage and state
+
+Native `triage`, `revalidate`, `export` and `metrics` have version-specific options: inspect their help, then retain complete machine-readable outputs plus any human report. Static TP/FP/fixed/uncertain verdicts are provenance, not independent confirmation. Send candidates to the separate verifier and applicable proof procedure.
+
+Deepsec's discovery worker performs static analysis. Do not instruct it to launch the application, contact endpoints or execute exploits. Runtime proof belongs to a separate verifier/context.
+
+On interruption, retain the exact command, state, processed/pending units and stop reason. Resume the same identity/configuration using native checkpoints; investigate changes before reusing cached results. Never remove `data/<id>/` to obtain a clean run.

package/skills/oma-security/resources/deepsec-setup.md

@@ -0,0 +1,41 @@
+# Deepsec workspace and setup
+
+Load for a source setup request or a missing workspace. Reuse existing `.deepsec/` state.
+
+## Select the setup path
+
+Record the package version, target root, selected agent/model route, authorization and limits in the engine receipt. Prefer a locked local executable; examples use `npx deepsec` as the upstream spelling, not permission to fetch a floating version.
+
+Inspect `--version`, `init --help`, and `setup --help` first. Read the installed `.deepsec/node_modules/deepsec/SKILL.md` and `dist/docs/` when present. Installed help takes precedence over these examples.
+
+Current upstream `init` can authenticate, study the repository, scan and run paid analysis. A plain initialization command is not a scaffold-only operation.
+
+For configuration files alone, from the target root:
+
+```bash
+npx deepsec init --scaffold-only
+```
+
+This does not install dependencies, select/authenticate a model or perform an AI review. Review the scaffold and lock the selected dependency through the target's package manager when setup is authorized. Do not build the target application.
+
+For a setup plan without applying it, if supported:
+
+```bash
+npx deepsec init --plan --output json
+```
+
+Run the one-shot setup/analysis only under an existing scope and spend authorization. Pass that authorization's numeric `--max-cost-usd` and duration `--max-duration` values; do not invent an unlimited default. Headless execution needs explicit answers and an inspected output format. Credential presence is not spend authorization.
+
+## Project context and coverage
+
+Check the configured project ID and resolved root before analyzing. Review `data/<id>/INFO.md` or its `infoMarkdown` override for the actual trust boundaries: callers, authentication/authorization, tenant ownership, secret handling, ingress families and relevant safeguards. Keep it project-specific, with representative paths and small examples instead of generic CWE descriptions.
+
+Setup may generate surface inventory and data-only matchers. Inspect the recorded coverage and exclusions. Preserve `generatedMatchersPlugin` when adding a project plugin. Missing ingress coverage is a gap even if scan candidates exist.
+
+When setup stops, save its printed state/inventory/proposal paths and exact resume command. Repair only the recorded coverage or credential problem, then resume. Do not delete native data to bypass a coverage checkpoint or repeat paid phases already completed.
+
+## Setup evidence
+
+Save version/help, redacted configuration, generated-file digests, setup summary, selected route and any native exit. An init budget/input stop has its own exit semantics; do not interpret it using the diff findings contract.
+
+Keep `.env.local`, authentication material and native data out of commits. Review configuration/matchers before any separately authorized commit. Setup success records preparation/coverage, not confirmed vulnerabilities or runtime proof.