dw-sdlc 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Woźniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# dw-sdlc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Gate and the agentic config of a repository. `.ai/agentic.config.json` declares how a repository
+works for an agent: its package manager, protected branches, env-file policy, commit convention and
+the Gate. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
+resolver of its layers.
+
+## Install
+
+Node 24 or later.
+
+```sh
+pnpm add -D dw-sdlc
+```
+
+## The Gate
+
+`dw-sdlc gate` runs the Steps under `gate.steps` in order from the repository root, then every Check
+under `gate.checks`. It exits 0 when everything passes, 1 when a Step or a Check fails, and 2 when the
+Gate cannot run. `--json` prints the result as one document.
+
+```json
+{
+  "$schema": "../node_modules/dw-sdlc/config/agentic.config.schema.json",
+  "version": 1,
+  "gate": {
+    "steps": ["pnpm lint", "pnpm typecheck", "pnpm test"]
+  }
+}
+```
+
+```json
+{ "scripts": { "check": "dw-sdlc gate" } }
+```
+
+## Commands
+
+| command            | what it does                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`            |
+| `primitives`       | the Primitives that own each path, with their summaries and documents               |
+| `setup`            | this machine's local config layer, the git excludes and the permission rules        |
+| `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                |
+| `config`           | the resolved agentic config, or one file validated against the schema               |
+| `references sync`  | every declared Reference brought to its ref under `references/`                     |
+| `references setup` | the Router, its table and the ignore rules a repository needs to declare References |
+
+`dw-sdlc <command> --help` gives each one's options.
+
+## The resolver
+
+```ts
+import { resolveConfig } from "dw-sdlc"
+
+const { config, problems } = resolveConfig(process.cwd())
+```
+
+`resolveConfig` merges the committed `.ai/agentic.config.json`, the machine's
+`.ai/agentic.config.local.json` and what it infers from the repository. `problems` names each layer
+that fails the schema; an invalid layer is dropped whole.
+
+## License
+
+MIT

package/config/agentic.config.schema.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/guardrails/config/agentic.config.schema.json",
+  "title": "agentic.config",
+  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` but never loosen it. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "baseBranch": {
+      "description": "The branch pull requests target; `auto` reads the remote's default branch.",
+      "type": "string",
+      "minLength": 1
+    },
+    "packageManagers": {
+      "type": "object",
+      "properties": {
+        "node": {
+          "description": "Inferred from the lockfile. The package-manager guard refuses the other Node package managers only when this is `pnpm`.",
+          "enum": ["pnpm", "npm", "yarn", "bun"]
+        },
+        "ruby": {
+          "description": "Accepted so a repository can declare it; no guard reads it and nothing infers it.",
+          "enum": ["bundler"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "guardrails": {
+      "description": "Policy the local override may tighten and never loosen. Every enum lists its strictest value first.",
+      "type": "object",
+      "properties": {
+        "forcePush": {
+          "description": "`deny` refuses every force push. `lease` lets `--force-with-lease` and `--force-if-includes` through to a branch outside `protectedBranches`; bare `--force` and `-f` stay refused. `ask` is `lease` with a permission prompt for each lease push it lets through. Strictest first: deny, ask, lease.",
+          "enum": ["deny", "ask", "lease"]
+        },
+        "commitOnProtected": {
+          "description": "`deny` refuses a `git commit`, `merge`, `cherry-pick` or `revert` on a branch listed in `protectedBranches`, so every change starts on a branch of its own. `allow` lets it through, for a repository that commits small fixes on its protected branch and pushes them from a person's terminal. Default `allow`. Strictest first: deny, allow.",
+          "enum": ["deny", "allow"]
+        },
+        "envFiles": {
+          "description": "Which env files (`.env`, `.env.*`, `.envrc`) an agent may read, edit or write. A candidate is judged in this order: listed in `deny` → refused; listed in `allow` → readable; `policy` `deny` → refused; `policy` `git` → readable when git tracks it, refused when git ignores it or does not know it. Entries are globs against the path relative to the repository root: `*` and `?` as in a shell pattern (`*` crosses `/`), a leading `**/` means at any depth, so `.env` is the one in the root and `**/.env.example` every file of that name. No brace groups. A path outside the repository root, or outside any repository, is judged by its basename against the `**/` entries alone. Defaults: policy `git`, allow the `.env.example`, `.env.sample` and `.env.template` names anywhere, deny nothing. The local override may drop `allow` entries and add `deny` entries, never the reverse.",
+          "type": "object",
+          "properties": {
+            "policy": {
+              "description": "What decides a candidate no list names. `deny` refuses it; `git` asks git: tracked passes, ignored or unknown is refused.",
+              "enum": ["deny", "git"]
+            },
+            "allow": {
+              "description": "Globs of the env files that are readable regardless of `policy`.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true
+            },
+            "deny": {
+              "description": "Globs of the env files that are refused regardless of `policy`; wins over `allow`.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true
+            }
+          },
+          "additionalProperties": false
+        },
+        "protectedBranches": {
+          "description": "Branches the guards refuse every push to: plain, lease or force. Under `commitOnProtected: deny` they refuse a commit, merge, cherry-pick or revert on one too. The local override may add to this list, never remove from it.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "commit": {
+      "type": "object",
+      "properties": {
+        "convention": {
+          "description": "The subject preset `pattern` falls back to. `ticket-key`: `[KEY-123] type: subject`, the tracker's key in brackets before a type from a fixed list. `conventional`: Conventional Commits; inferred when no layer sets either.",
+          "enum": ["ticket-key", "conventional"]
+        },
+        "pattern": {
+          "description": "POSIX ERE the commit subject must match; set, it wins over `convention`. `grep -E` runs it, so no `\\d`, `\\s`, `\\w`, `\\b` or `(?…)`. `.+` accepts any subject.",
+          "type": "string",
+          "minLength": 1,
+          "format": "regex"
+        },
+        "trailer": {
+          "description": "A trailer key, such as `Co-Authored-By`, that every commit message must carry on a line of its own.",
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9-]*$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "gate": {
+      "description": "The Gate `dw-sdlc gate` runs: the Steps under `steps` in order, then every Check under `checks`.",
+      "type": "object",
+      "properties": {
+        "command": {
+          "description": "The one command that runs the Gate, the same in a terminal and in CI. Inferred as `pnpm check` where `package.json` has a `check` script.",
+          "type": "string",
+          "minLength": 1
+        },
+        "steps": {
+          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`, each one's output passed through; the first that fails ends the Gate and no Check runs. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "checks": {
+          "description": "The Checks the Gate runs after its steps, every one even when another fails: the `run` scripts first, then the Checks the package ships, in the order listed here. A Check the package ships is `true` for its defaults, an options object over them, or `false` to stay off. A key names a Check the package ships, and a name it does not ship is refused.",
+          "type": "object",
+          "properties": {
+            "run": {
+              "description": "The repository's own scripts, each run like a Step and reported as a Check under its `name`: exit 0 passes, 127 or 126 means the Gate cannot run, any other code fails.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "description": "The Check's name, which each of its failure lines carries: lowercase words joined by hyphens.",
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+                  },
+                  "command": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": ["name", "command"],
+                "additionalProperties": false
+              }
+            },
+            "primitives": {
+              "description": "The Primitives catalogue: unique ids, each in a group `groups` lists, a summary of one line within 120 characters, every `code` path on disk, every `docs` path on disk with its heading anchor resolving, and every file under `roots` named by the `code` of a Primitive, itself or a directory above it. A test file, under a `test`, `tests` or `__tests__` directory or named `*.test.*` or `*.spec.*`, needs no Primitive.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "file": {
+                  "description": "The catalogue, relative to the repository root. Default `.ai/primitives.json`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "roots": {
+                  "description": "The directories whose every file a Primitive names, relative to the repository root; one that does not exist names no file. Default `packages`, `plugins`, `scripts` and `src`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "agents-map": {
+              "description": "The agent map: within its line and byte budget, naming the resolved `gate.command`, carrying a Task Router row to the Primitives catalogue where there is one, every path the Task Router points at existing, and the skills directory, `skills-lock.json` and the `.claude/skills` links in step where the repository has them.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "file": {
+                  "description": "The map, relative to the repository root. Default `AGENTS.md`.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "maxLines": {
+                  "description": "Default 150.",
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "maxBytes": {
+                  "description": "Default 10240.",
+                  "type": "integer",
+                  "minimum": 1
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "worktree": {
+      "type": "object",
+      "properties": {
+        "setup": {
+          "description": "Commands a fresh linked worktree needs before work starts. Reported at session start, not run.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/config/references.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/references/config/references.schema.json",
+  "title": "references",
+  "description": "The `references` key of `.ai/agentic.config.json`: the repositories an agent reads to see how a problem was solved before, each brought to its ref under `references/<dir>` by the Sync. Only the committed file is read; the local layer adds no References. Every `dir` is unique in the list, which this schema cannot say and the Sync refuses. A key the Sync refuses syncs nothing.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "dir": {
+        "description": "The one directory under `references/` the clone lives in: letters, digits, `_`, `.` and `-`, not starting with `.` or `-`.",
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
+      },
+      "repository": {
+        "description": "A URL `git` can fetch. A `https://github.com/` one fetches with the GitHub CLI's credentials. No whitespace, and no leading `-`, which `git` would read as an option.",
+        "type": "string",
+        "pattern": "^[^\\s-]\\S*$"
+      },
+      "ref": {
+        "description": "A branch, whose head the clone moves to, or a tag. `{name}` in it stands for the exact version the root `package.json` pins for package `name`, read through the default catalog of `pnpm-workspace.yaml` when the pin says `catalog:` or `catalog:default`. No whitespace, and no leading `-`.",
+        "type": "string",
+        "pattern": "^[^\\s-]\\S*$"
+      },
+      "only": {
+        "description": "Paths the sparse checkout holds beside the repository's top-level files, relative to the clone and inside it; a directory ends in `/`. Absent, the whole tree is checked out. Present, it names at least one path, and a path the ref's tree lacks fails the Reference.",
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "string",
+          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+        }
+      },
+      "skip": {
+        "description": "Paths the sparse checkout leaves out, relative to the clone and inside it. Empty or absent, nothing is left out. With `only`, each lies inside one of its paths, which this schema cannot say and the Sync refuses.",
+        "type": "array",
+        "items": {
+          "type": "string",
+          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+        }
+      },
+      "what": {
+        "description": "What the Reference is.",
+        "type": "string",
+        "minLength": 1
+      },
+      "when": {
+        "description": "When an agent reaches for it.",
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "required": ["dir", "repository", "ref", "what", "when"],
+    "additionalProperties": false
+  }
+}

package/dist/agentic-config.d.ts

@@ -0,0 +1,167 @@
+export declare const COMMITTED_FILE = ".ai/agentic.config.json";
+export declare const LOCAL_FILE = ".ai/agentic.config.local.json";
+/** The schema's path inside this package. */
+export declare const SCHEMA_FILE = "config/agentic.config.schema.json";
+export declare const SCHEMA_PATH: string;
+export declare const COMMIT_CONVENTIONS: readonly ["ticket-key", "conventional"];
+export type CommitConvention = (typeof COMMIT_CONVENTIONS)[number];
+export type NodePackageManager = "pnpm" | "npm" | "yarn" | "bun";
+export type ForcePush = "deny" | "ask" | "lease";
+export type CommitOnProtected = "deny" | "allow";
+export type EnvPolicy = "deny" | "git";
+/** Which env files may be read: `deny` list, then `allow` list, then `policy` for the rest. */
+export type EnvFiles = {
+    policy: EnvPolicy;
+    allow: string[];
+    deny: string[];
+};
+export type Guardrails = {
+    forcePush: ForcePush;
+    commitOnProtected: CommitOnProtected;
+    envFiles: EnvFiles;
+    protectedBranches: string[];
+};
+/** `guardrails` as one layer writes it: every key optional, `envFiles` key by key. */
+export type GuardrailsLayer = Partial<Omit<Guardrails, "envFiles">> & {
+    envFiles?: Partial<EnvFiles>;
+};
+/** A repository's own script under `gate.checks.run`, reported as a Check under `name`. */
+export type RunCheck = {
+    name: string;
+    command: string;
+};
+/**
+ * `run`, and under each other key a Check the package ships, as the schema takes it: `true`, `false` or
+ * its options. `src/checks/` reads the setting of each.
+ */
+export type GateChecks = {
+    run: RunCheck[];
+    [check: string]: unknown;
+};
+/** The Gate: its command, the steps run in order, the Checks run after them. */
+export type Gate = {
+    command?: string;
+    steps: string[];
+    checks: GateChecks;
+};
+/** `gate` as one layer writes it: every key optional, `checks` Check by Check. */
+export type GateLayer = {
+    command?: string;
+    steps?: string[];
+    checks?: Partial<GateChecks>;
+};
+/** One layer as written in a file: every key optional, unknown top-level keys tolerated. */
+export type AgenticConfig = {
+    $schema?: string;
+    version?: 1;
+    baseBranch?: string;
+    packageManagers?: {
+        node?: NodePackageManager;
+        ruby?: "bundler";
+    };
+    guardrails?: GuardrailsLayer;
+    commit?: {
+        convention?: CommitConvention;
+        pattern?: string;
+        trailer?: string;
+    };
+    gate?: GateLayer;
+    worktree?: {
+        setup?: string[];
+    };
+};
+/** What the guards see: every layer applied, every key present. */
+export type ResolvedConfig = {
+    version: 1;
+    baseBranch: string;
+    packageManagers: {
+        node?: NodePackageManager;
+        ruby?: "bundler";
+    };
+    guardrails: Guardrails;
+    commit: {
+        convention: CommitConvention;
+        pattern: string;
+        trailer?: string;
+    };
+    gate: Gate;
+    worktree: {
+        setup: string[];
+    };
+};
+/** The layers merged, before `commit.pattern` falls back to the preset its convention names. */
+type Merged = Omit<ResolvedConfig, "commit"> & {
+    commit: {
+        convention: CommitConvention;
+        pattern?: string;
+        trailer?: string;
+    };
+};
+export type Problem = {
+    file: string;
+    path: string;
+    message: string;
+};
+export type LayerState = "absent" | "valid" | "invalid";
+export type Resolution = {
+    config: ResolvedConfig;
+    problems: Problem[];
+    layers: {
+        committed: LayerState;
+        local: LayerState;
+    };
+    /** The checkout each layer was read from: the root, or the main checkout for a worktree lacking it. */
+    sources: {
+        committed: string | undefined;
+        local: string | undefined;
+    };
+};
+/** Strictest value first; the local override may only move towards the front. */
+export declare const STRICTNESS: {
+    readonly forcePush: readonly ["deny", "ask", "lease"];
+    readonly commitOnProtected: readonly ["deny", "allow"];
+    readonly envFiles: readonly ["deny", "git"];
+};
+/** What the guards run on while any layer is invalid. */
+export declare const STRICTEST_GUARDRAILS: Guardrails;
+/** What a repository gets with nothing declared. */
+export declare const DEFAULT_GUARDRAILS: Guardrails;
+/**
+ * Whether an `envFiles` glob selects the file at `relativePath` (to the repository root, or the
+ * basename outside one). `*` and `?` as in a shell pattern, `*` crossing `/`; a leading `**` and a
+ * slash mean at any depth. The same rule `hooks/block-env-access.sh` applies with `[[ == ]]`.
+ */
+export declare function matchesEnvGlob(glob: string, relativePath: string): boolean;
+export declare const COMMIT_PATTERNS: Record<CommitConvention, string>;
+/**
+ * The schema's public `$id`: what a written config points its `$schema` at. Stable across plugin
+ * installs, where `SCHEMA_PATH` moves with every version.
+ */
+export declare function schemaId(): string;
+/** Parses and validates one document; `file` names it in every problem. */
+export declare function validateDocument(file: string, text: string): {
+    value: AgenticConfig;
+} | {
+    problems: Problem[];
+};
+/** The top level of the repository holding `dir`, or undefined outside one. */
+export declare function findRepository(dir: string): string | undefined;
+/** The top level of the repository holding `dir`, or `dir` itself outside one. */
+export declare function repositoryRoot(dir: string): string;
+/**
+ * The main checkout of the linked worktree at `root`, or undefined for a main checkout or outside a
+ * repository: a linked worktree's git dir differs from the common one, which sits in the main checkout.
+ */
+export declare function mainCheckout(root: string): string | undefined;
+/**
+ * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
+ * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
+ * `resolveConfig`, which fills it from the convention when no layer sets one.
+ */
+export declare function inferConfig(root: string): Merged;
+/**
+ * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
+ * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
+ */
+export declare function resolveConfig(root: string): Resolution;
+export {};