@gspothq/cli 0.1.1 → 0.2.0

package/configurations/general/docs/rules/DOCS.md

@@ -1,9 +1,11 @@
 # Documentation
 
+Read this rule when you write or change documentation.
+
 ## Before you write
 
 Read the implementation and existing pages. Identify the reader, their task, starting state,
-permissions, and risks. Describe supported behavior. State limitations that rule out use before setup.
+permissions, and risks. Describe supported behavior. Before the install steps, state limitations that rule out use.
 
 Keep durable product information in its documentation. Link to its reference instead of copying
 procedures or configuration tables. When behavior changes, update the reference and examples.
@@ -32,9 +34,9 @@ An example teaches one idea and uses the supported API. Include imports, setup,
 readers need. Label an incomplete fragment and say what it omits. Keep volatile output out of
 examples unless the public API defines its exact text.
 
-State the starting directory and prerequisites before commands. Explain placeholders. Separate
-output from commands, or comment output where a copied block must run. State the expected result
-when the result does not make success clear. Give each platform alternative a complete procedure.
+State the starting folder and prerequisites before commands. Explain placeholders. Separate
+output from commands, or comment it out where a copied block must run. State the expected result
+when the command output does not make success clear. Give each system alternative a complete procedure.
 
 A destructive step names its scope, irreversible effects, backup, and recovery before the action.
 Keep permissions, verification, and recovery beside the steps that need them. Use secure defaults
@@ -44,6 +46,11 @@ Keep authentication, retries, and advanced variants outside minimal examples unl
 Start troubleshooting with the observable symptom and common causes. Diagnose before a reset or
 other destructive recovery. Preserve exact public errors and remove private data from examples.
 
+Do not write the current release number in prose or examples. Write `<version>` and say once where to find the
+number, or generate the text from the dependency file.
+
+A test runs or parses each command and each settings file that a page shows.
+
 ## Reference pages
 
 Use the names and values of the API the page documents. Explain public behavior without requiring
@@ -58,7 +65,7 @@ Describe releases by their effect on readers and required actions.
 
 A known issue states its trigger,
 risk, and verified workaround. A deprecation names support, replacement, and migration. A retirement
-names the unavailable functions. Security disclosures follow the project's disclosure policy.
+names the unavailable functions. Security disclosures follow the project policy.
 
 ## Images and video
 
@@ -73,14 +80,14 @@ A video needs captions and a transcript for information absent from the page. Ke
 procedure in text. Do not embed trackers or commit video outside the project's asset workflow.
 Follow the accessibility rules for alt text and color.
 
-Keep diagrams small and give equal concepts
-equal shapes. Prefer editable diagrams and descriptive file names. List keyboard shortcuts and
-platform steps in the same order each time.
+Keep diagrams small and draw equal concepts
+with the same shape. Prefer editable diagrams and descriptive file names. List keyboard shortcuts and
+per-system steps in a fixed order.
 
 ## Links
 
 Use maintained primary sources for external APIs and relative paths for repository content.
 Link text identifies the destination. A public procedure states any account or permission needed
 to open a required page.
-See [Diátaxis](https://diataxis.fr/), [Google's documentation guidance](https://developers.google.com/style),
+See [Diátaxis](https://diataxis.fr/), [Google documentation guidance](https://developers.google.com/style),
 and [W3C image guidance](https://www.w3.org/WAI/tutorials/images/).

package/configurations/general/duplication/manifest.toml

@@ -1,32 +1,30 @@
 [configuration]
-title = "Duplication"
 always_selected = true
-description = "Copy-paste detection across every language a selected configuration claims, with a ceiling for the share of duplicated lines."
+description = "Reports copied code across every language a configuration claims."
+title = "Duplication"
 
 [files]
 languages = true
 
 [[tool]]
+mise = "npm:jscpd"
 name = "jscpd"
-version = "5.2.0"
 npm = "jscpd"
-mise = "npm:jscpd"
-[[tool.replace]]
-file = ".jscpd.json"
-shared = false
+replace = [".jscpd.json"]
+version = "5.2.0"
 
 [[tool_file]]
 target = ".gspot/config/jscpd.json"
 tool = "jscpd"
 
 [[check]]
-name = "jscpd"
-example = "Two selected files containing the same substantial code block can exceed the configured duplication threshold. Move the shared behavior into its actual owner and call it from both locations, then rerun."
+example = "Two files with the same long block of code report that block. Move it into one function, and call it from both places."
+files = { languages = true }
+help = "Move the shared block into one function both callers use."
 level = "all"
-stage = "push"
+name = "jscpd"
 runs = "scope"
-files = { languages = true }
+stage = "push"
+summary = "Reports every block of code copied between files, naming both places."
 tool = "jscpd"
-summary = "Finds blocks of code copied between files. While the duplicated share stays at or under the ceiling it passes, and over it every copy is a finding that names both places."
-why = "A copied block is fixed in one place and stays broken in the other."
-help = "Move the shared block into one function both callers use, or raise limits.duplication.percent with a reason."
+why = "A fix in one place leaves the copied block broken in the other."

package/configurations/general/engineering/manifest.toml

@@ -1,8 +1,12 @@
 allowed_words = ["Bun", "Node", "npm", "pnpm", "mise", "CI", "macOS", "Linux", "Windows", "CSRF", "ASD"]
+
 [configuration]
-title = "Engineering guidance"
 always_selected = true
-description = "Rules on how to work and how to write code. The `[rules]` setting turns them on or off."
+description = "Rules for working and writing code. The `[rules]` setting turns them on or off."
+title = "Engineering guidance"
 
 [rules]
 "ACCESSIBILITY.md" = { filenames = ["*.html", "*.tsx", "*.jsx", "*.vue", "*.svelte", "*.astro", "*.swift"] }
+
+"HTTP.md" = { dependencies = ["express", "fastify", "hono", "koa", "@nestjs/core", "next", "@sveltejs/kit", "fastapi", "flask", "django", "starlette", "aiohttp", "vapor"] }
+"LOGGING.md" = { dependencies = ["pino", "winston", "bunyan", "structlog", "loguru", "express", "fastify", "hono", "koa", "@nestjs/core", "fastapi", "flask", "django", "vapor"] }

package/configurations/general/engineering/rules/agent/PLANNING.md

@@ -1,15 +1,17 @@
 # Planning
 
+Read this rule before you write a plan.
+
 ## Complete change content
 
 A plan holds the complete content of every change it proposes, so another agent can carry it
 out without inventing anything.
 
-- Show the exact diff of every code, configuration, documentation, schema, and text change, and
+- Show the exact diff of each code, configuration, documentation, schema, and text change, and
   the full contents of every new file. Do not summarize a change the diff can show.
-- Name every command that creates, moves, renames, regenerates, or deletes a file, and every
+- Name every command that creates, moves, renames, regenerates, or deletes a file. List each
   generated file the change rewrites.
-- For an image or another binary file, give the source path, the output path, the operation, and
+- For an image or another binary file, give the source and output paths, the operation, and
   the command that reproduces it.
 - Leave no placeholder such as `update accordingly`, `adjust imports`, or `fix any errors`.
 
@@ -31,12 +33,13 @@ Good:
 ## Order and detail
 
 One step holds one change. Order the steps so each one builds on finished work. Change
-a shared interface before its callers, and move a module before the imports that point at it.
-Generated output follows the source that produces it, and cleanup follows the last caller.
+a shared interface before its callers. Move a module before the imports that point at it.
+Put generated output after the source that produces it, and cleanup after the last caller.
 
 Say why the steps run in that order, and name the constraints and assumptions that affect them.
 Mention an edge case only when it belongs to the requested work.
 
 ## Verification steps
 
-A plan verifies the requested change.
+End the plan with the commands that prove the change works, and what each one prints when it passes. Run
+only the checks that cover the change, as WORKING.md says.

package/configurations/general/engineering/rules/agent/SUPPRESSIONS.md

@@ -1,16 +1,25 @@
 # Suppressions
 
-A suppression turns a rule off for one place, and it carries a reason.
+Read this rule before you add a suppression comment or run `gspot ignore`.
 
-- Write the reason on the same line or directly above, in the form `reason: <sentence>.`. It says
-  why the rule does not apply here, not the content of the rule.
-- Scope a suppression to the narrowest thing that works: one rule, one line, one symbol. A
-  file-wide suppression needs a reason that applies to the whole file.
-- Suppress only when the rule misjudges this line. When the code breaks the rule, fix the code.
-- Delete a suppression with no remaining cause. Never add filler statements to pass a check.
+A suppression turns a lint rule off for one place, and it carries a reason.
 
-The forms differ by language. Apply the same rule to all of them: the ESLint
-disable comment, the Ruff `noqa`, the type-checker ignore, the SwiftLint disable, the ShellCheck
-disable. gspot refuses Semgrep and Vale directives.
+- Write the reason on the same line or directly above, in the form `reason: <sentence>.`. The reason says why the
+  lint rule misjudges this place.
+- A reason states a fact that a reader can check in the repository today. Never cite a plan, a table, a
+  conversation, or a decision that the repository does not hold.
+- Scope a suppression to the narrowest thing that works: one lint rule, one line, one symbol. A file-wide
+  suppression needs a reason that holds for every line.
+- Suppress only when the lint rule misjudges this line. When the code breaks the lint rule, fix it.
+- Never suppress a size or complexity limit, such as `complexity`, `max-lines`, or `max-statements`. Split the code
+  by its steps, or ask the user to raise the limit in `gspot.toml`.
+- Do not widen a setting, such as an import boundary or an architecture module, so that a finding passes. Move the
+  code instead.
+- Do not select a configuration only to stop a detection notice. Remove the configuration from that scope instead.
+- Delete a suppression when its cause does not apply. Never add filler statements to pass a check.
 
-To accept a finding without changing the code, run `gspot ignore <check>` with a reason. Ask the user first.
+The forms differ by language. This rule covers each form: the ESLint, SwiftLint, and ShellCheck disable comments, the
+Ruff `noqa`, and the type-checker ignore. gspot rejects Semgrep and Vale directives.
+
+To accept a finding without changing the code, ask the user first. Then run `gspot ignore <check>` with a reason.
+Every other rule that mentions `[[ignore]]` follows this one.

package/configurations/general/engineering/rules/agent/TASKS.md

@@ -1,6 +1,6 @@
 # Task Runner
 
-Rules for `mise` tasks, `package.json` scripts, `Makefile` targets, or the project's runner.
+Read this rule when you change `mise` tasks, `package.json` scripts, a `Makefile`, or another task runner.
 
 ## Task behavior
 
@@ -16,4 +16,8 @@ Rules for `mise` tasks, `package.json` scripts, `Makefile` targets, or the proje
 - Name tasks in kebab-case with a colon namespace, such as `check:fix` or `deploy:staging`.
 - Use the runner's declarative commands and dependency ordering. Keep substantial parsing,
   branching, and process control in the code that implements that behavior.
-- Give each task a concise description in the runner's task list.
+- Give each task a concise description in the runner's list.
+- Do not compute an argument by running code inside the task definition, such as a template `exec()` that
+  evaluates a source file. Put the value where the tool reads it, or in the task script.
+- Write a command line once. When tasks differ in one part, write a single task that takes that part as an argument.
+- A task script runs commands. It does not import the internals of a workspace package.

package/configurations/general/engineering/rules/agent/WORKING.md

@@ -1,9 +1,11 @@
 # Working in a Repository
 
+Read this rule before you change anything in the repository.
+
 ## Running processes
 
 Check for a running instance before you start a dev server, a build watcher, an emulator, or a
-database. Look at the port, the process list and the runner's output. Reuse what runs. Start a
+database. Look at the port, the process list, and the runner's output. Reuse what runs. Start a
 second instance only for a test that needs isolation, or when the user asks in this
 conversation. A framework that moves to the next free port hides the duplicate: two servers then
 serve different code. Stop what you started when the task ends.
@@ -14,61 +16,65 @@ Read the relevant code before touching it. Understand the public interfaces, dat
 and how the modules work together. Then think through your approach:
 
 - Which change solves the problem correctly with the fewest steps?
-- Which failures can occur? What happens with bad input, missing data, concurrent access, network failures?
+- Which failures can occur? What happens with bad input, missing data, concurrent access, or network errors?
 - Does this change affect other parts of the system? Trace the call chain.
 
 When you rename or move a file, update every reference: imports, documentation, configuration, and scripts.
 
-Before adding a new module, directory, or helper, identify the module that implements
-the behavior. When you add a file, tell the user why that module needs it.
+Before you add a module, folder, or helper, identify the code that implements
+the behavior. When you add a file, tell the user why that code needs it.
 
 ## Scope discipline
 
 - Complete the requested task. Do not expand scope.
-- If you discover something unrelated that needs fixing, mention it to the user. Do not silently fix it unless the fix takes one small edit in a file you already edit.
+- If you discover something unrelated that needs fixing, mention it to the user. Leave it unless the fix takes one small edit in a file you already change.
 - Do not add features, refactor surrounding code, or make unrequested improvements.
 
 ## Verification and tests
 
-A check reports what it finds as a finding, and `gspot explain <check>` describes the check.
-
 Do not run verification broader than the change. Run no full test suite, build, scan, or Docker
 check unless the user asks for it or the checks of the repository include it.
 
-Write tests when the user asks or a check requires them. When your change breaks a test, fix the
-test. Language and framework instructions say how to write a test, not when.
+Write tests when the user asks or a check requires them. Fix each test that your change
+breaks. Language and framework instructions say how to write a test, not when.
+
+## Rules and checks
+
+Run `gspot explain <check>` to see what a check looks for and how to fix its findings. When a rule and a check
+conflict, follow the check, and name both to the user.
 
 ## No defensive logic
 
 Do not add guards, fallbacks, retries, defaults, or wrappers for states the public interface rules
-out. Handle known failure modes where failures can occur: user input, network calls, persistence,
-permissions, and external services. Trust an internal invariant once the public interface establishes it. When an invariant lacks a clear promise, trace the code and clarify the promised behavior instead of adding speculative protection.
+out. Handle known failure modes where they can occur: user input, network calls, persistence,
+permissions, and external services. Trust an internal invariant once the public interface establishes it. When an invariant lacks a clear promise, trace the code and define the behavior instead of adding speculative protection.
 
 ## Abstractions
 
 <!-- level: all -->
 
-Keep one implementation for each concept in the module that implements it. Extract shared behavior only
-when real callers need the same behavior and the extraction removes complexity. Do not add
-forwarding wrappers, one-caller helpers, or abstractions for hypothetical reuse. Prefer local
-duplication when callers have different responsibilities. Remove abstractions whose cost exceeds their benefit.
-
-- An abstraction that gains flags, modes, optional branches, or caller-specific conditions needs a different design. Do not box loosely related behavior into one function with a parameter that
-  picks the behavior.
-- Inline a wrong abstraction into each caller, delete the branches each caller does not need,
-  and extract only the common behavior that remains.
-- You can prepare the code to support the requested change: first keep the
-  behavior, then change it, in separate commits.
-- Replace positional booleans and ambiguous arguments with an options parameter using named fields.
-- Pass a function in only when it replaces several option flags across real callers.
-- Prefer plain functions, data structures, and explicit data flow to classes, factories,
-  strategies, and inheritance. Push state and I/O outward, and keep the core close to pure.
+Keep one implementation of each concept, and one copy of each table of values, in the module that uses it.
+Extract shared code only when two or more callers need the same behavior now.
+
+- Delete a function whose body only calls another or returns a single expression. Call the other function
+  directly. Keep a callback that an API needs.
+- Keep a helper with one caller when it names a step and holds real logic. Do not split code into helpers only
+  to pass a size or complexity limit. Split it by the steps it performs.
+- An abstraction that gains flags, modes, or caller-specific branches needs a different design. Do not combine
+  loosely related behaviors in a function behind a parameter that picks one.
+- A function takes at most four parameters, and no positional boolean. Pass other values as named fields: an
+  options object, keyword-only parameters, or argument labels.
+- To remove a wrong abstraction, inline it into each caller, delete the unused branches there, and extract only
+  the common behavior that remains.
+- Pass data, not a callback, unless it replaces several flags across real callers.
+- Prefer plain functions, values, and explicit data flow to classes, factories, strategies, and inheritance. Push state
+  and I/O outward, and keep the core close to pure.
 
 ## No backward compatibility
 
 <!-- level: all -->
 
-Never introduce compatibility layers, wrapper functions, re-exports for renamed symbols, deprecated-but-kept code, or any other form of backward-compatible scaffolding. A published API follows the deprecation policy its project declares instead.
+Never introduce compatibility layers, wrapper functions, re-exports for renamed symbols, deprecated-but-kept code, or other backward-compatible scaffolding. A published API follows the deprecation policy its project declares instead.
 
 When you replace or rename something:
 
@@ -79,5 +85,4 @@ When you replace or rename something:
 
 <!-- level: all -->
 
-Group constants, types, and schemas by the behavior they belong to. Do not mirror the source
-tree in tests.
+Group constants, types, and schemas by the behavior they belong to.

package/configurations/general/engineering/rules/code/ACCESSIBILITY.md

@@ -1,16 +1,18 @@
 # Accessibility
 
+Read this rule when you change a user interface.
+
 ## Structure
 
-- Use semantic elements and roles: headings in order, landmarks, lists for lists, tables for data,
-  native controls such as `button`, `a`, `input`, `select` before custom ones.
+- Use semantic elements and roles: headings in order, landmarks, lists, tables for data, and
+  standard controls such as `button`, `a`, `input`, and `select` before custom ones.
 - Every page has one `h1` and a document language.
 - Reading order matches visual order.
 
 ## Names and descriptions
 
-- Every interactive control has an accessible name. An icon-only control gets a label attribute; a
-  form field gets a visible label; an image gets `alt` that states its purpose, or empty `alt` when
+- Every interactive control has an accessible name. An icon-only control gets a label attribute. A
+  form field shows a visible label. An image gets `alt` that states its purpose, or empty `alt` when
   decorative.
 - Link each error and hint to its field with `aria-describedby` on the web or `accessibilityHint` on iOS.
   Announce an error when it appears.
@@ -18,10 +20,10 @@
 
 ## Keyboard and focus
 
-- Let keyboard users reach everything a pointer can reach, in a sensible order.
+- Let keyboard users reach every target a pointer can, in a sensible order.
 - Show focus. Do not remove the focus indicator without replacing it.
-- Move focus deliberately: into a dialog when it opens, back to the trigger when it closes, to the
-  first error on failed submission, to the new content on route change.
+- Move focus deliberately: into a dialog on open, back to its trigger on close, to the first error
+  after a failed submission, and to new content on route change.
 - No keyboard traps. Escape closes a dialog, menu, or popover and returns focus to its trigger.
 
 ## Motion, size, and contrast

package/configurations/general/engineering/rules/code/CLI.md

@@ -1,6 +1,6 @@
 # Command-Line Programs
 
-These rules apply to command-line programs the project ships for people or automation. Internal build tasks follow the task runner's interface.
+Read this rule when you change a command-line program that the project ships.
 
 ## Streams and exit status
 
@@ -8,26 +8,29 @@ These rules apply to command-line programs the project ships for people or autom
 - Preserve established exit codes. New commands use `0` on success, `1` on failure, and `2`
   on usage error unless their protocol defines other behavior. List each exit code in `--help`.
 - Keep machine-readable `--json` output complete, stable, and free of progress text.
-- Omit color and terminal control sequences unless stdout connects to a terminal and `NO_COLOR` has no value.
+- Omit color and control sequences unless stdout connects to a terminal and `NO_COLOR` has no value.
 
 ## Interface
 
 - `--help` prints usage, every flag with its default, and one example. `--version` prints the
   version and exits.
 - Every value a prompt asks for also has a flag. If the process has no terminal, fail. Name the missing flag.
-- A destructive command asks for confirmation on a terminal and requires `--yes` otherwise.
+- A destructive command prompts for confirmation on a terminal and requires `--yes` otherwise.
+- Help and explain text says what the user can do. It shows no regular expression, internal identifier, source path
+  of the program, or value that the user cannot change.
+- Every command, flag, and setting that help text names exists. A test checks each name.
 
 ## Behavior
 
 - Validate every argument before doing any work. Fail with an actionable message that names the
   argument.
 - Idempotent where the operation allows it: running twice produces the same state.
-- Long operations report progress on stderr and honor interruption: catch the termination signal,
-  clean up, exit with the signal's status.
-- Resolve a relative path against the directory the user ran the command in, or against an
-  explicit argument. Never resolve it against the script's own folder.
-- Create temporary files with the platform's secure call such as `mktemp`, `tempfile.mkstemp`, and
-  delete them on exit.
+- Long operations report progress on stderr and handle interruption: catch the termination signal,
+  clean up, and exit with its status.
+- Resolve a relative path against the folder the user ran the command in, or an explicit
+  argument. Never resolve it against the script's own folder.
+- Create temporary files with a secure call such as `mktemp` or `tempfile.mkstemp`, and delete
+  them on exit.
 
 ## Flag naming
 

package/configurations/general/engineering/rules/code/COMMENTS.md

@@ -1,5 +1,7 @@
 # Comments
 
+Read this rule when you write or change a comment.
+
 ## What a comment says
 
 <!-- level: all -->
@@ -15,7 +17,9 @@ A doc comment says what a function does, what its parameters mean, and what it r
 
 <!-- level: all -->
 
-Write the doc comment that the language check asks for. Add other comments only when a function:
+Write the doc comment that the language check requires. Say what the signature does not. Never write a comment that only repeats a name or a
+type. Name an object parameter for its role, such as `options`, never `root0`. Add other comments only when a
+function:
 
 - handles a failure that its public interface does not explain
 - has concurrency, cancellation, or isolation requirements
@@ -30,6 +34,12 @@ When you change a function, update its doc comment: summary, parameters, return
 Rewrite or delete a comment that describes behavior the code lacks, or the reason for a decision
 you undo.
 
+- When you move or delete a declaration, do the same to its comment. A doc comment sits directly above its
+  declaration, with no blank line between them.
+- Use a file header only when it helps the reader. When present, the header describes the whole file in a single sentence. Update it
+  when the file's job changes.
+- Do not write work status in a comment. For example, do not describe a paused job or a temporary choice.
+
 ## Deferred work
 
 <!-- level: all -->

package/configurations/general/engineering/rules/code/CONFIGURATION.md

@@ -1,5 +1,7 @@
 # Configuration
 
+Read this rule when you change how a program reads its configuration or environment.
+
 ## Validate external values
 
 - A missing or invalid value stops startup. The message names the variable and never prints its

package/configurations/general/engineering/rules/code/ERRORS.md

@@ -1,10 +1,12 @@
 # Errors
 
+Read this rule when you write code that raises, catches, or reports an error.
+
 ## Error taxonomy
 
 - Return a typed result or throw a typed error for an expected operational failure. Invalid input, missing resources, denied permission, and provider timeouts need results the caller can act on.
 - Throw a programmer error for a broken invariant or impossible state. Log its stack and show a generic failure. Never catch it to keep going.
-- A startup failure fails fast before the process accepts work.
+- A startup failure stops the process before it accepts work.
 - On shutdown, set readiness to false, stop accepting work, drain in-flight work for a bounded
   time, close resources, and exit.
 - A fatal runtime error stops new work, reports the failure, and exits. Last-resort handlers never
@@ -14,7 +16,7 @@
 
 - Catch the narrowest type. Never a bare catch-all unless the block re-raises or deliberately isolates an operation and records the failure.
 - Keep the try block around the one operation that can fail.
-- Preserve the cause when wrapping: `new Error(message, { cause })`, `raise ... from error`, `Error` conformance with an underlying error.
+- Preserve the cause when wrapping: `new Error(message, { cause })`, `raise ... from error`, or `Error` conformance with an underlying error.
 - Do not swallow failures. Handle, record, or re-raise each caught error.
 - Run required cleanup in `finally` or the language's equivalent.
 
@@ -29,7 +31,7 @@ private data out of every output.
 - Internal identifiers such as row IDs, user IDs, or session tokens.
 - Stack traces or file paths.
 - Raw upstream, provider, or database errors.
-- Implementation details such as trigger names, policy names, or internal state like "deleted" flags.
+- Implementation details such as trigger and policy names, or internal state like "deleted" flags.
 
 **Always:**
 

package/configurations/general/engineering/rules/code/HTTP.md

@@ -1,14 +1,13 @@
 # HTTP
 
-Rules for any HTTP service, whatever framework serves it, on top of the security, error, and
-logging rules.
+Read this rule when you change an HTTP service.
 
 ## Requests
 
 - Validate input once where the request enters the service, with a schema. Handlers read the
   validated value, never the raw request.
-- Reject unsupported content types on endpoints that take a body. Limit the body size per route,
-  and keep the proxy's body limit equal to the application parser's.
+- Reject unsupported content types on endpoints that take a body. Cap the body size per route,
+  and keep the proxy limit equal to the application parser limit.
 - Handlers adapt transport to domain calls. They define no validation policy, database access,
   provider mechanics, caching, or business decision.
 - Middleware validates, authenticates, rate-limits, and attaches context, and makes no feature
@@ -18,23 +17,23 @@ logging rules.
 
 - One handler formats error responses. Feature code throws and never builds an HTTP error body.
 - Give clients generic, stable messages. Detail stays in server diagnostics.
-- The service documents one success shape and one error shape and keeps both stable.
+- The service documents one shape for success and one for errors, and keeps both stable.
 - Use precise status codes: 201 for creation, 204 with no body, 4xx for caller errors, and 5xx
   only for failures the caller cannot fix.
-- The endpoint or module maps provider and database shapes into response shapes. Response
-  use API field names rather than storage names, unless the public interface explicitly uses the provider's format.
+- The endpoint or module maps provider and database shapes to responses. Responses name fields
+  for the API, not for storage, unless the public interface explicitly exposes the provider format.
 - Escape HTML for its rendering context, and never pre-escape JSON field values.
 
 ## Sessions and transport
 
-- Terminate TLS at the proxy, and trust forwarding headers only from that proxy.
+- Terminate TLS at the proxy, and trust forwarding headers only from it.
 - When the service issues tokens, a revocation reaches every instance.
 
 ## Wire names
 
 <!-- level: all -->
 
-- Keep existing protocol header names, and a new header carries no `X-` prefix, as
+- Keep existing protocol header names. A new header carries no `X-` prefix, as
   [Request for Comments (RFC) 6648](https://www.rfc-editor.org/rfc/rfc6648) recommends.
 
 ## Operations
@@ -43,4 +42,4 @@ logging rules.
 - Broad rate limits sit at the edge, application limits in middleware, and route limits beside
   the route.
 - Either the proxy or the application compresses responses, not both. Under heavy traffic, the
-  reverse proxy compresses responses.
+  reverse proxy does it.

package/configurations/general/engineering/rules/code/LOGGING.md

@@ -1,11 +1,13 @@
 # Logging
 
+Read this rule when you add or change logging.
+
 ## One logger
 
 <!-- level: all -->
 
 - One logging module per process, configured at the entrypoint: level, format, redaction, transports.
-- Feature code obtains a logger from that module. It never instantiates, configures, or adds transports.
+- Feature code gets a logger from that module. It never instantiates, configures, or adds transports.
 - A service logs to stdout. Configure other transports at the logger.
 
 ## Levels
@@ -24,10 +26,10 @@
 - Write a stable, human-readable message string that describes the event. Values go in structured fields, never interpolated into the message.
 - Preserve declared event names and field keys. Before you rename one, tell the user because
   dashboards and alerts may read it.
-- Include the request trace when the request provides one.
-- Use stable names for request IDs, correlation IDs, provider request IDs, operation IDs, resource IDs, and safe user IDs. Propagate them to provider calls when supported.
-- Put an error object in the field the logger serializes errors from, so the logger keeps the stack and cause.
-- Summarize: counts, IDs, statuses, provider names, durations. No large, deeply nested, or expensive-to-compute fields.
+- Include the request trace when one exists.
+- Use stable names for request, correlation, provider request, operation, resource, and safe user IDs. Propagate them to provider calls when supported.
+- Put an error object in the field the logger serializes errors from, so it keeps the stack and cause.
+- Summarize: counts, IDs, statuses, provider names, and durations. No large, deeply nested, or expensive-to-compute fields.
 - Do not compute expensive log arguments when the logger disables the level.
 
 ### Field naming
@@ -38,9 +40,8 @@ Use `lower_snake_case` for new event names and field keys unless an existing log
 
 ## Sensitive values
 
-Follow the secrets rules for values that must never reach logs.
-
-- Personal data, raw user content, full request or response bodies, provider payloads, database rows.
+Follow the secrets rules. Never log secrets, personal data, raw user content, full request or response bodies,
+provider payloads, or database rows.
 
 Redaction lives in the logging module. When a new sensitive key can reach logs, update the redaction list; do not filter at one call site.
 
@@ -49,7 +50,7 @@ Redaction lives in the logging module. When a new sensitive key can reach logs,
 logger.info({ headers: req.headers }, 'Incoming request');
 
 // Good.
-logger.info({ path: req.path, method: req.method, requestId }, 'Incoming request');
+logger.info({ path: req.path, method: req.method, request_id: requestId }, 'Incoming request');
 ```
 
 A logging test asserts the fields and redaction, not that the logger ran.