devflow-kit 2.4.0 → 3.0.0

package/README.md

@@ -53,7 +53,7 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Ambient orchestration.** Your main session becomes the tech lead: a charter injected at session start turns it into a pure orchestrator that delegates work to specialized agents and keeps only judgment mainline. Plan-mode handoffs auto-run `/implement`. Init and forget.
 
-**A staffed agent roster.** 16 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
+**A staffed agent roster.** 17 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
 
 **Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). Every finding gets validated and resolved automatically.
 
@@ -65,11 +65,13 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Always-on rules.** 13 ultra-condensed engineering principles (~10 lines each) load on every prompt — security, quality, and language-specific guidance (TypeScript, React, Go, Python, Java, Rust), plus a compliance rule when compliance is enabled. Rules install from your selected plugins only, so a Go project won't get React rules. Override any rule via `~/.devflow/rules/{name}.md` or `devflow rules shadow <name>`.
 
-**41 skills** (40 universal + 1 feature-owned compliance skill, installed when compliance is enabled). Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
+**41 skills** (40 plugin-owned + 1 feature-owned compliance skill, installed on every machine). Skills install for the plugins you selected plus whatever those plugins declare they use, so the default plugin set installs 32 of the 40 and a Go project never gets the React skill. Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
 
-**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules.
+**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules. A shadow for a skill outside your plugin selection stays where it is: not installed, never deleted, and live again the moment you select that plugin.
 
-**Compliance built in.** Six regulatory frameworks — GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX — composed into a review skill and an always-on rule for exactly the frameworks you select. Compliance reviews activate automatically when a diff touches regulated surface. `devflow compliance --enable`.
+**Compliance built in.** Six regulatory frameworks — GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX. Every install carries the review skill with all six framework references; `devflow compliance --enable` adds an always-on rule for exactly the frameworks you select. A repository can declare its own frameworks in `.devflow/project.json` (`"compliance":["hipaa"]`), and the compliance review then runs there on any machine — with your machine's frameworks plus the repository's, loading only those references — without ever touching your rule. Compliance reviews activate automatically when a diff touches regulated surface. Enabling it on your machine also makes `required` the floor of your team's [evidence policy](#evidence-policy) on your machine: tracker-linked PRs, checked test plans, traced releases and a non-author approval before a PR reads merge-ready.
+
+**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository and a GitHub one side by side. Every install carries every provider's mechanics (47 generated reference files, the tool-call contract among them) and the background agent, because pull requests stay on GitHub whatever your tracker and any repository may pick any provider. On a non-GitHub tracker that agent learns your conventions once per provider (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker/{provider}.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. Each provider's conventions are learned from the first repository that uses it. Those files are yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if one no longer names its own provider. **GitHub is the default** and needs no configuration: no background run and no conventions file.
 
 **Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Simplify + Scrutinize quality passes, and `/release` ships with learned configuration.
 
@@ -95,7 +97,8 @@ When to use which: the orchestrated flow is for a **feature**; graph workflows a
 you: /dynamic-tickets specs/billing-v2.md
 
   Ticket factory         spec → 14 dependency-graphed tickets across 4 waves
-                         each ticket adversarially reviewed · tracking issue opened
+                         each ticket adversarially reviewed
+  Git                    tracking issue + one issue per ticket filed (required evidence policy)
 
 you: /dynamic-plan (wave 1)
 
@@ -107,6 +110,7 @@ you: (answer 2 decisions, walk away) /dynamic-build (wave 1)
 
   Wave 1                 4 tickets   implement → review → verify, dependency-ordered
   Git                    wave report posted to the tracking issue
+  Git · Test             wave PR opened once you say so · its test-plan evidence refreshed
 
 you: /dynamic-plan (wave 2) → /dynamic-build (wave 2) → …
 
@@ -125,24 +129,31 @@ That's it. The interactive wizard offers Recommended defaults or an Advanced flo
 
 ## Privacy & Sharing
 
-Everything Devflow generates lives under `.devflow/` — working memory, decisions and pitfalls, feature knowledge bases, and transient locks. That directory is **gitignored wholesale by default**, so this per-developer runtime state stays on your machine and never lands in a commit. Devflow adds the `.devflow/` line to your project's root `.gitignore` automatically on first use.
-
-Sharing is opt-in. To share **everything** with your team, remove the `.devflow/` line from `.gitignore`. To share only curated knowledge (and keep memory, queues, and locks local), replace the `.devflow/` line with a pattern that ignores everything except the files you want tracked:
+Everything Devflow generates lives under `.devflow/` — working memory, decisions and pitfalls, feature knowledge bases, naming conventions, docs and transient locks. On first use Devflow appends one block to your project's root `.gitignore`. It keeps per-developer runtime state on your machine and shares three things through git: the feature knowledge bases, the learned naming conventions and the team's settings in `.devflow/project.json`, which carry its [evidence policy](#evidence-policy):
 
 ```gitignore
-# Ignore all Devflow runtime data…
-.devflow/**
-# …except the team knowledge you want to share
-!.devflow/learning/
-!.devflow/learning/decisions.md
-!.devflow/learning/pitfalls.md
+# Devflow runtime data — local by default (memory, learning, docs, locks).
+# Shared via git: feature knowledge bases under .devflow/features/ (index.md and
+# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority),
+# .devflow/policy.json (retired; presence only) and .devflow/project.json (team settings).
+# To stop sharing the first two, re-add `.devflow/features/` or
+# `.devflow/conventions.md` to your own .gitignore.
+.devflow/*
 !.devflow/features/
+.devflow/features/*
 !.devflow/features/index.md
 !.devflow/features/*/
+.devflow/features/*/*
 !.devflow/features/*/KNOWLEDGE.md
+!.devflow/conventions.md
+!.devflow/policy.json
+!.devflow/project.json
+.claudeignore
 ```
 
-(The directory re-includes — `!.devflow/learning/` — are required: git won't descend into an excluded directory to reach a re-included file.)
+The `!.devflow/policy.json` line keeps a retired policy file shared while teammates on an older devflow still read it (see [Evidence policy](#evidence-policy)). When your block predates a line, the next hook run or `devflow init` inserts the missing line inside the block, where a fresh block holds it — never at the end of the file, so a re-ignore of your own further down still wins. The paired lines — `!.devflow/features/` then `.devflow/features/*` — are required: git never descends into an excluded directory to reach a re-included file. The final `.claudeignore` line is left out when your `.gitignore` already has its own `.claudeignore` or `!.claudeignore` entry.
+
+To keep the knowledge bases or conventions local, add `.devflow/features/` or `.devflow/conventions.md` to your own `.gitignore`. A `/.devflow/` line of your own opts the whole project out: Devflow then leaves your `.gitignore` alone.
 
 ## Commands
 
@@ -165,7 +176,86 @@ Sharing is opt-in. To share **everything** with your team, remove the `.devflow/
 
 See [docs/commands.md](https://github.com/dean0x/devflow/blob/main/docs/commands.md) for detailed usage.
 
-**PR-comment publication** for `/code-review` and `/resolve` is visibility-gated (counts-only stub on public repos by default) and every posted body is secret-scrubbed before it leaves your machine. Configure via `reviewPublication` in `.devflow/config.json` — details in [docs/commands.md](https://github.com/dean0x/devflow/blob/main/docs/commands.md).
+**PR-comment publication** for `/code-review` and `/resolve` is visibility-gated (counts-only stub on public repos by default) and every posted body is secret-scrubbed before it leaves your machine. Configure via `reviewPublication` (`auto`, `full` or `off`) in your personal `.devflow/config.json`; a team value in [`.devflow/project.json`](#team-settings) is only a ceiling: it can lower yours, never raise it. Under a `required` evidence policy, `off` still posts the counts-only stub, so a record reaches the PR. The [test-plan evidence](#test-plan-evidence) comment is a stub unless `reviewPublication` is `full` — details in [docs/commands.md](https://github.com/dean0x/devflow/blob/main/docs/commands.md).
+
+## Team settings
+
+A repository can commit `.devflow/project.json` to settle team-wide choices. Every key is optional, unknown keys are ignored, and devflow never writes the file:
+
+```json
+{"version":1,"evidence":"required","compliance":["hipaa"],
+ "tracker":{"provider":"jira","site":"https://acme.atlassian.net","key":"ACME"},
+ "reviewPublication":"auto","features":{"learning":false}}
+```
+
+- `evidence` is the [evidence policy](#evidence-policy); `compliance` names the regulatory frameworks the repository answers to, and its presence raises the evidence floor to `required`.
+- `tracker` selects the repository's issue tracker. Your personal `.devflow/config.json` may only narrow it, to `github` or to the same provider.
+- `reviewPublication` is a ceiling only: it can lower your personal value, never raise it. With no personal value you get at most `auto` — a team `off` still lowers it — so a branch that commits `full` cannot switch off the visibility gate for whoever reviews it.
+- `features` can switch memory, learning or knowledge off for this repository, never back on. Your personal `config.json` can do the same for you.
+
+**Adopting it.** Commit `project.json` on the default branch. `evidence` is always read from the default branch, so a feature branch cannot lower the bar it is judged by. Every other key — `tracker` with its `site` and `key`, `features` and the `reviewPublication` ceiling — is read from the branch you have checked out, so a branch that edits them sees the change at once. `compliance` is read from both and joined with your machine's frameworks: a branch can add a framework, never remove one, so a pull request that deletes `"compliance":["hipaa"]` is still reviewed under HIPAA. The default branch's copy is read from your clone's tracking branch, as fresh as your last fetch, never over the network, so a framework added on the default branch reaches the lens once your checkout has fetched it.
+
+Each key is checked on its own, so one bad value never disables the rest: a bad `evidence` resolves to `required`, a bad `reviewPublication` to `off`, a bad `compliance` list to the generic lens. A `project.json` or `config.json` that exists but is not a JSON object is never read as absent: the settings fail closed (publication off, knowledge write-back off, the tracker reported as invalid). The compliance lens is the exception, because it only adds scrutiny: it keeps every framework a readable layer declares, and an unreadable `project.json` counts as the generic lens. Memory and learning capture fail open instead: the hooks read an unreadable file as narrowing nothing, so capture runs as your machine's switch says.
+
+`config.json` is personal, so it must not be committed. A `config.json` that git tracks is ignored as if it were absent — otherwise a branch could commit `"reviewPublication":"full"` for whoever reviews it — and `devflow tracker|memory|learning|knowledge --status` say so, with the fix: `git rm --cached .devflow/config.json`. Commands never read the file themselves — one local resolver folds it with your `config.json` and the machine settings, without touching the network.
+
+## Evidence policy
+
+How much evidence a change must carry is a team decision, so it lives in the file the team commits, read from the repository's default branch: the `evidence` key of [`.devflow/project.json`](#team-settings).
+
+```json
+{"version":1,"evidence":"required"}
+```
+
+`evidence` is `required` or `standard`. A malformed or duplicated value, or a `project.json` that is not a JSON object, resolves to `required`.
+
+**`.devflow/policy.json` is retired.** devflow never reads it. Where `project.json` has no `evidence` key, a committed `policy.json` holds the repository at `required` whatever it says, with an `invalid-file` warning. To migrate, add its value to `.devflow/project.json` — `{"version":1,"evidencePolicy":"standard"}` becomes `{"version":1,"evidence":"standard"}` — and keep `policy.json` until every teammate runs devflow 3.0 or later. It is harmless on 3.0, which never looks at it once `project.json` has `evidence`, while an older devflow reads only `policy.json`; delete it after that. `devflow compliance --status` prints the same hint while the file is there.
+
+| | `standard` | `required` |
+|---|---|---|
+| Tracker issue | optional — `/plan` offers to create one | mandatory — `/plan` creates or enriches one; `/implement` without one records a self-attested exception or stops |
+| Test plan | written and shown on the PR when there is one; a missing plan is only reported | mandatory — `/implement` without one records a self-attested exception or stops, and a wave PR with a merged ticket lacking one is blocked |
+| Naming conventions | not learned, not applied | learned once into `.devflow/conventions.md`, then applied to branch names and PR titles |
+| External review threads | left alone | `/resolve` replies to them and resolves the ones it verifiably fixed |
+| Merge readiness | not checked by `/resolve` | `/resolve` checks it, and READY needs a trusted non-author approval |
+| Releases | no trace gate (`--dry-run` still shows the trace) | `/release` maps every commit since the last release to its issue; untraced commits are attested or the release halts; shipped issues are back-linked and added to the release marker |
+| `reviewPublication: off` | no PR comment | the counts-only stub still posts |
+| `/dynamic-tickets` | files no issues | files the tracking issue and one issue per ticket |
+
+**Defaults.** With no committed `evidence` and no `policy.json` the policy is `standard`, unless compliance is enabled on the machine running devflow — at any framework count — which makes it `required` there, or the repository's `project.json` carries a `compliance` key — on the default branch, its tracking copy or the working tree, whatever its value — which makes it `required` everywhere.
+
+**The stricter value wins.** The default branch's copy is the authority, so a feature branch that commits a weaker policy is still judged by the default branch's; the difference shows as a `pr-changes-policy` warning. Local sources can raise the policy but never lower it: enabled compliance raises a committed `standard` to `required` on that machine. Every failure — git not answering, an invalid file, a resolver that cannot run — resolves to `required`. Offline, devflow takes the default branch's name from your clone's `origin/HEAD` and reads that branch's local tracking copy instead, so a branch still cannot lower the policy, and flags the result `remote-unavailable`. A clone that never recorded `origin/HEAD` has only the working tree to go on, which then decides; `git remote set-head origin --auto` records it.
+
+**Commit it yourself.** The CLI never writes `project.json` or `policy.json`. `devflow compliance --enable` and `--set` print the keys to add to `.devflow/project.json` — merged into the file when it already exists, never replacing it — and `devflow compliance --status` shows the policy resolved for the current repository and where it came from. The `.gitignore` block above keeps `project.json` shareable. Guard it like any other policy file, for example with a CODEOWNERS entry:
+
+```text
+/.devflow/project.json @your-org/maintainers
+```
+
+## Test-plan evidence
+
+A PR carries a test plan: one TP line per acceptance criterion, in one fixed shape.
+
+```text
+- [ ] TP-1 (AC-1) rejects an upload over the size limit — method:ci [files: src/upload/**]
+```
+
+`method` is how the line is verified: `ci` (the CI suite covers it), `local` (a command whose exit code the Test agent reads) or `manual` (agent-driven steps, observed). `files:` lists the globs the line covers, so a later change elsewhere does not make it stale. A scenario is plain words — no `#`, `@`, `/`, `<`, `>`, brackets or backticks — because it lands in the PR body, where a closing keyword or a mention would act.
+
+`/plan` writes the lines, and `/implement` checks them before any code is written. The PR body carries them as a test-plan block between `<!-- devflow:test-plan -->` markers. The Test agent records a claim per line — `PASS`, `FAIL` or `SKIP` at a commit — and the evidence scripts, never a prompt, turn each claim into one of six states:
+
+| State | Meaning |
+|---|---|
+| `VERIFIED-CI` | a `ci` pass backed by passing CI runs at the verifying commit |
+| `ATTESTED-LOCAL` | a `local` pass with exit code 0, a `manual` pass, or a `ci` pass at a commit that has no CI runs |
+| `UNVERIFIED` | no usable claim: none, a skip, a commit outside the PR, or a line whose text changed |
+| `STALE` | claimed at an older commit, and the change since may touch the line's files |
+| `FAILED` | a fail, a non-zero exit code, or a failing CI run |
+| `INDETERMINATE` | something the verdict needs could not be resolved, such as a CI run still in progress or expired |
+
+Only the first two count as verified, and the block ticks exactly those lines. `update-pr-evidence` re-derives every state at the PR's head, updates the block — reduced to one counts line when the lines would push the body past its size limit — and posts an append-only evidence comment keyed to that head. `/implement`, `/resolve` and the wave PR of `/dynamic-build` all refresh it.
+
+The evidence comment is a counts-only **STUB** unless `reviewPublication` is `full`. **FULL** adds the scenario table, with links to the CI runs, and the reasons for any self-attested exception, and falls back to the STUB above 55,000 characters. `off` posts no evidence comment, except under a `required` policy, where it becomes the STUB. A self-attested exception — no tracker issue, or no test plan — is recorded in the PR body under `## Evidence Exceptions`, with who attested it and when.
 
 ## Language Support
 
@@ -187,8 +277,11 @@ For deep dives: [Working Memory](https://github.com/dean0x/devflow/blob/main/doc
 npx devflow-kit init                    # Install (interactive wizard)
 npx devflow-kit init --plugin=implement # Install specific plugin
 npx devflow-kit ambient --enable        # Toggle ambient mode (orchestrator)
-npx devflow-kit learning --enable       # Toggle decision/pitfall tracking
-npx devflow-kit compliance --enable     # Enable compliance reviews (pick frameworks)
+npx devflow-kit learning --enable       # Toggle decision/pitfall tracking (all projects)
+npx devflow-kit compliance --enable     # Enable compliance (pick frameworks); prints the keys to add to .devflow/project.json
+npx devflow-kit compliance --status     # Show compliance state and this repo's evidence policy
+npx devflow-kit tracker --set jira       # Pick the machine's default tracker (github | jira | linear)
+npx devflow-kit tracker --status         # Show provider, this repo's effective one, learned conventions, mechanics
 npx devflow-kit rules --status          # Show installed rules
 npx devflow-kit security --status       # Show / manage the security deny list
 npx devflow-kit safe-delete --enable    # Install rm -> trash safe-delete