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.

The layers (recon example: katanaTimeout)

Agent-only settings use DEFAULT_AGENT_SETTINGS + fetch_agent_settings; recon-only use DEFAULT_SETTINGS + fetch_project_settings. There is no shared module.

The registry reaches three services on three schedules

This is the part that bites, because two of the three pick a change up on their own and the third does not:

Rebuilding the agent is not optional after a registry change. build.py also writes recon_settings/roe_parse_prompt.py, which embeds the SHA-256 of registry.json, and /roe/parse compares that digest against the registry it actually loaded. A stale agent image therefore returns 503 on every RoE document upload, naming both digests, rather than parsing a document against a field list that no longer matches what will validate the answer.

It fails closed on purpose: a stale prompt does not produce an error, it produces a confidently wrong configuration.

Commands

bashCopy code
python3 tooling/scripts/extract_recon_registry.py             # draft the registry entry for a new column
python3 recon_settings/build.py                               # rebuild the THREE artifacts (--check in the gate)
cd webapp && npm run docs:settings                            # regenerate the wiki settings registry
docker compose exec webapp npx prisma db push                 # apply schema; NEVER prisma migrate
docker compose build agent && docker compose up -d agent      # REQUIRED after ANY registry change (see below)
docker compose restart recon-orchestrator                     # picks the registry up from its mount
# existing projects (ask first - mutates every row):
docker compose exec postgres psql -U redamon -d redamon -c "UPDATE projects SET katana_timeout = 3600 WHERE katana_timeout IS NULL;"

Resources

• Naming + servement details in docs/readmes/coding_agent_prompts/PROMPT.ADD_RECON_TOOL.md (settings multi-layer flow)
• Related skills: agentic-tool-integration, recon-tool-integration, recon-ai-enrichment