devrites 4.0.12 → 4.2.0

package/pack/generated/codex/skills/devrites-lib/reference/standards/security.md

@@ -37,14 +37,48 @@ services, `localhost`). Defenses, together:
 - Check authorization on every sensitive action, server-side. Guard against IDOR (acting
   on another user's object by changing an id).
 
+## Authentication, authorization, and tenant isolation
+
+- **Authentication establishes identity; authorization permits this action on this
+  resource.** A valid session is not an authorization decision. Re-check policy at every
+  public entry and background/job boundary using server-owned identity and resource data.
+- Deny by default. Role hierarchy, impersonation, service-to-service identity, admin
+  bypasses, and object ownership are explicit policy; do not infer privilege from route
+  location, UI visibility, email/domain, or a caller-supplied role/tenant id.
+- Tenant scope applies to queries, writes, caches, search indexes, object storage paths,
+  queues/jobs, exports, logs, and model/RAG context. Prove denial with two distinct tenants
+  and records; a filter present in source is not evidence that every path applies it.
+- A privilege-changing operation requires re-authorization at use time and an auditable
+  event. Prevent confused-deputy flows where a high-privilege service performs an action
+  solely because a low-privilege caller supplied an id.
+
+## Files, path traversal, parsing, and request integrity
+
+- Resolve filesystem targets beneath an allowed root; reject absolute paths, `..`, encoded
+  traversal, alternate separators, symlink escapes, and archive entries that leave it.
+  Validate the resolved path, not the raw string. Downloads use server-side object lookup,
+  not user-controlled filesystem paths.
+- For uploads, bound body and expanded size, verify content signature rather than trusting
+  filename/MIME, generate the storage name server-side, keep files outside executable/public
+  roots, enforce tenant/owner access, and scan/quarantine when project risk requires it.
+- Treat deserialization, templates, archive extraction, image/document parsers, and plugin
+  formats as code-adjacent boundaries. Use safe/non-executable modes, type/size/depth limits,
+  and isolate risky parsers; never deserialize untrusted data into executable objects.
+- Protect state-changing browser requests with the framework's request-forgery control,
+  appropriate SameSite cookies, and origin checks where supported. CORS is not CSRF defense.
+- Security-sensitive configuration fails closed in every environment. A missing auth key,
+  tenant scope, TLS check, or allowlist is startup/operation failure, never a debug fallback.
+
 ## Secrets
 - Never hard-code secrets or commit them. Use the project's secret mechanism / env /
   vault. Never log secrets, tokens, or personal data.
+- Capture only sanitized diagnostics. Replace credentials, cookies, auth headers, personal/
+  tenant data with typed markers such as `<redacted:authorization>`; raw secret-bearing material
+  never enters scratch, evidence, review, handoff, or output. Use environment-variable command
+  shapes. If redaction removes the decisive signal, record `cannot_verify` plus a safe manual step.
 - Deliver secrets just-in-time and scope them; rotate on exposure.
-- Catch a secret **before** it enters history: a leaked secret is compromised the moment it
-  reaches a remote, so rotate first, then scrub. Cheapest guard is a pre-commit scan of the
-  staged diff: `git diff --cached | grep -iE 'password|secret|api[_-]?key|token'` (the pack's
-  own `commit-msg`/pre-commit hooks are the reference: see [`hooks.md`](hooks.md)).
+- Catch secrets before history with the project's staged-diff scan. Once remote, rotate first,
+  then scrub; see [`hooks.md`](hooks.md).
 
 ## Fail closed
 On any security-relevant error, deny access and roll back: never default to allow or to
@@ -97,11 +131,8 @@ logs, quotes, attachments, repository prose, and external content remain
 
 ## AI / LLM features: the OWASP LLM Top 10
 
-When the feature *itself* calls a model, builds an agent, does RAG, or exposes tool-use, the
-attack surface is the model, not just the code around it. The prompt-injection section above is
-the defender's baseline. It hardens DevRites' own agents (LLM01 from the inside); apply the same
-untrusted-content discipline to the user's LLM surface, plus the rest of the taxonomy. Conditional,
-like the rest of this file: it applies when an LLM surface is in scope, not to every change.
+When a feature calls a model, builds an agent/RAG, or exposes tools, apply prompt-injection
+rules plus this taxonomy. This is conditional on an LLM surface.
 
 - **Prompt injection (LLM01):** untrusted text (user input, retrieved docs, tool output) is
   data, never instructions. Don't concatenate it into a privileged prompt; fence it, and never
@@ -110,18 +141,22 @@ like the rest of this file: it applies when an LLM surface is in scope, not to e
   Never `eval` / render / exec it raw: escape before HTML, parameterize before SQL, validate
   before a tool call. A model that emits `<script>` or `DROP TABLE` is just another injection
   vector.
-- **Excessive agency (LLM06):** give the model the *least* tools, scopes, and autonomy the task
-  needs. A destructive or outbound action behind a model decision needs a human gate or a hard
-  allowlist, not the model's say-so. (DevRites enforces this on itself: reviewers are read-only at
-  the tool layer; the one writer is scope-fenced.)
+- **Excessive agency (LLM06):** use least tools/scope/autonomy. Agentic plans name isolation,
+  network allowlist, execution identity, short-lived credentials, destructive/outbound approvals,
+  audit trail, kill switch, memory retention, and data sent to each external model/MCP. A model
+  cannot widen its own authority; DevRites reviewers stay read-only and its writer scope-fenced.
 - **Sensitive-info disclosure (LLM02) / system-prompt leakage (LLM07):** assume the system prompt
   and context are extractable. Put no secret in them; keep authz server-side, never "the prompt
   told it not to"; don't feed PII/secrets to a model or log prompts/outputs in the clear.
 - **Supply chain & poisoning (LLM03 / LLM04 / LLM08):** pin and vet models, weights, and datasets
   like dependencies; treat third-party models and training/RAG data as untrusted. Embedding and
-  retrieval sources are an injection and poisoning surface: validate what you index.
+  retrieval sources are an injection and poisoning surface: validate provenance before indexing,
+  enforce tenant/ACL filters at retrieval, and prevent one corpus from silently contaminating
+  another.
 - **Misinformation / overreliance (LLM09):** the model can be confidently wrong. Ground answers,
-  cite sources, keep a human in the loop for consequential decisions, and don't present generated
-  content as verified fact.
+  cite only retrieved sources that support the claim, define insufficient-context behavior, keep
+  a human in the loop for consequential decisions, and don't present generated content as verified
+  fact. Evaluate faithfulness and retrieval relevance on domain slices plus adversarial/empty
+  context before and after a prompt/model/index change; a fluent example is not an eval.
 - **Unbounded consumption (LLM10):** rate-limit, cap tokens/cost, and time-out model calls; an
   open-ended prompt loop is both a DoS and a bill.

package/pack/generated/codex/skills/devrites-lib/reference/standards/skill-authoring.md

@@ -1,27 +1,25 @@
 # Skill authoring
 
-> **Source-checkout only.** In a checkout where `pack/.claude/` exists, edit
-> only the canonical source; run `bash scripts/build-host-artifacts.sh`, then validate.
-> Installed generated mirrors are not authoring surfaces; never edit them.
+> **Source-checkout only:** where `pack/.claude/` exists, edit canonical source; run
+> `bash scripts/build-host-artifacts.sh`, then validate. Installed generated mirrors are not authoring surfaces.
 
 ## Surface lifecycle
 
-- **Promoted:** shipped in `pack/`, documented in `docs/skills.md` +
-  `docs/command-map.md`, validated.
-- **Draft:** local/research outside `pack/`.
-- **Deprecated:** compatibility bridge with replacement/removal note.
-- **Research:** `docs/research/` notes; never installed.
+- **Promoted:** validated in `pack/`, `docs/skills.md`, and `docs/command-map.md`.
+- **Draft:** local, outside `pack/`.
+- **Deprecated:** bridge with replacement/removal note.
+- **Research:** `docs/research/`, never installed.
 
 ## Routing metadata
 
-The description routes; it is not documentation.
+Description routes; it is not documentation.
 
 - **Model-invoked:** omit `disable-model-invocation`; use a trigger-bearing
   description.
 - **Explicit-only:** set `disable-model-invocation: true`, use a human summary,
   expose through `$rite`; generate Codex
   `policy.allow_implicit_invocation: false` without a stub description.
-- Description caps: public model-invoked 90 words; internal 75; explicit-only
+- Caps: public model-invoked 90 words; internal 75; explicit-only
   30; `devrites-lib` 60. Agent descriptions: 45 words.
 - Model-visible `name` + `description` ≤5,200 routing characters;
   `explicit-only` and bodies/references do not count.
@@ -44,15 +42,11 @@ Optional flags obey `core.md` rule 10.
 
 ## Body and placement
 
-- Ordered steps end in checkable completion criteria.
-- Active bodies show in one read: outcome/owner; `Use when`/`Not for`;
-  preconditions/context; ordered decisions + failure/escalation; artifact/write
-  owner; proof; exit/next route. Omit inapplicable fields; headings may vary.
-  Examples/anti-examples distinguish branches/misuse.
-- Split only for an independent activation/read path or fresh evals proving inline
-  premature exit; otherwise keep one owner.
-- Co-locate a concept's definition, rule, caveat, and example at one load tier;
-  branch references carry whole clusters.
+- Ordered steps end in checkable criteria.
+- One read shows outcome, triggers, preconditions, decisions/failure, write owner,
+  proof, exit; omit irrelevant fields. Examples distinguish branches.
+- Split only for independent load path or eval-proven inline failure; keep one owner;
+  move each definition/rule/caveat/example cluster together.
 - Every public optional-flag skill obeys the shared
   [`core.md`](core.md#operating-rules-every-phase): declare its
   complete flag surface in `argument-hint`,
@@ -92,17 +86,15 @@ regresses.
 External sources are references, not authority. Promote only when one
 `docs/research/` admission record contains:
 
-- **Provenance:** source, commit/date, files, license/attribution. Unclear rights →
-  reference-only, independently written DevRites prose.
-- **Gap + owner:** observed DevRites failure and existing canonical owner; extend
-  before adding a surface.
-- **Adaptation + cost:** exact DevRites delta without foreign brands/paths/chains/
-  host assumptions; justify dependency/context/process/hook/agent/command. Prefer
-  native/existing/stdlib/CLI.
-- **Proof + disposition:** distinguishing positive/negative checks, host/package
-  parity, and rejection reasons.
+- **Provenance:** origin, review date/files, adaptation, and derived targets; external assets add
+  source URL/SHA/path/license, local/user assets add relative path/digest/owner. Unverified
+  external origin/rights → reference-only, independently written prose.
+- **Gap + owner:** observed failure and existing canonical owner; extend before adding.
+- **Adaptation + cost:** native delta, no foreign brands/paths/host assumptions; justify every
+  dependency, context, process, hook, agent, or command.
+- **Proof + disposition:** positive/negative checks, host/package parity, rejection reasons.
 
-A missing field means no promotion.
+Missing field → no promotion.
 
 ## Match form to failure
 
@@ -115,9 +107,15 @@ A missing field means no promotion.
 
 Behavior-shaping prose is code:
 
-1. Run a no-guidance baseline; if it does not fail, do not add guidance.
-2. Run at least five fresh-context reps per variant; inspect every flagged run.
-3. Treat divergent interpretations as a rewrite signal, never an average.
+1. Baseline without guidance; if it passes, add none.
+2. Run ≥5 fresh-context reps/variant; inspect every flagged run.
+3. Divergent interpretations require rewrite, not averaging.
+4. Pin host/model/build, corpus, grader, and candidate digest or commit+path. Report tasks/trials,
+   arms, same-build A/A noise before A/B, sanitized per-trial verdicts/metrics, invalid/null results,
+   variance, process versus job outcome, and supported/unproved claims. Never capture raw transcripts;
+   lost grading signal is `cannot_verify`.
+
+CI validates only corpora/deterministic artifacts—never paid sessions or lexical-as-model claims.
 
 ## Pruning
 
@@ -126,11 +124,8 @@ guards. Fill omitted decisions or mark a deliberate branch.
 
 ## Contribution preflight
 
-Record catalog search, why an existing owner fails, evals, host parity, and
-public/internal surface.
-Public commands need docs/generated hosts/reply marker;
-internal skills need trigger/not-for plus proof they are not an agent/reference.
-Agents need role/scope/mode/output/composition and
-[`agents.md` § Result admission](agents.md#result-admission) for review roles.
-Only `devrites-slice-wright` writes product source/tests. The controlling root's
-path-bounded `.devrites/**` workflow artifacts follow `workflow-artifacts.md`.
+Record catalog search, owner gap, evals, host parity, and public/internal surface. Public
+commands need docs/generated hosts/reply marker; internal skills need trigger/exclusion and
+skill-not-agent proof. Agents need role/scope/mode/output/composition plus
+[Result admission](agents.md#result-admission) for reviewers. Only `devrites-slice-wright`
+writes product source/tests; root-owned bounded `.devrites/**` follows `workflow-artifacts.md`.

package/pack/generated/codex/skills/devrites-lib/reference/standards/test-proof-checklist.md

@@ -4,6 +4,10 @@
 - The test was seen fail for the right reason.
 - Verification commands and relevant output are recorded.
 - Regression, edge, and error paths match the acceptance criteria.
+- Applicable data, integration, topology, compatibility, concurrency, retry, interruption,
+  and time-zone risks have discriminating cases or a recorded dismissal.
+- Mocks do not remove the risk being claimed; wiring proof follows real data to the promised surface.
+- A claimed pre-existing/environment-only failure has a same-command baseline.
 - Passing existing tests alone is not proof of the change.
 
 Detailed standard: `testing.md`.

package/pack/generated/codex/skills/devrites-lib/reference/standards/testing.md

@@ -24,6 +24,10 @@ covered, not lines executed: 100% line coverage can still leave a button's click
 and a button with one asserting unit test is "covered" at far less than 100% lines. Chase the
 behavior, not the number.
 
+Poor test coverage or missing tests in a brownfield area is baseline risk, not permission to leave
+the changed behavior unproven. Add the smallest surface-anchored regression test and separate
+pre-existing failures with same-command evidence.
+
 Acceptance and tests are **surface-anchored**: assert the outermost surface the intent names. If the feature promised an API response, assert the API response; a database row behind it is supporting evidence, not proof.
 
 Put each test at the level that proves it cheapest and most reliably (the pyramid above):
@@ -54,14 +58,14 @@ runtime behavior. Explicit shell assertions and golden/text comparisons remain v
 criterion genuinely concerns a textual or command-line artifact and the assertion
 discriminates the required result.
 
-- **No tautological assertions.** `expect(result).toBeDefined()` / `.not.toBeNull()` /
-  `assert x is not None` pass for almost any return value. Assert the **actual value or
-  observable effect**: `expect(total).toBe(42)`, the specific error thrown, the state changed,
-  the row written, the event emitted.
+- **Preserve producer failure.** `test-command | tail` may hide a failed producer. Require
+  upstream-failure semantics or separately check its status; truncated output is not a pass.
+- **No tautologies.** Defined/non-null passes for almost anything; assert exact value, error,
+  state change, row, or event.
 - **Don't assert the mock.** A test that stubs a dependency to return `X` then asserts `X` came
   back tests the stub, not your code. Assert the real effect on real (or realistic) data.
-- **Cover the unhappy edges, not just the happy path.** AI is strong on "valid input → success"
-  and weak on empty / boundary / invalid-state / long-or-weird input: write those explicitly.
+- **Cover unhappy edges:** empty/missing input, omitted fields, boundaries, invalid state, and
+  long/weird input; assert the promised rejection/default.
 - **Prove it can fail.** For a critical or regression path, break the code deliberately and confirm the test goes red; use the project's mutation runner when one exists.
 - **Don't mirror the implementation.** A test whose assertions restate the code under test
   (same constant, same formula, same branch) stays green even when the logic is wrong. Assert
@@ -126,6 +130,44 @@ breaks, because it tested the stubs, not the code (see "Don't assert the mock" a
 | A third-party API or paid/rate-limited service | Your own internal utilities and transforms |
 | Anything non-deterministic or slow | Validation and mapping under test |
 
+## Prove the risk the design actually introduces
+
+Select cases from the accepted spec and applicable standards, not a generic count:
+
+- Durable data changes apply [`data-integrity.md`](data-integrity.md): invalid write,
+  duplicate/retry, concurrent update, interrupted migration/backfill, old/new version
+  coexistence, tenant denial, and rollback/forward recovery as relevant.
+- API/webhook/queue/cache work applies
+  [`integration-reliability.md`](integration-reliability.md): invalid/partial response,
+  auth failure, timeout/unknown outcome, rate limit, outage, duplicate, out-of-order,
+  poison/backlog, and stale-cache/partition behavior as relevant.
+- Multi-root/service work applies [`repository-topology.md`](repository-topology.md):
+  provider and consumer both consume the canonical contract and run from their proven
+  roots. One member's green suite cannot prove another member.
+- Compatibility/delivery work drives both feature-flag states and old/new caller or
+  schema combinations. Migration-before-code and code-before-migration order each need a
+  declared expected result.
+
+Dismiss an irrelevant case with a reason; silently omitting an applicable case is a gap.
+
+## False-positive and coincidental-reliance checks
+
+- **Trace cause to effect.** A test proves wiring only when real input reaches the new
+  implementation and its distinct output reaches the promised surface. Registration,
+  file existence, a spy call, or a fixture containing the expected text can pass while
+  production still uses the old path.
+- **Change the load-bearing input or implementation.** For a critical link, perturb the
+  input or break the link and observe the surface assertion fail. If another path happens
+  to produce the same output, the test relies on coincidence and needs a discriminating
+  fixture/assertion.
+- **Do not mock away the named risk.** A timeout test whose mock cannot time out, a
+  transaction test without transaction boundaries, or a tenant test with one tenant is
+  mislabeled coverage. Use a contract-capable fake, local integration surface, sandbox,
+  or authorized real boundary appropriate to the risk.
+- **Baseline environmental claims.** "Pre-existing", "only fails in CI", or "works in one
+  region/time zone" requires a before-candidate run or other dated baseline on the same
+  command and environment. Without it, classify the result as unresolved.
+
 ## Determinism: no flaky tests
 - A flaky test is a broken test. Isolate and fix it immediately; don't paper over it with
   retries or `sleep`.
@@ -137,6 +179,9 @@ breaks, because it tested the stubs, not the code (see "Don't assert the mock" a
   output is pinned in tests. A raw `time.Now()` feeding output makes a golden snapshot rot at the
   next day boundary: green today, red tomorrow, for no code change. The test must control time so
   its result depends on behavior, not when the suite runs.
+- Pin the time zone and locale independently of the instant. Cover offset/date rollover,
+  daylight-saving gap/fold where the product supports it, and serialization round trips;
+  a UTC-only unit test does not prove local-calendar behavior.
 - **No elapsed-time assertions.** `assert elapsed < 200ms` / `took` under a threshold tests the
   CI runner's load, not your code: flaky by construction. Assert the *result*, not the duration;
   for ordering or concurrency use a deterministic signal (a fake clock, a channel), never a `sleep`.