project-settings-cascade

When to Use

• Adding a new project setting, or changing the default value of an existing one.

This skill is the settings sub-pattern the tool/skill skills depend on; they link here rather than restating it. For the surrounding tool wiring, see agentic-tool-integration, recon-tool-integration, or builtin-agent-skill.

Critical Rules

• NEVER change a default in one layer only. A setting is synchronized across every layer in the table below. Update them in one commit or the UI and backend drift silently.
• NEVER assume existing projects pick up a new/changed default. A Prisma @default applies to new projects only. Existing rows keep their stored value; changing behaviour for them needs an explicit SQL UPDATE (ask before running it - it mutates every project).
• NEVER share settings code between agent and recon. agentic/project_settings.py and recon/project_settings.py are separate modules with their own default dicts (DEFAULT_AGENT_SETTINGS vs DEFAULT_SETTINGS). A setting used by both is declared in both.
• NEVER use prisma migrate. This project is push-based: docker compose exec webapp npx prisma db push.
• ALWAYS keep the name triad aligned: DB column snake_case (via @map()), Prisma field + frontend + API camelCase, Python key SCREAMING_SNAKE_CASE. A mismatch means fetch_*_settings reads None and silently falls back to the default.
• ALWAYS give the frontend onChange a fallback equal to the Python/Prisma default, so a project saved before the field existed does not write undefined.
• A new column FAILS THE BUILD until it has a registry entry. Every parameter is described once, in recon_settings/registry.yaml, with its unit, phase, traffic class, engagement-cap flag, MCP disposition, meaning, and either a bound or a named validator. Add the column, run python3 tooling/scripts/extract_recon_registry.py to draft the entry, EDIT IT, then python3 recon_settings/build.py. The draft is a starting point: no extraction can tell whether a meaning is true or a bound is right.
• NEVER hand-edit registry.json. It is a build artifact, written to two places (recon_settings/ for Python, webapp/src/lib/reconSettings/ for TypeScript) by one build, and build.py --check fails the gate when either is stale. Edit the YAML.
• NEVER add a rate field without roe_capped: true. An rps field with traffic: active and no cap fails the build, because that gap is how three rate limits shipped reachable over MCP and outside the engagement ceiling.
• mcp: settable is the normal answer, and a REAL bound is the control. The form input and the MCP validator are both generated from the registry, so a bound of 0..10000000 is a fake control on both doors at once. bounds.test.ts fails any count or threads maximum above 100000; the only way past it is a field whose SHIPPED default is already higher, named individually in ABOVE_THE_FLAT_CEILING with its own maximum, and the test refuses an entry whose default would fit under the ceiling anyway.
• A field with a closed vocabulary gets values:, not validator: free_text. That is what makes the form render a <select> and the write refuse an unknown value instead of accepting it and having the runtime replace it silently. bounds.test.ts also fails a bespoke control that renders a closed-value field as anything but a <select>, because a text box over a closed set means the form accepts what the save rejects.
• mcp: never needs a deny_reason the schema defines - identity, internal, escalation, secret, upload-managed, engagement-record, not-tuning or derived. There is no ALLOW/DENY table and no unbounded reason; denying a tuning field "to be safe" makes the API the weaker of two doors and fails parity.test.ts.
• A settable field needs a form input, and an input needs a classification. form_section is joined from the tool's entry unless the field names its own, and an explicit null means "no input anywhere" - which the parity test reads to tell a deliberate omission from a forgotten one.
• State what 0 means on any field that defaults to it. Several rates treat 0 as UNLIMITED, which makes it the FASTEST value rather than the safest. A numeric defaulting to 0 without zero_means fails the build, and the meaning has to repeat it in words.