@caddis/cli 0.4.23 → 0.4.25

package/bundles/codex/.codex/skills/devops/adopt-app/profiles/static-site/profile.json

@@ -0,0 +1,87 @@
+{
+  "name": "static-site",
+  "status": "draft",
+  "description": "A static site or a statically-generated site (for example built with a static-site generator, or plain HTML/CSS/JS) with no backend process of its own.",
+  "detect": {
+    "anyFiles": [
+      "index.html",
+      "astro.config.mjs",
+      "astro.config.ts",
+      "gatsby-config.js",
+      "next.config.js",
+      "hugo.toml",
+      "hugo.yaml",
+      "_config.yml",
+      "mkdocs.yml",
+      "docusaurus.config.js",
+      "vuepress.config.js"
+    ],
+    "noneFiles": [
+      "pyproject.toml",
+      "requirements.txt",
+      "composer.json",
+      "index.php",
+      "**/*.csproj",
+      "pom.xml",
+      "build.gradle",
+      "build.gradle.kts"
+    ],
+    "noneContain": [
+      {
+        "file": "package.json",
+        "pattern": "\"(express|fastify|hono|@nestjs/core|koa)\""
+      }
+    ]
+  },
+  "runtimes": [
+    {
+      "kind": "node",
+      "version": "<from package.json engines, if a generator is used to build the site>",
+      "provision": "<needed only at build time, not to serve the finished site>"
+    }
+  ],
+  "build": [
+    {
+      "what": "Dependencies, if the site is generated",
+      "command": "npm ci"
+    },
+    {
+      "what": "Generate the static output",
+      "command": "npm run build"
+    }
+  ],
+  "services": [
+    {
+      "role": "web",
+      "port": "<the site's HTTP port, if served by a small process rather than a CDN or web server>",
+      "start": "<a static file server, or the site is served directly by a web server / CDN with no process of its own>",
+      "manager": "<a service manager, or none if a web server serves the files directly>",
+      "bind": "<loopback-only, if a trusted edge fronts it>",
+      "health": "<the home page returns 200 with the expected content>"
+    }
+  ],
+  "routing": {
+    "mode": "<dedicated-site|none>",
+    "staticRoot": "<the built output folder, e.g. dist or public>",
+    "apiPrefix": "<n/a>"
+  },
+  "config": {
+    "files": ["<build-time environment variables, if any>"],
+    "rule": "no secrets belong in a static bundle - anything shipped to the browser is public"
+  },
+  "data": {
+    "migrations": "none",
+    "state": "none - the site is a build artefact; content lives in the source repo or a content system, not on the serving host"
+  },
+  "ci": {
+    "workflow": "<CI workflow file: lint, build>",
+    "requiredJobs": ["<build>"],
+    "deployJob": "<deploy_prod>"
+  },
+  "deploy": {
+    "script": "<deploy script: build, then publish the output folder to where it is served from>",
+    "verify": [
+      "a rendered page's content or the build output's hash changed - not just an HTTP 200 from the serving host"
+    ]
+  }
+}

package/bundles/codex/.codex/skills/devops/adopt-app/references/config.example.json

@@ -0,0 +1,18 @@
+{
+  "outDir": ".caddis/adopt",
+  "fileBudget": 20000,
+  "skipFolders": [],
+  "skipPattern": "(?i)[\\\\/](\\.git|node_modules|\\.venv|venv|__pycache__|\\.mypy_cache|\\.pytest_cache|\\.tox|dist|build|target|bin|obj|vendor|packages|\\.terraform|\\.gradle|\\.next|\\.nuxt|coverage)([\\\\/]|$)",
+  "expectedRemotePattern": "^https://github\\.com/example-org/",
+  "untrackedThresholdMB": 10,
+  "_comments": {
+    "_read_this_first": "Copy this to .caddis/adopt-app.json in the repo you run the skill from, or point $env:ADOPT_APP_CONFIG at a copy elsewhere, then edit the values. JSON has no comment syntax, so this _comments object exists only to explain the keys above. Get-AdoptConfig merges every top-level key of your file over the defaults; nothing reads a key named _comments.",
+    "_every_key_is_live": "Each key below is read by a named script. There are deliberately no others. An earlier version of this file also listed blockingItems and contentPolicy, which no script ever consulted - a project could set them, see no effect and never find out. Config that does nothing is a promise the code does not keep, so those keys were removed from the code and from here together.",
+    "outDir": "Where phase output goes, relative to the repo root: <outDir>/<name>/inventory.json and the rest. Read by Resolve-AdoptOutDir, and only when a phase script runs without its own -OutDir.",
+    "fileBudget": "How many files the scan will walk per top-level folder before it stops. Read by Get-AppInventory.ps1 when -FileBudget is not passed; the parameter always wins. Reaching the budget does not fail quietly: the folder's size becomes a MINIMUM, the scan is marked partial, and the script exits 1 unless you pass -AllowPartial.",
+    "skipFolders": "Top-level folder names never walked at all. Read by Get-AppInventory.ps1 when -SkipFolder is not passed. Use it for a tree you already know is bulk data, so the budget is spent where the answer is still open. A skipped folder is recorded as NOT SCANNED, never as empty, and it stops source-only, runtime-manifest and data-recovery from passing.",
+    "skipPattern": "Paths whose CONTENTS are not classified - dependency folders, build output, caches. They are still measured for size and still classified as excludable content, but their files are not read for credentials or indexed for stack detection. Read by Get-AppInventory.ps1 and passed to Invoke-AdoptScan.",
+    "expectedRemotePattern": "The regex that means 'the team's host'. Read by Test-AppConformance.ps1 for the remote-on-team-host item: a repository whose remote URL does not match is a GAP even though it has a remote, which is how a repository sitting on someone's personal account gets caught. Leave it empty and any remote passes, because the check will not guess.",
+    "untrackedThresholdMB": "A folder that is neither committed nor ignored and is at least this large is a finding. Read by Test-AppConformance.ps1 when -UntrackedThresholdMB is not passed. This is the state that turns one 'git add -A' into gigabytes of runtime data in the history for ever, and no filename pattern finds it - only git can."
+  }
+}

package/bundles/codex/.codex/skills/devops/adopt-app/references/profile-contract.md

@@ -0,0 +1,207 @@
+# The profile contract
+
+A profile describes one KIND of component, not one app. It lives at
+`profiles/<stack-name>/profile.json`. `profiles/_template/profile.json` is the starting point
+for a new one, and phase 2 (`Resolve-AppProfile.ps1`) never matches `_template` itself against a
+real inventory unless something explicitly asks `Get-AdoptProfiles` for it with
+`-IncludeTemplate`.
+
+Every profile file is loaded and checked against this contract BEFORE any detection runs, by
+`Test-AdoptProfileContract` in `AdoptCommon.ps1`. **One broken profile fails detection for every
+app being resolved, not just the one that owns it** - `Resolve-AppProfile.ps1` refuses to run at
+all while any profile under `profiles/` fails the checks below.
+
+## Required keys
+
+All ten must be present. The contract only checks that the key EXISTS; it does not validate the
+shape of what is inside it.
+
+| Key | Meaning |
+|---|---|
+| `name` | The stack's short name, e.g. `node-service`. Matches the folder name by convention. |
+| `status` | `proven`, `draft`, or `placeholder`. See below. |
+| `description` | One sentence: what kind of component this is. |
+| `detect` | The rules that decide whether a component folder is this stack. See below. |
+| `runtimes` | The language/runtime(s) it needs: kind, exact version, and how that version gets onto a box. |
+| `build` | The ordered build steps: what each one does and the command. |
+| `routing` | How traffic reaches it: reverse proxy, a rewrite rule, a dedicated site, or none. |
+| `config` | Which files carry per-environment settings, and the rule that keeps them out of version control. |
+| `data` | The migration tool, if any, and where persistent state actually lives. |
+| `ci` | The CI workflow file, the jobs that must pass, and which job deploys. |
+| `deploy` | The deploy script, and at least one check that would FAIL on a broken deploy. |
+
+**Plus one rule that is not a top-level key check:** the profile must also carry `services` or
+`schedule` (or both).
+
+- `services` describes a component that answers requests. Each entry names a role
+  (`api`/`web`/`worker`/`database`), a port, a start command, the process manager that keeps it
+  running, the interface it binds, and a health check.
+- `schedule` describes a batch component instead: what triggers a run - a scheduler, a
+  file-arrival watcher, or a manual/CI trigger.
+
+A component that is neither long-running nor scheduled does not fit this contract yet.
+
+## Status values
+
+| Status | Licenses |
+|---|---|
+| `placeholder` | Only `_template`'s own state. Its `name` is still the literal `<stack-name>` placeholder text - which is exactly why the "no leftover placeholder" rule below is skipped for `placeholder` alone. |
+| `draft` | A description a person can follow by hand. It can still be DETECTED and matched to a real component - phase 2 will report it, with its status shown as `draft` - but nothing has automated it end to end yet. Follow it manually, write down what you actually did, and let it earn `proven` later. |
+| `proven` | Something has actually automated this stack end to end: build, deploy and verify have all been run for real against a live component, not only described. |
+
+Two more rules `Test-AdoptProfileContract` enforces on `status`:
+
+- It must be exactly one of the three values above. Anything else fails the contract for every
+  profile in the directory, not only this one.
+- Unless `status` is `placeholder`, `name` must not contain `<` or `>`. This is what stops a copy
+  of `_template` being left half-filled-in and silently matching real apps with its placeholder
+  name still inside it.
+
+## The five `detect` rule kinds
+
+Checked by `Test-AdoptDetect`, against two things gathered per component: a list of relative
+file paths, and the text of a handful of small files. Which files make it into either list is
+bounded - see "What `detect` can actually see" below.
+
+| Kind | Shape | Meaning |
+|---|---|---|
+| `allFiles` | list of globs | Every glob must match at least one path, or the profile does not match at all. |
+| `anyFiles` | list of globs | At least one glob must match at least one path, or the profile does not match at all. |
+| `noneFiles` | list of globs | If ANY glob matches, the profile does not match at all. A pure veto - it never adds to the score. |
+| `fileContains` | list of `{ "file": glob, "pattern": regex }` | Every entry's glob must resolve to a file whose text matches `pattern`, or the profile does not match. |
+| `noneContain` | list of `{ "file": glob, "pattern": regex }` | If any entry's glob resolves to a file whose text matches `pattern`, the profile does not match. A pure veto. |
+
+All five are optional; omit whichever a stack does not need. A profile that declares none of them
+never matches anything.
+
+## Glob-to-regex translation, exactly
+
+Every glob - in `allFiles`, `anyFiles`, `noneFiles`, or a `fileContains`/`noneContain` entry's
+`file` - goes through the same conversion, in this order:
+
+1. `[regex]::Escape($glob)` - escape every regex-special character literally, including `*`.
+2. Replace an escaped `**` (now `\*\*`) with `.*` - matches across any number of path segments.
+3. Replace a remaining escaped `*` (`\*`) with `[^\\/]*` - matches within ONE path segment only.
+4. Replace `/` with `[\\/]` - so a glob written with a forward slash matches a path recorded
+   with either separator.
+5. Anchor the whole thing as `(?i)^...$` - case-insensitive, and the WHOLE relative path must
+   match, not a substring of it.
+
+So `src/*.ts` matches `src/index.ts` but not `src/api/index.ts` (one segment only), while
+`src/**/*.ts` matches both. A bare filename like `package.json` matches only at the root of the
+component being tested, not at any depth beneath it - write `**/package.json` for "anywhere
+under this component."
+
+## How the score is computed
+
+`Test-AdoptDetect` returns `0` for no match, or a positive score where a higher number means a
+more specific match:
+
+- `allFiles` declared and satisfied -> **+1**. Declared and NOT satisfied -> return `0`
+  immediately, regardless of anything else.
+- `anyFiles` declared and satisfied -> **+1**. Declared and NOT satisfied -> return `0`
+  immediately.
+- `fileContains` declared and satisfied -> **+1**. Declared and NOT satisfied -> return `0`
+  immediately.
+- `noneFiles` and `noneContain` never add to the score. They are vetoes only: if either is
+  violated, the rule returns `0` no matter what else matched.
+
+The maximum score is `3` (`allFiles` + `anyFiles` + `fileContains` all declared and all
+satisfied). Phase 2 runs every profile against every component and keeps the highest-scoring
+match as the winner. Everything else that scored above `0` is recorded in `alsoMatches`, never
+discarded - a component genuinely matching two stacks is a decision for a person, and picking one
+silently would hide that decision.
+
+## What `detect` can actually see
+
+A rule can only use evidence the inventory actually indexed. Two different limits apply,
+depending on what kind of file a glob names.
+
+- **Manifests, entry points, config files, CI files, docs, and test markers** - anything matching
+  one of the fixed name lists `Get-AppInventory.ps1` already recognises (`package.json`,
+  `pyproject.toml`, `Dockerfile`, `main.py`, `.env*`, a file under a `workflows` folder,
+  `README*`, `pytest.ini`, and the rest) - are indexed at ANY depth in the tree.
+- **Everything else** - an arbitrary filename a `detect` rule names that is not one of those
+  fixed names, for example `index.html` as evidence of a front end - only lands in the general
+  shallow path index, and that index is depth-limited: paths at depth 2 or shallower from the
+  scanned root are always kept; paths at depth 3-4 are kept only while a single cap shared across
+  the WHOLE scan (`DetectPathCap`, default 20000 paths) still has room. Past depth 4, or once
+  that cap is spent, a `detect` rule naming such a file cannot see it - not because the file is
+  absent, but because nothing recorded that it exists.
+
+`fileContains`/`noneContain` add a second limit on top of path indexing: the named file must
+actually be fetched, which only happens for files under 256 KB. A rule that reads a large
+generated file will never see its content.
+
+**Practical rule of thumb:** name a real manifest or entry-point filename in
+`allFiles`/`anyFiles` whenever the stack has one - that evidence survives at any depth. Reserve
+arbitrary, non-manifest filenames for secondary evidence, and expect them to be missed on a
+deeply nested component or a very large tree.
+
+## Worked example: adding a new stack
+
+Say a fleet starts running a Rust service and no profile describes it yet. Phase 2 would report
+"NO PROFILE MATCHED ANY FOLDER" and exit 2 for that component.
+
+1. Copy the template:
+
+       cp -r profiles/_template profiles/rust-service
+
+2. Fill in `profiles/rust-service/profile.json`. Start with `status: "draft"` - nothing has
+   automated this stack yet, only described it:
+
+       {
+         "name": "rust-service",
+         "status": "draft",
+         "description": "A Rust HTTP service built with Cargo, e.g. Actix Web or Axum.",
+         "detect": {
+           "allFiles": ["Cargo.toml"],
+           "fileContains": [
+             { "file": "Cargo.toml", "pattern": "(actix-web|axum|rocket)" }
+           ]
+         },
+         "runtimes": [
+           {
+             "kind": "rust",
+             "version": "<from Cargo.toml or rust-toolchain.toml>",
+             "provision": "<installed on dev and prod hosts; confirm the installed version matches what is declared>"
+           }
+         ],
+         "build": [
+           { "what": "Compile", "command": "cargo build --release" }
+         ],
+         "services": [
+           {
+             "role": "api",
+             "port": "<the app's HTTP port>",
+             "start": "<the built binary, e.g. target/release/app>",
+             "manager": "<a service manager or a container runtime>",
+             "bind": "<loopback-only, unless a trusted edge forwards identity>",
+             "health": "<the app's real health route - confirm it, do not assume a default path>"
+           }
+         ],
+         "routing": { "mode": "reverse-proxy", "apiPrefix": "/api" },
+         "config": {
+           "files": ["<the env file it reads, per environment>"],
+           "rule": "kept out of version control; a committed example file with placeholder values"
+         },
+         "data": {
+           "migrations": "<its migration tool, if any>",
+           "state": "<where persistent state actually lives>"
+         },
+         "ci": {
+           "workflow": "<CI workflow file>",
+           "requiredJobs": ["<build_and_test>"],
+           "deployJob": "<deploy_prod>"
+         },
+         "deploy": {
+           "script": "<deploy script>",
+           "verify": ["<a check that would FAIL on a broken deploy>"]
+         }
+       }
+
+3. Re-run phase 2. If a real component's `Cargo.toml` mentions `axum`, it now scores `2`
+   (`allFiles` + `fileContains`) and is reported with `status: draft`.
+4. Follow the profile by hand on a real adoption. Write down what was actually done for build,
+   deploy and health, then raise `status` to `proven` only once all of it has genuinely been
+   automated - not before.

package/bundles/codex/.codex/skills/devops/adopt-app/references/standard.md

@@ -0,0 +1,304 @@
+# The adoption standard
+
+`Test-AppConformance.ps1` (phase 3) measures an app against 20 items, in the order below - the
+same order the script adds them in. Each one gets a verdict, never a guess:
+
+| Verdict | Means |
+|---|---|
+| `PASS` | Observed true, from the inventory or the profile. |
+| `GAP` | Observed false. The evidence is named. |
+| `ASK` | Not observable from files. A person must answer it. |
+| `ANSWERED` | Was `ASK`; a non-empty answer has been recorded for it (see below). Not a fourth independent state - it only exists once an `ASK` has been answered. |
+
+Items marked **blocking** below stop the adoption exactly the same way whether they are `GAP` or
+an unanswered `ASK` - a checklist that only tracks blocking failures and lists open questions as
+notes at the bottom lets those questions be skipped, which is the failure this standard exists to
+prevent.
+
+---
+
+### 1. `git-repo` - The source is in a git repository
+
+**Blocking.**
+
+**Decided by:** `PASS` if the source folder contains a `.git` directory (`inventory.git.isRepo`
+is true). `GAP` otherwise, with "no `.git` in the source folder" as the evidence.
+
+**Why it is on the list:** an app with no repository has no history and no way to see what
+changed. Adoption starts by importing the folder as one commit - but only once the content
+policy (item 4) is settled, because that first commit decides what is in the history forever.
+
+### 2. `remote-on-team-host` - The repository lives on the team's host
+
+**Blocking.**
+
+**Decided by:** `GAP` if there is no repository at all; `GAP` if a repository exists but has zero
+remotes configured ("this folder is the ONLY copy of the history"); `GAP` if
+`expectedRemotePattern` is set in the config and none of the remote URLs match it; `PASS` if a
+remote exists and either no pattern is configured or one remote matches it.
+
+**Why it is on the list:** a repository with no remote, or hosted on a personal account, is one
+disk failure or one departure away from disappearing. `expectedRemotePattern` is what lets this
+check tell "the team's host" from "somewhere else" - without it configured, having any remote at
+all is enough to pass, which is a weaker check than it looks like.
+
+### 3. `canonical-branch` - Which branch is the truth is written down
+
+**Blocking.**
+
+**Decided by:** `ASK` when the app has a repository AND (it has no remote, OR it has more than 3
+local branches). `PASS` otherwise. Note the edge case this produces: when there is no repository
+at all, this item reads `PASS` (evidence: "no repository") even though `git-repo` itself is a
+`GAP` for the same app - there being no branches yet is not treated as a question to ask.
+
+**Why it is on the list:** with more than a handful of local branches and no shared remote to
+compare against, which one is actually deployed cannot be read from the files. Wiring CI to the
+wrong branch before this is answered means CI builds and tests code nobody ships.
+
+### 4. `source-only` - The repository holds source, not runtimes, data or dependencies
+
+**Blocking.**
+
+**Decided by:** `GAP` if either of these is true: a top-level folder that IS git-tracked also
+matches an excludable content category (dependency, runtime, build-output, cache, db-data,
+archive, data-export, or media - `log` is exempted here) - i.e. something was committed that
+should not have been; or a top-level folder is git-UNTRACKED, is not `.git`, and is at least
+`-UntrackedThresholdMB` (default 10 MB). Otherwise `PASS` - except a `PASS` is downgraded to
+`ASK` if any top-level folder was scanned with `-SkipFolder` (see "Coverage" below).
+
+**Why it is on the list:** a `.gitignore` added later does not remove what is already committed -
+that needs a history rewrite. And a folder that is neither committed nor ignored is the genuinely
+dangerous state: it sits there doing nothing until one `git add -A` puts it in the history
+forever. A filename pattern cannot find that state; only asking git can.
+
+### 5. `no-secrets` - No credential is in the working tree
+
+**Blocking.**
+
+**Decided by:** `GAP` if the inventory's `secretsSuspected` list is non-empty (files flagged by
+name, e.g. `.env`, `*.pem`, `id_rsa`, `credentials.json`; or by content, e.g. a line shaped like
+`password = "..."` or a live-looking token, with comments, non-literal values, and template
+references excluded). `PASS` if the heuristics found nothing - which the evidence text says
+explicitly is not proof there is nothing.
+
+**Why it is on the list:** history keeps a credential, so the fix is to ROTATE it, not delete it.
+Deleting the file in a later commit does not stop anyone who already has a clone, or ever will,
+from reading the old value out of history. Only rotating the credential itself closes that.
+
+### 6. `config-separation` - Configuration is outside the code, per environment
+
+**Not blocking.**
+
+**Decided by:** `PASS` if at least one config file looks like a committed template (matches a
+name like `.env.example`, `*.sample`, `*.template`, or `*.dist`). `ASK` if the inventory found
+zero config files at all. `GAP` if config files exist but none of them look like a template.
+
+**Why it is on the list:** hardcoded, per-environment values in committed config are exactly
+where a real credential tends to leak. A committed template proves the separation exists without
+exposing a real value; its absence does not prove the opposite, which is why zero config files
+reads as a question rather than a pass or a fail.
+
+### 7. `deps-pinned` - Dependencies are pinned
+
+**Not blocking.**
+
+**Decided by:** `PASS` if a recognised lock file is present among the manifests
+(`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `poetry.lock`, `Pipfile.lock`,
+`composer.lock`, `Gemfile.lock`, `Cargo.lock`, `go.sum`). `GAP` otherwise.
+
+**Why it is on the list:** without a lock file the build is not reproducible, and a broken deploy
+cannot be told apart from a dependency that moved underneath it between two runs.
+
+### 8. `tests` - There is an automated test suite
+
+**Not blocking.**
+
+**Decided by:** `PASS` if the inventory's test-file count is greater than zero (files under a
+`tests`/`spec`/`__tests__` folder, or matching a test-name convention like `*_test.py` or
+`*.spec.ts`). `GAP` otherwise.
+
+**Why it is on the list:** CI that runs no tests only proves the code compiles.
+
+### 9. `ci-build` - CI builds and tests on every push
+
+**Not blocking.**
+
+**Decided by:** `PASS` if any CI file was found (a workflow under `.github`/`.gitea`/`.forgejo`,
+or a known pipeline file like `Jenkinsfile`, `azure-pipelines.yml`, `.travis.yml`,
+`appveyor.yml`, `bitbucket-pipelines.yml`). `GAP` if none was found.
+
+**Why it is on the list:** without CI, "it works" means "it worked on one machine, once."
+
+### 10. `ci-deploy` - Deployment is reproducible, not manual
+
+**Not blocking.**
+
+**Decided by:** `ASK` if CI files exist (the file LIST cannot say whether that CI actually
+deploys, only that some pipeline exists). `GAP` if there is no CI at all.
+
+**Why it is on the list:** a build pipeline is not the same claim as a deploy pipeline. Whether
+pushing to the default branch actually ships the app has to be answered by a person or by reading
+the workflow's job list, not assumed from its presence.
+
+### 11. `runtime-manifest` - Anything excluded from the repository can be got back
+
+**Not blocking.**
+
+**Decided by:** `PASS` if no ignored folder is 100 MB or larger among the folders that were
+scanned. `ASK` if one or more ignored folders reach that size. A `PASS` is downgraded to `ASK` if
+any top-level folder was scanned with `-SkipFolder` (see "Coverage" below).
+
+**Why it is on the list:** excluding a large runtime or dependency tree from the repository is
+correct. It is only SAFE once something says how to get it back - the exact version and where it
+installs from - and a folder nobody looked at cannot be assumed to already have that answer.
+
+### 12. `health` - There is a health signal that fails loudly
+
+**Not blocking.**
+
+**Decided by:** `PASS` if any probed text file contains a line matching `/health`, `/healthz`,
+`/api/health`, or `healthcheck` (case-insensitive). `ASK` if every matched component's profile
+name contains `batch` (a batch job has no HTTP endpoint to check at all). `GAP` otherwise.
+
+**Why it is on the list:** a check that returns 200 whatever happens is not a health check.
+Finding the STRING `/health` in the source only proves a route exists - it says nothing about
+whether that route actually fails when the app is broken. That is why the plan step this item
+produces explicitly requires breaking the dependency on purpose and watching the check go red
+before it counts as done.
+
+### 13. `run-declared` - How the app runs is declared and version-controlled
+
+**Blocking.**
+
+**Decided by:** `PASS` if the host's registered services, scheduled tasks, or web sites include
+at least one whose path references this folder (matched on the folder's last path segment,
+against Windows services, scheduled tasks, and IIS sites/applications). `ASK` if nothing on the
+scanned host references it at all.
+
+**Why it is on the list:** on a real run, the only "service" `run-declared` found for one app was
+a database engine that happened to be installed inside the app's own folder - not the app's
+process at all. That is why the evidence names each hit individually (`service X`, `task Y`, `site
+Z`): a non-zero count is not proof that any of them is actually running THIS app, and the reader
+has to check, not assume.
+
+### 14. `rollback` - There is a way back to the previous version
+
+**Not blocking.**
+
+**Decided by:** Always `ASK` - the code marks it "not observable from files" unconditionally.
+
+**Why it is on the list:** whether the previous release can be restored, by what exact command,
+and whether that command has ever actually been run, is not written down anywhere a scan can
+read. It can only be answered by a person, and then it has to be exercised at least once to be
+believed (see the plan step this item produces).
+
+### 15. `owner` - The app has a named owner
+
+**Blocking.**
+
+**Decided by:** Always `ASK` - "not observable from files" unconditionally.
+
+**Why it is on the list:** nothing in a repository can say who is accountable for it. Without a
+named owner there is nobody to decide a change and nobody to call when it breaks, so this has to
+reach a person before anything else proceeds.
+
+### 16. `data-recovery` - State can be restored from a backup
+
+**Not blocking.**
+
+**Decided by:** `PASS` if no ignored folder is 100 MB or larger AND the excludable-content
+summary contains no `db-data` category entry. `ASK` otherwise. A `PASS` is downgraded the same
+way as items 4 and 11 if any top-level folder was scanned with `-SkipFolder`.
+
+**Why it is on the list:** excluding a database file or a data dump from the repository is
+correct. It is only safe once a backup schedule exists and a restore from it has actually been
+tested - a repository holding schema and migrations is not itself a backup of the data.
+
+### 17. `docs-readme` - A README says what it is and how to run it
+
+**Not blocking.**
+
+**Decided by:** `PASS` if any doc file's name matches `README*` (case-insensitive). `GAP`
+otherwise.
+
+**Why it is on the list:** the first two questions a new person asks - what is this, and how do I
+run it - should not require finding and interrupting someone.
+
+### 18. `agent-rules` - A rules file the coding agents read
+
+**Not blocking.**
+
+**Decided by:** `PASS` if a doc file is named exactly `AGENTS.md` or `CLAUDE.md`
+(case-insensitive). `GAP` otherwise.
+
+**Why it is on the list:** without it, every coding agent that touches the app re-derives its
+non-obvious rules from scratch, and different agents derive them differently.
+
+### 19. `no-junctions` - No junction or symlink inside the tree git manages
+
+**Not blocking.**
+
+**Decided by:** `PASS` if no reparse point (junction or symlink) was found outside a dependency
+folder (`node_modules`, `.venv`, `venv`, `vendor`). `GAP` otherwise, naming up to three.
+
+**Why it is on the list:** git's own recursive remove (for example `git worktree remove --force`)
+FOLLOWS a junction and deletes the TARGET's contents - this was proven directly, not assumed.
+Ordinary Windows delete operations (`Remove-Item -Recurse`, `cmd /c rmdir /s /q`,
+`[IO.Directory]::Delete`) all correctly refuse to follow a junction, which is exactly what makes
+this trap easy to miss: a delete you tested yourself can look completely safe right up until git
+does the deleting instead.
+
+### 20. `profile` - The stack is declared, not assumed
+
+**Blocking.**
+
+**Decided by:** `PASS` if phase 2 matched at least one component to a profile. `GAP` if it
+matched none.
+
+**Why it is on the list:** without a declared stack, every later step - runtimes, build, deploy -
+is a guess dressed up as a plan. "No profile matched" means the rules do not describe this app
+yet; it does not mean the app has no stack.
+
+---
+
+## Coverage: a skipped folder cannot pass a check
+
+Three items above (`source-only`, `runtime-manifest`, `data-recovery`) can only reach `PASS`
+through `Limit-ByCoverage`, which downgrades a would-be `PASS` to `ASK` whenever any top-level
+folder was scanned with `-SkipFolder`. A folder passed to `-SkipFolder` is recorded as **not
+scanned**, never as empty and never as clean - it is unknown. On a real run, `-SkipFolder tools`
+hid a 16 GB runtime tree, and without this rule the check for "anything excluded can be got back"
+would have reported `PASS` on a folder nobody had actually looked at. Coverage-dependent checks
+stay open until every folder has been scanned, or the operator explicitly accepts a partial
+inventory (`-AllowPartial` in phase 1).
+
+## Answers and waivers
+
+**`-Answer id=text`** (phase 3) records a non-empty answer for an item that is currently `ASK`.
+The tool does not judge the content - any non-empty text satisfies it - and the verdict becomes
+`ANSWERED`. Answers persist in `answers.json` inside the app's output folder and are merged with
+any new `-Answer` arguments on every run, so recording one once is enough for every later
+re-check.
+
+**`-Waive <id>`** records an accepted exception for an item that is not already `PASS`. It sets a
+`waived` flag; **it never rewrites the verdict itself**. A waived `GAP` is still recorded as
+`GAP`, permanently, with `waived: true` next to it - six months later, that difference between "we
+fixed it" and "we accepted the risk" is the whole value of the record. A waived item is excluded
+from the blocking counts below, so it can no longer stop the exit code, but the report still shows
+what it really is.
+
+## Exit codes
+
+| Code | Means |
+|---|---|
+| `0` | Every blocking item is `PASS`, `ANSWERED`, or waived. |
+| `1` | At least one blocking item is `GAP` and not waived. Checked first - if both a blocking `GAP` and a blocking unanswered `ASK` exist at once, exit code `1` wins. |
+| `2` | No blocking `GAP` remains, but at least one blocking item is still an unanswered `ASK` and not waived. |
+
+The eight blocking items, as the code actually enforces them, are: `git-repo`,
+`remote-on-team-host`, `canonical-branch`, `source-only`, `no-secrets`, `run-declared`, `owner`,
+and `profile`. Which items block is decided in the script, by the `Blocking` argument to each
+item, and not by the project config. An earlier draft of the config carried a `blockingItems`
+list that nothing read and that had drifted out of step with this set; it was removed from the
+code and from `config.example.json` together, rather than documented as a thing that looks
+settable and is not.