@h2loop/safe-c-coding-plugin 0.3.0 → 0.3.2

package/agents/safe-c-reviewer.md

@@ -2,15 +2,19 @@
 mode: subagent
 displayName: Safe-C Reviewer
 description: >-
-  ALWAYS invoke this subagent once you have written, generated, or modified any C or C++
-  code (.c, .h, .cpp, .hpp), or whenever you want to review existing C/C++ code — do not
-  skip this for one-line changes or code that looks routine. Reviews the code against the
-  safe-c-coding (MISRA C:2012-aligned) guidelines. Given a file, diff, or code range, it
-  scans for undefined behaviour, dynamic allocation, unchecked returns, implicit
-  conversions, missing switch defaults, recursion, and other hazardous constructs, and
-  reports each as "severity — file:line — what's wrong -> safe fix". Use it to audit
-  hand-written or generated C/C++ before it lands, especially for embedded / safety-critical
-  targets.
+  Invoke this subagent for C or C++ code (.c, .h, .cpp, .hpp) only — never for other
+  languages. Frequency depends on task size: for a single small edit (one step, a handful
+  of lines), a self-audit against the safe-c-coding skill's checklist is normally enough
+  and this subagent is optional extra assurance. For a multi-step task with several
+  planned edits and/or files, invoking this subagent is mandatory — but exactly ONCE, as
+  the final step after every planned edit is done, covering the whole changed set. Do not
+  invoke it after each individual step — that is the aggressive, slow pattern to avoid.
+  Reviews the code against the safe-c-coding (MISRA C:2012-aligned) guidelines. Given a
+  file, diff, or code range, it scans for undefined behaviour, dynamic allocation,
+  unchecked returns, implicit conversions, missing switch defaults, recursion, and other
+  hazardous constructs, and reports each as "severity — file:line — what's wrong -> safe
+  fix". Use it to audit hand-written or generated C/C++ before it lands, especially for
+  embedded / safety-critical targets.
 permission:
   # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast
   # (last matching rule wins), so "*": deny MUST precede the allows or it overrides them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h2loop/safe-c-coding-plugin",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Safe-C coding plugin for Hydron — MISRA C:2012-aligned defensive C/C++ guidelines as an always-on skill plus a safe-c-reviewer subagent",
   "type": "module",
   "license": "UNLICENSED",

package/plugins/index.ts

@@ -3,10 +3,13 @@ import type { Plugin } from "@kilocode/plugin"
 export const SafeCCodingPlugin: Plugin = async () => ({
   "experimental.chat.system.transform": async (_input, output) => {
     output.system.push(
-      "Before writing, generating, modifying, or reviewing any C or C++ code " +
-        "(.c, .h, .cpp, .hpp), invoke the safe-c-coding skill. After writing or " +
-        "modifying C/C++ code, invoke the safe-c-reviewer subagent. Do this even " +
-        "for a one-line change or code that looks routine.",
+      "Before writing, generating, modifying, or reviewing C or C++ code only " +
+        "(.c, .h, .cpp, .hpp — not other languages), invoke the safe-c-coding skill " +
+        "and follow it so the code is MISRA-aligned on the first pass. For a single " +
+        "small edit, that first pass plus your own re-read is enough — do not also " +
+        "call the safe-c-reviewer subagent. For a multi-step C/C++ task, do not review " +
+        "after each step; add exactly one safe-c-reviewer call as the final step, " +
+        "after all planned edits are done, covering everything changed.",
     )
   },
 })

package/skills/safe-c-coding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: safe-c-coding
-description: ALWAYS invoke this skill before writing, generating, modifying, or reviewing any C or C++ code (.c, .h, .cpp, .hpp) — no exception for one-line changes, snippets, or code that looks routine. Applies especially to embedded, automotive, medical, aerospace, or other safety-critical or resource-constrained targets where reliability, determinism, and freedom from undefined behaviour matter, but the mandatory-invocation rule applies to all C/C++ work.
+description: ALWAYS invoke this skill before writing, generating, modifying, or reviewing any C or C++ code (.c, .h, .cpp, .hpp) — no exception for one-line changes, snippets, or code that looks routine. Scope is per file, not per project or per task — do not invoke it for code in other languages (Python, JS/TS, Rust, Go, shell, build/config, etc.), even inside a project that also contains C/C++. Applies especially to embedded, automotive, medical, aerospace, or other safety-critical or resource-constrained targets where reliability, determinism, and freedom from undefined behaviour matter, but the mandatory-invocation rule applies to all C/C++ work.
 ---
 
 # Safe C Coding
@@ -22,8 +22,8 @@ Short list, verified on every function you write or edit. Everything else lives
 3. **No dynamic memory, recursion, VLAs, `exit`/`abort`/`longjmp`, or unbounded string functions** — use the substitutes in guidelines.md.
 4. **No implicit narrowing and no signed/unsigned mixing** — every conversion explicit.
 5. **Braces on every body, a `default` on every `switch`, every return value used or `(void)`-discarded.**
-6. **Every identifier you reference is one you have actually read in a declaration.** Before writing a macro, struct or union member, type, enum constant, global, or function name that this file does not itself define, find its declaration in the headers and context you were given, and copy the spelling from there. Names that feel like they *must* exist — a size or count macro accompanying a table, a member named after the quantity it holds, an obvious-looking helper — very often do not, and a plausible invented name is a compile error, not a style blemish. Note in particular that a length may be exposed as a variable rather than a macro, and that a member's name usually describes its slot, not its physical meaning. If you cannot find a declaration for something you need, say so rather than guessing at it.
-7. **Every guard you add must be able to fail.** Before testing a value against zero, NULL, or a range limit, establish what the value actually is. If it is fixed at compile time — a macro expanding to a literal expression, an enum constant, a `sizeof`, a `const` object with a visible initialiser, the address of a declared object or array — then the test has one permanent answer, and an always-true or always-false controlling expression is a required-rule violation (dead code), not extra safety. Guard the things that genuinely vary at run time: parameters, values read from globals or hardware, results of computation. If the worry is that a *configured constant* could be set wrongly, check it at compile time with `#if` or a static-assertion idiom, which costs nothing at run time and cannot be dead code. This does **not** loosen items 1 and 2: an index or pointer that arrives as a parameter, or is read from a global, a struct, or a device, is precisely the varying kind, and still needs its real `if` guard. The two rules point the same way — put guards where a value can actually surprise you, and nowhere else.
+6. **Every identifier you reference is one you have actually read in a declaration.** A plausible invented name — a size/count macro that feels like it must accompany a table, a member named after the quantity it holds rather than its declared name — is a compile error, not a style blemish. Full rule: see guidelines.md § General.
+7. **Every guard you add must be able to fail.** A guard whose tested value is fixed at compile time (a macro, enum constant, `sizeof`, `const` with a visible initialiser, a declared object's address) has one permanent answer — that's an always-true/-false controlling expression, a dead-code violation, not extra safety; check it with `#if`/a static assertion instead. This does **not** loosen items 1 and 2: a value that arrives as a parameter or is read from a global, struct, or device is precisely the varying kind and still needs its real `if` guard. Full rule: see guidelines.md § Control flow.
 
 Where one of these clashes with the surrounding house style, follow the guideline in the code you write and note the divergence in one line.
 
@@ -41,7 +41,7 @@ The full guideline catalogue is in **[guidelines.md](guidelines.md)**.
 
 1. Read guidelines.md in full — before drafting any code, not after.
 2. Choose the safe pattern from the start: static allocation over `malloc`, braced bodies, explicit types, checked return values, a `default` in every `switch`, no recursion, guarded array/pointer access.
-3. Run the **self-audit** below on the code you just wrote, before you save or present it. This step is not optional and not a formality — it is where most violations are actually caught.
+3. Run the **self-audit** below, sized to the task — see that section for which mode applies. This step is not optional and not a formality, but it is not a per-step gate either: a multi-step task gets one audit at the end, not one after every edit.
 4. If a hazardous construct is genuinely unavoidable, don't hide it — call it out and explain why, with a documented justification.
 5. If the project has a MISRA compliance checker (e.g. Cppcheck, Parasoft C/C++test, Helix QAC) and you don't already know how to invoke it for this project, ask the developer for the exact command to run it — then run it against the code you wrote and fix what it reports.
 
@@ -53,16 +53,16 @@ The code already in the file, the neighbouring functions, and the project's hous
 - Do **not** inherit its *hazardous constructs*. "The function next to mine does it this way" is not a justification, and a static-analysis tool will not accept it — each construct is judged on its own.
 - You will often be told not to modify existing code. That constrains what you may change; it does not license writing new non-compliant code that imitates it. Write the compliant form in the code you own, and note the divergence in one line if it looks inconsistent.
 
-### Self-audit (run on your own diff, before saving)
+### Self-audit — one pass, sized to the task
 
-Do this as a **separate pass with fresh eyes**, not as a mental note while writing — the audit only catches anything if it actually re-reads the code. Two acceptable forms, in order of preference:
+Do this as a **separate pass with fresh eyes**, not as a mental note while writing — the audit only catches anything if it actually re-reads the code. Pick the mode by the shape of the task, not by habit: auditing after every single step of a multi-step task is the slow, aggressive pattern this section replaces.
 
-- Delegate the code you just wrote to the **safe-c-reviewer** subagent (bundled with this skill) and fix every Critical and Standard finding it reports.
-- If no subagent is available, re-read the edited region with the read tool — reading it back is part of the step — and work through the checklist below line by line.
+- **Single small change** (one edit step, a handful of lines, one function): no subagent call. Re-read the edited region with the read tool — reading it back is part of the step — and work through the checklist below line by line yourself, before you save.
+- **Multi-step task** (several planned edits and/or files touching C/C++): don't audit after each step. Write every step compliant the first time using the guidelines above, then add exactly **one** extra step at the end of the task, after all planned edits are done, that delegates the full set of changed C/C++ files or diff to the **safe-c-reviewer** subagent and fixes every Critical and Standard finding it reports. That final review is the task's last step, not a gate between steps — do not call the subagent again until the whole task's edits are complete.
 
-Either way the pass is required before you save the file or report the work as done. A summary that says the code is compliant without a re-read behind it is not an audit.
+Either way the pass is required once before you save the file(s) or report the work as done — never zero times, and never once per edit. A summary that says the code is compliant without a re-read or reviewer pass behind it is not an audit.
 
-Walk the lines you wrote — not the whole file — and answer each question explicitly, by re-reading the code rather than from memory of what you intended.
+Walk the lines that changed since the task started (or, if delegating, since the last review) — not the whole file — and answer each question explicitly, by re-reading the code rather than from memory of what you intended.
 
 1. **Every array subscript and pointer dereference**: list them. For each, name the enclosing `if` or loop condition that proves the index is in range and the pointer is non-NULL *on that path*. If the only thing between the access and undefined behaviour is an assertion macro, a comment, a caller's promise, or a convention copied from nearby code, then it is unguarded — add a real guard.
 2. **Every name you did not define in this file**: list the macros, struct/union members, types, enum constants, globals, and functions your new code references. For each, name the header or context file whose declaration you actually read. Any name you produced from memory, from the shape of a sibling name, or because it seemed like it ought to exist is unverified — go and find its declaration, and correct the spelling to match. This is a five-second check that prevents code that cannot compile.
@@ -72,7 +72,7 @@ Walk the lines you wrote — not the whole file — and answer each question exp
 6. **Every branch construct**: braced bodies, a `default` in every `switch`, a terminating `else` where the chain must be exhaustive.
 7. **Anything on the banned-facility list** (dynamic memory, recursion, VLAs, `exit`/`abort`/`longjmp`, unbounded string functions): replaced by its substitute, or deviated from with a written justification.
 
-State the result of the audit in one or two lines before you finish, so the check is visible rather than assumed.
+State the result of the audit before you finish the task: for every Critical or Standard finding raised — by the reviewer subagent or by your own re-read — name the finding and the specific edit that resolved it. "Audit passed" or "no issues found" with no re-read behind it is not an audit; a finding with no matching fix next to it is not an audit either.
 
 ## Preferred patterns