dw-sdlc 0.0.0-stage → 0.2.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,375 @@
+{
+  "$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
+            },
+            "markdown-budget": {
+              "description": "Each file a glob of `budgets` matches within that glob's `maxLines` and `maxBytes`, and every glob matching a file. A glob matches the files git tracks or would track, a symbolic link left out when the file it points at is matched too; `*` and `**` skip a name that starts with a dot.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "budgets": {
+                  "description": "Default `docs/agents/*.md` within 100 lines and 6144 bytes; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "glob": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "maxLines": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "maxBytes": {
+                        "type": "integer",
+                        "minimum": 1
+                      }
+                    },
+                    "required": ["glob", "maxLines", "maxBytes"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "markdown-refs": {
+              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A link with a scheme, such as `https:`, and a link inside code are not judged.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the markdown files whose links are judged, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files left out. Default none.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "temporal-language": {
+              "description": "No changelog phrase in a durable document, matched across a line break and never inside code: `now we`,`we now`, `we no longer`, `previously we`, `as before`, `were removed`, `was` or `were retired`, `no longer` before `support`, `accept`, `require`, `use`, `fan`, `carry`, `replay`, `incur`, `authoritative`, `insert` or `needed`,`is now a` or `the`, `are now`, `previously a` or `the`, `recently` before `changed`, `added`, `updated`, `removed` or `introduced`, and `used to support` or `require`.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the durable documents, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files that record a point in time. Default `docs/adr/**`, `docs/decisions/**`, `docs/research/**` and `**/CHANGELOG.md`; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "decision-records": {
+              "description": "The records of each directory of `dirs` that exists, the files in it git tracks or would track named `<number>-<slug>.md`: numbered from 1 with no gap and no number taken twice, each with a level-1 heading for its title and a frontmatter `status` whose first word is one of `statuses`, so `superseded by ADR 0008` reads as `superseded`. The Gate cannot run when none of `dirs` exists.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "dirs": {
+                  "description": "The directories of the records, relative to the repository root; one that does not exist holds none. Default `docs/adr` and `docs/decisions`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "statuses": {
+                  "description": "Default `proposed`, `accepted`, `active`, `deprecated` and `superseded`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "file-size-ratchet": {
+              "description": "The file-size Ratchet: each file git tracks or would track within the line limit of its group, or, where `.ai/file-size-ratchet.baseline.json` lists it, within the count recorded there. A file belongs to the first group with a glob that matches it; a file no group matches has no limit, and a symbolic link is left out when the file it points at is matched too. The baseline is committed and lists the files over their limit; one that lists a file twice, at a count within its group's limit or in no group fails the Check. `dw-sdlc gate --update-baseline` records it where there is none and otherwise only tightens it, and only when every Step and every other Check passes: a file within its limit leaves it, a count that shrank is lowered, and no file joins.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "groups": {
+                  "description": "Default, in this order: `tests`, 2000 lines, a file under a `test`, `tests` or `__tests__` directory or named `*.test.*` or `*.spec.*`; `agent-docs`, 120 lines, `AGENTS.md`, `CLAUDE.md` and `GLOSSARY.md` anywhere and the markdown under `docs/agents`; `source`, 500 lines, JavaScript, TypeScript and shell.",
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "description": "The group's name, which its failure lines carry: lowercase words joined by hyphens.",
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+                      },
+                      "maxLines": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "files": {
+                        "description": "Globs against the path from the repository root, as Node's `path.matchesGlob` reads them: `**` crosses directories, but no `*` matches a name that starts with a dot.",
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "minItems": 1,
+                        "uniqueItems": true
+                      }
+                    },
+                    "required": ["name", "maxLines", "files"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "comment-budget": {
+              "description": "The comment budget: each comment block in the JavaScript and TypeScript files under `roots` carries at most `maxProseLines` lines of prose, a line with a letter or a digit once the comment markers are off. A block is one `/* … */` comment or a run of `//` comments each alone on consecutive lines; a comment after code on its line is none.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "maxProseLines": {
+                  "description": "Default 3.",
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "roots": {
+                  "description": "The directories whose files it reads, relative to the repository root; one that does not exist holds no file. Default `packages`, `plugins`, `scripts` and `src`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "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
+  }
+}