@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/profiles/concerns/performance.md

@@ -0,0 +1,54 @@
+# Concern: performance
+
+Taxonomy domains **E** (performance and computational efficiency) and **N** (scalability and
+capacity). Rules in the `PERF-*` namespace.
+
+Enable with `"concerns": ["performance"]`. Checked by `sdlc-code-reviewer`.
+
+## What this concern can and cannot do
+
+It reviews code against standards. **It does not measure.** A performance claim without a
+representative workload is an opinion, and this file will not let a reviewer pretend otherwise:
+every `PERF-*` finding raised by reading is `medium` confidence at most. Measurement is a
+benchmark in `quality.cmd`, or it has not happened.
+
+## Complexity and work per request
+
+- A loop nested inside a loop over user-controlled length is a finding. State the complexity
+  and the input size at which it stops being acceptable.
+- Work that does not depend on the input belongs outside the loop; work that does not depend on
+  the request belongs outside the request.
+- A new allocation, copy or serialisation on a hot path needs a reason. Passing by value what
+  could be borrowed, re-serialising what is already serialised, and parsing the same
+  configuration per call are the usual three.
+
+## Data access
+
+- A query inside a loop is `PERF-N-PLUS-ONE` and is blocking. The fix is one query, not a cache.
+- Every list endpoint is paginated. An unpaginated query over a table expected to grow is
+  blocking, however small the table is today.
+- A new filter or sort on a growing table arrives with its index, or with the reason it does not
+  need one.
+- A cache needs three answers before it is an improvement: what invalidates it, what happens on
+  a miss storm, and what a stale read costs. Without them it is a correctness bug with better
+  latency.
+
+## Network and I/O
+
+- Round trips in series that could be in parallel; payloads that carry fields nobody reads;
+  a retry policy with no jitter. Each is a finding with a named fix.
+- Blocking I/O on an asynchronous path blocks everything sharing that thread. Name the call.
+
+## Scale
+
+- State the limit: at what concurrency, queue depth, connection count or data volume does this
+  stop working? "It scales" is not an answer, and neither is silence.
+- Unbounded concurrency, unbounded queue growth and connection-pool exhaustion are blocking.
+- A hot partition — a tenant, a key, a shard taking disproportionate traffic — is a design
+  finding, not an operations problem.
+
+## The tool beats the opinion
+
+`cargo bench` / criterion, `go test -bench` and `pprof`, `hyperfine`, `pytest-benchmark`,
+Lighthouse or `bundlesize` for the web, `EXPLAIN ANALYZE` for a query. Put the one that fits in
+`quality.cmd` with a budget, and a `PERF-*` finding can finally be `high` confidence.

package/profiles/concerns/platform.md

@@ -0,0 +1,62 @@
+# Concern: platform and low-level correctness
+
+Taxonomy domain **S** (platform-specific and low-level correctness), plus the toolchain half of
+**X8**. Rules in the `PLAT-*` namespace.
+
+Enable with `"concerns": ["platform"]`. Checked by `sdlc-code-reviewer`.
+
+For anything that runs somewhere other than the machine it was written on — which, once there
+is CI, is everything.
+
+## What this concern can and cannot do
+
+Almost everything here is settled by running the code somewhere else, and almost nothing by
+reading it on the machine it was written on. A `PLAT-*` finding from the diff is `medium`
+confidence; a CI matrix that actually fails on another operating system, architecture or
+locale makes it `high`. One failing matrix leg is worth more than this whole file.
+
+## Assumptions about the host
+
+- Path separators, case sensitivity, maximum path length, permitted filename characters. A test
+  that passes on macOS and fails on Linux is usually a case-sensitivity assumption, and the
+  reverse is usually a path-length one.
+- Line endings on anything written, read or compared.
+- A temporary directory is obtained from the platform, never hardcoded to `/tmp`.
+- File permissions, symlink behaviour and atomic rename differ across filesystems. A
+  write-then-rename that is atomic on one is not on all.
+- Environment variables: name the ones required, their defaults, and the behaviour when absent
+  or malformed at startup. Failing at first use instead of at startup turns a configuration
+  error into a 3am page.
+
+## Numbers and encoding
+
+- Integer overflow, underflow and precision loss, especially before an allocation or an index.
+  Say whether the language wraps, traps or is undefined here — the three behave differently
+  and the code usually assumes one.
+- Signed/unsigned conversions and narrowing casts.
+- Endianness and alignment on anything serialised, memory-mapped or sent over a wire.
+- Text is bytes until it is decoded. State the encoding; do not index into a UTF-8 string by
+  byte offset and call it a character.
+
+## Locale and time
+
+- Case conversion, sorting, number and date formatting are locale-dependent. `toUpperCase` on a
+  Turkish locale is the classic. Use an invariant locale for anything the program compares.
+- The system clock moves backwards. A duration measured with a wall clock is not a duration;
+  use a monotonic one.
+
+## Process and toolchain
+
+- Signal handling and shutdown: what happens to in-flight work on SIGTERM?
+- Exit codes mean something to whatever invoked you.
+- Resource limits — open file descriptors, process count — are real and are lower in a
+  container than on a laptop.
+- The toolchain is pinned where the project can pin it. A build that depends on whatever
+  version is installed will differ between a developer's machine and CI, and `ENV-TOOLCHAIN-DRIFT`
+  exists to say so. Native dependencies and cross-architecture builds are where this bites.
+
+## The tool beats the opinion
+
+A CI matrix across the operating systems and architectures you claim to support is worth more
+than this entire file. `cross`, `cibuildwheel`, QEMU runners, `shellcheck` for portable shell,
+and a 32-bit or big-endian target if you claim one.

package/profiles/library.md

@@ -0,0 +1,31 @@
+# Profile: library
+
+For published packages, SDKs and anything whose consumers are other developers.
+
+## The public API is a promise
+
+- Every exported symbol is intentional. A symbol exported by accident is a defect, not a
+  feature, and removing it later is a breaking change.
+- Every exported symbol has documentation that says what it does, what it returns, what it
+  throws or rejects with, and one runnable example.
+- A change to an exported signature, a default, an error type or a thrown condition is a
+  breaking change, whatever the implementation looks like. The specification must say so.
+
+## Versioning
+
+- Semantic versioning, decided from the diff rather than from intent: removed or narrowed →
+  major; added → minor; neither → patch.
+- The changelog entry is written in the same commit as the change, in the consumer's language —
+  what they must do, not what you refactored.
+- Deprecate before removing: a release that warns, then a release that removes.
+
+## Compatibility
+
+- The supported runtime and dependency ranges are stated and tested, not assumed.
+- No new required peer dependency in a minor release.
+- Types ship with the package and are tested by compiling an example consumer.
+
+## Tests
+
+- Public behaviour is tested through the public entry point, not through internals.
+- Every documented example is executed by a test; a broken README example is a bug.

package/profiles/service.md

@@ -0,0 +1,32 @@
+# Profile: service
+
+For long-running network services. The questions are about the second year of operation, not
+the first deploy.
+
+## Failure is specified
+
+- Every outbound call states its timeout, its retry policy and what happens when it exhausts
+  them. "Retry forever" is not a policy.
+- Every failure path either degrades in a stated way or fails loudly. Nothing is swallowed.
+- Partial writes are impossible, or the recovery path is specified and tested.
+- Idempotency: any operation a client may retry states its idempotency key and behaviour.
+
+## Operability
+
+- Every new code path is observable: a log line with the correlation identifier, a metric, or a
+  span. A failure mode that cannot be seen cannot be operated.
+- Logs carry no personal data, credential or full payload by default.
+- A new configuration value has a default, a documented range, and a stated behaviour when
+  absent or invalid at startup.
+
+## Load and limits
+
+- Unbounded allocation, unbounded queues, unpaginated queries and user-controlled loop bounds
+  are blocking findings.
+- A new endpoint states its expected rate and its limit behaviour.
+
+## Change safety
+
+- A schema change is forward and backward compatible across one deploy, or the specification
+  states the ordered migration.
+- Rollback is possible, and the specification says what rolling back loses.

package/profiles/webapp.md

@@ -0,0 +1,40 @@
+# Profile: webapp
+
+For product applications with users, an admin surface and a database. Adds these standards to
+the core rules. They are checked by `sdlc-spec-reviewer` and `sdlc-code-reviewer`.
+
+## Configurability
+
+Anything a non-engineer will want to change — a threshold, a label, a fee, a rate, a status
+name, an email template, a feature flag — is read from configuration or a reference table, and
+is editable through the admin surface. A literal in code for one of these is a blocking finding.
+
+The specification must say which values are configurable. A spec that hardcodes one is
+`changes-requested`.
+
+## Data model
+
+- A new table or column states its purpose, its nullability, its indexes and its retention.
+- Reference data lives in reference tables, not in enums compiled into the application, unless
+  the value is part of the code's own logic.
+- Every migration is reversible, or says explicitly why it is not, and is tested against a
+  database with representative data — not an empty one.
+- No destructive migration without an explicit, separately approved step.
+
+## Interface and accessibility
+
+- Every interactive element is reachable and operable by keyboard, and has an accessible name.
+- Colour is never the only carrier of meaning; contrast meets WCAG AA.
+- Every form field has a label, an error state, and a described validation rule.
+- Loading, empty, error and permission-denied states exist for every view that can reach them.
+
+## Multi-tenancy and authorisation
+
+- Every query that reads tenant data is scoped by tenant, and there is a test that a second
+  tenant cannot read the first's.
+- Authorisation is checked on the server for every mutation, not only hidden in the interface.
+
+## Performance
+
+- No query inside a loop over user-controlled length; no unpaginated list endpoint.
+- A new index accompanies a new filter or sort on a table expected to grow.

package/schema/finding.schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mdferdousalam/agentic-sdlc/schema/finding.schema.json",
+  "title": "agentic-sdlc finding",
+  "description": "One finding, from any agent or any deterministic tool, in the shape every stage can compare. A finding is a claim about the code; this schema is what makes the claim checkable by something other than the agent that made it. Valid JSON is not proof of correct reasoning \u2014 the gate still independently checks the evidence.",
+  "type": "object",
+  "required": [
+    "id",
+    "category",
+    "ruleId",
+    "summary",
+    "evidence",
+    "classification",
+    "outcome",
+    "provenance"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^F-[0-9a-f]{8}$",
+      "description": "Stable identity for this finding, assigned by `sdlc finding write`. Referenced by the commit that closes it."
+    },
+    "category": {
+      "type": "string",
+      "pattern": "^([A-U]\\.(?:[1-9][0-9]{0,2})|X(?:[1-9]|1[0-2]))$",
+      "description": "Taxonomy address. A letter domain plus a check number (`D.31` = Security / injection), or a cross-cutting domain (`X7` = agent economics). Domains are listed in docs/control-spec.md."
+    },
+    "ruleId": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$",
+      "description": "The rule in docs/control-spec.md this finding was raised under, e.g. SEC-INJECTION-SQL. Stable across versions; a renamed rule is a new rule.",
+      "examples": [
+        "SEC-INJECTION-SQL",
+        "TEST-SUITE-WEAKENED",
+        "ARCH-LAYER-DIRECTION"
+      ]
+    },
+    "component": {
+      "type": "string",
+      "description": "The module, package or service the finding belongs to. Free text, but consistent within a repository."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 200,
+      "description": "One sentence stating the defect. Not the fix, not the consequence \u2014 the defect."
+    },
+    "evidence": {
+      "type": "object",
+      "description": "What makes this a finding rather than an opinion. A finding with no evidence is itself a finding against the agent that raised it.",
+      "required": [
+        "file"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Repository-relative path."
+        },
+        "line": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1,
+          "description": "1-indexed line the finding anchors to."
+        },
+        "endLine": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        },
+        "code": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The relevant lines, quoted \u2014 not paraphrased."
+        },
+        "toolOutput": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The deterministic output that supports the claim: compiler diagnostic, analyser line, failing assertion, scanner hit. Null for an llm-detected finding, which is why such findings carry lower confidence by default."
+        },
+        "repro": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The smallest sequence that reproduces it, as commands. The brief's rule: a finding you cannot reproduce may simply be wrong."
+        }
+      }
+    },
+    "classification": {
+      "type": "object",
+      "description": "Severity and confidence are deliberately separate axes. A low-confidence fix for a critical vulnerability is not safe merely because the agent believes it solved the problem.",
+      "required": [
+        "severity",
+        "confidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "severity": {
+          "enum": [
+            "critical",
+            "high",
+            "medium",
+            "low",
+            "advisory"
+          ],
+          "description": "How bad it is if real. critical: auth bypass, data corruption, exploitable injection. high: memory-safety, race, broken authorization, destructive migration. medium: performance regression, missing edge case, incorrect retry. low: formatting, lint, safe mechanical refactor. advisory: a trade-off or a disputed judgement \u2014 report, never force."
+        },
+        "confidence": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ],
+          "description": "How sure we are it is real. high: a deterministic tool said so, or there is a reproduction. medium: strong reading of the code, no execution. low: pattern match or suspicion. Never raise confidence to justify an automatic repair."
+        },
+        "exploitability": {
+          "enum": [
+            "remote",
+            "local",
+            "authenticated",
+            "theoretical",
+            "not-applicable"
+          ],
+          "description": "Security findings only. Describe reachability; never write an exploit."
+        },
+        "impact": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What goes wrong for a user or an operator if this is not fixed."
+        }
+      }
+    },
+    "rootCause": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Why the problem exists, not the visible symptom. A finding with only a symptom tends to produce a symptom-only fix, which is the failure X4 exists to prevent."
+    },
+    "proposedRepair": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "change": {
+          "type": "string",
+          "description": "The minimal change. Not a refactor of the surrounding module."
+        },
+        "expectedBehaviour": {
+          "type": "string",
+          "description": "What is true after the change that is not true now."
+        },
+        "sideEffects": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What else this touches, including anything downstream."
+        },
+        "autofixEligible": {
+          "type": "boolean",
+          "description": "Whether the repair policy in docs/control-spec.md permits an agent to make this change unattended. Derived from severity and confidence together; never from severity alone."
+        }
+      }
+    },
+    "verificationPlan": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The specific test, static check, benchmark or experiment that would establish the repair worked. Written before the repair, so the repair cannot choose its own easy standard."
+    },
+    "outcome": {
+      "enum": [
+        "open",
+        "fixed",
+        "refused",
+        "deferred",
+        "unexecuted",
+        "escalated"
+      ],
+      "description": "open: raised, not yet addressed. fixed: behaviour changed and a test proves it. refused: the finding is wrong, with the evidence. deferred: real, out of scope, filed where it will be seen. unexecuted: the fix could not be verified \u2014 not closed. escalated: awaiting a human decision. These extend the remediator's existing four; the five evidence words (passed/failed/skipped/refused/unexecuted) describe a criterion, not a finding."
+    },
+    "closedBy": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The commit that closed this finding. One finding per commit, so this is a single sha."
+    },
+    "closedByActor": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Who closed it. A finding could previously be closed by any actor with no record of which \u2014 a remediator closing a reviewer's finding looked identical to the reviewer closing their own."
+    },
+    "reopened": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "How many times this finding was closed and then detected again. A non-zero value is the honest signal that a fix did not hold; the first version of the re-raise logic wrote the finding straight back as `fixed` and it vanished from the gate's open list."
+    },
+    "provenance": {
+      "type": "object",
+      "description": "Who claimed this, with what, and against what state. Without it a finding cannot be reproduced or disputed.",
+      "required": [
+        "agent",
+        "at",
+        "commit"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "agent": {
+          "type": "string",
+          "description": "The agent or tool that raised it, e.g. sdlc-security-reviewer, gitleaks."
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The model behind an llm-detected finding, where the host exposes it."
+        },
+        "detection": {
+          "enum": [
+            "deterministic",
+            "test",
+            "runtime",
+            "llm"
+          ],
+          "description": "How it was found. The brief's rule 2: prefer a tool to an opinion, and record which this was so a reader can weigh it."
+        },
+        "toolVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "at": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+        },
+        "commit": {
+          "type": "string",
+          "description": "The commit the finding was raised against. A later commit does not void a finding the way it voids a receipt, but it does mean the line numbers may have moved."
+        }
+      }
+    }
+  }
+}