devworkspace 0.2.1 → 0.3.0

package/dist/verification/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/verification/scope.ts"],"names":[],"mappings":"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","sourcesContent":["import { promises as fs } from 'node:fs';\nimport path from 'node:path';\nimport type { CommandEntry } from '../config/schemas.js';\nimport { gitAvailable, parsePorcelainZ } from '../git/git.js';\nimport { isSensitiveFile } from '../security/files.js';\nimport type { TaskScope } from '../tasks/task.js';\nimport { sha256File, sha256Text } from '../utils/fs.js';\nimport { run } from '../utils/proc.js';\n\nconst MAX_TRACKED_FILES = 2000;\nconst MAX_HASH_BYTES = 8 * 1024 * 1024;\n/** Documentation and tool-managed folders never decide which package's checks apply. */\nconst NOT_CODE = /^(?:\\.devworkspace|\\.claude|graphify-out)\\/|\\.(?:md|mdx|rst|txt)$/i;\n\nexport type ChangeMap = Record<string, string>;\n\nasync function git(root: string, args: string[]): Promise<string | null> {\n  const r = await run('git', args, { cwd: root, timeoutMs: 30_000 });\n  return r.ok ? r.stdout : null;\n}\n\nasync function fileFingerprint(root: string, rel: string): Promise<string> {\n  const full = path.join(root, ...rel.split('/'));\n  try {\n    const st = await fs.lstat(full);\n    if (!st.isFile()) return 'not-a-file';\n    if (st.size > MAX_HASH_BYTES) return `large:${st.size}:${Math.floor(st.mtimeMs)}`;\n    return await sha256File(full);\n  } catch {\n    return 'deleted';\n  }\n}\n\n/** Files that differ from HEAD right now (modified, staged or untracked), project-relative, with a content hash. */\nexport async function dirtyFiles(root: string): Promise<{ head: string | null; files: ChangeMap } | null> {\n  if (!(await gitAvailable())) return null;\n  if ((await git(root, ['rev-parse', '--is-inside-work-tree']))?.trim() !== 'true') return null;\n  const prefix = ((await git(root, ['rev-parse', '--show-prefix'])) ?? '').trim();\n  const head = ((await git(root, ['rev-parse', 'HEAD'])) ?? '').trim() || null;\n  const status = await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);\n  if (status === null) return null;\n  const files: ChangeMap = {};\n  for (const e of parsePorcelainZ(status)) {\n    if (e.xy === '!!' || !e.path.startsWith(prefix)) continue;\n    const rel = e.path.slice(prefix.length);\n    if (NOT_CODE.test(rel) || isSensitiveFile(rel)) continue;\n    if (Object.keys(files).length >= MAX_TRACKED_FILES) break;\n    files[rel] = await fileFingerprint(root, rel);\n  }\n  return { head, files };\n}\n\n/** Snapshot taken when a task is created: what is already modified is not the task's doing. */\nexport async function captureScope(root: string, now: string): Promise<TaskScope> {\n  const d = await dirtyFiles(root);\n  return { capturedAt: now, head: d?.head ?? null, baseline: d?.files ?? {} };\n}\n\n/** Project-relative files committed since `head` (so committing during a task does not hide its changes). */\nasync function committedSince(root: string, head: string): Promise<string[] | null> {\n  const prefix = ((await git(root, ['rev-parse', '--show-prefix'])) ?? '').trim();\n  const out = await git(root, ['diff', '--name-only', '-z', head, 'HEAD']);\n  if (out === null) return null;\n  return out.split('\\0').filter((f) => f && f.startsWith(prefix)).map((f) => f.slice(prefix.length));\n}\n\n/** Files that changed since the task started, with their current hashes. Null when that cannot be determined. */\nexport async function changedSince(root: string, scope: TaskScope): Promise<ChangeMap | null> {\n  const now = await dirtyFiles(root);\n  if (!now) return null;\n  const changed: ChangeMap = {};\n  for (const [rel, hash] of Object.entries(now.files)) if (scope.baseline[rel] !== hash) changed[rel] = hash;\n  // A file that was modified at the start and has since been cleaned up (committed or reverted) also changed.\n  for (const rel of Object.keys(scope.baseline)) if (!(rel in now.files)) changed[rel] = await fileFingerprint(root, rel);\n  if (scope.head && now.head && scope.head !== now.head) {\n    const committed = await committedSince(root, scope.head);\n    if (committed === null) return null;\n    for (const rel of committed) if (!NOT_CODE.test(rel) && !isSensitiveFile(rel) && !(rel in changed)) changed[rel] = await fileFingerprint(root, rel);\n  }\n  return changed;\n}\n\n/** Directories (relative to the project root) that have their own checks in the contract, longest first. */\nexport function packageDirs(contract: CommandEntry[]): string[] {\n  const dirs = new Set<string>();\n  for (const c of contract) if (c.available && c.cwd && c.cwd !== '.') dirs.add(c.cwd);\n  return [...dirs].sort((a, b) => b.length - a.length || a.localeCompare(b));\n}\n\n/**\n * Fingerprint of the changes inside each package. A change under a package belongs to it; a change outside every package\n * (root config, shared tooling) belongs to all of them. \".\" covers everything. Returns null when nothing is known.\n */\nexport function scopeByPackage(changes: ChangeMap | null, contract: CommandEntry[]): Record<string, string> | null {\n  if (!changes) return null;\n  const files = Object.keys(changes).filter((f) => !NOT_CODE.test(f)).sort();\n  if (files.length === 0) return null;\n  const dirs = packageDirs(contract);\n  const owner = (f: string): string | null => dirs.find((d) => f === d || f.startsWith(`${d}/`)) ?? null;\n  const shared = files.filter((f) => owner(f) === null);\n  const line = (f: string): string => `${f}:${changes[f]}`;\n  const out: Record<string, string> = { '.': sha256Text(files.map(line).join('\\n')) };\n  for (const d of dirs) {\n    const mine = files.filter((f) => owner(f) === d);\n    if (mine.length > 0 || shared.length > 0) out[d] = sha256Text([...mine, ...shared].sort().map(line).join('\\n'));\n  }\n  return out;\n}\n"]}

package/docs/benchmarking.md

@@ -31,3 +31,22 @@ Report medians and ranges, not single runs. Include the onboarding cost in arm B
 - Provider token counts are often unavailable inside IDE integrations; use tool-call counts as a proxy and say so.
 - Savings depend heavily on repository size, task type and knowledge quality. A one-file repo will show none.
 - Do not extrapolate to percentages without data from your own runs.
+
+## Measuring DevWorkspace itself (speed and context size)
+
+The section above is about agent behaviour. This one measures the tool, deterministically and offline.
+
+```
+npm run build
+node scripts/bench.mjs --files 3000 --runs 9 --json result.json
+```
+
+`scripts/bench.mjs` generates an ERP-shaped monorepo (NestJS-style `backend/` with DB-dependent scripts, React `frontend/`, docs, a `.env` that is never read) in a temp directory, commits it, and times the `dist/` build in-process: first and repeated `analyze`, dry-run `analyze`/`refresh`, `refresh`, and context generation (legacy, `--topic`, and `--for` for five request types). It prints medians, min/max and every sample.
+
+To compare against a baseline, build the baseline commit in a separate `git worktree`, copy `scripts/bench.mjs` into it, and run the script in both. Alternate the runs (A, B, A, B) to cancel machine drift.
+
+**Token counts are estimates**: rendered CLI output bytes / 4. No tokenizer or model is called. Use them to compare two outputs of the same tool, not as billing numbers. The generated fixture's facts are synthetic; real repositories have more and longer facts, so absolute sizes will differ.
+
+Reported per context: bytes, estimated tokens, facts included/available, checks included/available, decisions and documents included/available, and how many safety rules and unsafe-command warnings were kept. Cache behaviour (`hit` / `miss` / `invalidated`) is asserted in `tests/integration/progressive-context.test.ts`; correctness of discovery is covered by the existing discovery suites.
+
+What the numbers do not show: the scan (`readdir` of every directory) and the Git query still run on every analyze, because the cache may not decide that nothing changed. Both are the remaining bottlenecks.

package/docs/knowledge.md

@@ -44,6 +44,8 @@ Uncertainty is first-class: record `INFERRED`/`LOW` or `UNKNOWN` rather than gue
 
 Each fact lists the repository files that evidence it and stores their SHA-256 at the time of recording. `devworkspace refresh` re-hashes those sources: a changed or removed source marks the fact `STALE` with a reason. Only stale facts are handed to the agent in the refresh prompt (incremental, not a full re-analysis). The agent re-checks and runs `devworkspace fact verify <key>` (re-hash, mark verified), corrects the fact, or removes it. Facts without sources cannot be proven stale, so cite files.
 
+Generated files are not evidence by themselves: re-running `analyze` rewrites `.devworkspace/analysis/*`, which must not invalidate unrelated facts. A fact may cite a section of the discovery report as `.devworkspace/analysis/discovery.json#ci` (fingerprint of that section only), and a bare `discovery.json` citation is narrowed to the section named by the fact's key (`ci.none` depends on `ci`). Any other generated file is ignored. `status`, `refresh --dry-run` and `doctor` all use the same read-only check, so they agree, and each stale fact says which evidence changed. A fact recorded before a dependency was tracked adopts its current fingerprint instead of going stale.
+
 Content hashing is deliberately conservative: *any* byte change to a cited file triggers re-validation. It over-reports rather than silently trusting old context.
 
 Deterministic (`detector`) facts are simply re-derived on every `analyze`/`refresh`; ones that no longer apply are removed (they are derived data and come back if the evidence returns), so they never produce a warning nobody can clear.
@@ -64,3 +66,20 @@ Never store: source files, `node_modules`/generated output, chat transcripts, te
 ## Progressive loading
 
 The generated instructions tell the agent to load context in levels and stop at the shallowest one that answers the request: (1) instructions → (2) `devworkspace context --topic …` → (3) relevant decisions → (4) Graphify → (5) specific source files → (6) tests/implementation. "Where is customer uniqueness checked?" stops at level 4–5; "Refactor the customer validation architecture" goes to level 6.
+
+### Task-aware context (`context --for`)
+
+`devworkspace context --for "<request>"` classifies the request (same classifier as `task new`) and prints only what it needs, each item with the reason it is included:
+
+- facts whose key, value or source match the request's keywords, plus type groups (stack and conventions for implementation tasks; known issues for bugs; authorization and tenant rules for security);
+- checks of the package the request names, or of the packages with uncommitted code changes, otherwise all checks; none for questions and documentation;
+- decisions by title and file (never their text) and context documents by name (never embedded);
+- the safety rules, always, and the list of commands DevWorkspace will not run by itself whenever their checks are included.
+
+Detector-derived facts whose value equals another selected fact's are folded into it in the output, and very long detector values are clipped with a pointer to `context --topic <key>`. Human- and AI-authored facts are never folded or clipped, and nothing is removed from `facts.json`. Output is deterministic. Plain `context` is unchanged.
+
+Routing note (0.3.0): requests naming cross-tenant access, tenant isolation, CSRF/XSS, SQL injection, IDOR, CVEs or privilege escalation are classified SECURITY even when they begin with "fix" (they were BUG), so the exploit-test and review gates apply.
+
+### Discovery cache
+
+`analyze` and `refresh` reuse the previous detection result from `.devworkspace/local/cache/discovery.json` (git-ignored, never exported) only when the scan result, the content of every manifest detection reads, the project name, the scan limit and the DevWorkspace version are identical. The directory scan and the Git query always run; the cache is a shortcut for recomputation, never evidence. `--dry-run`, `status`, `doctor` and `context` never write it. Delete the `local/cache` folder at any time.

package/docs/testing.md

@@ -21,9 +21,27 @@ Re-running `analyze` keeps any command with `origin: "user"` (confirmed by a per
 
 Sources: `package.json` scripts (matched by common names), plus conventions for Python (pytest/ruff/mypy/black/alembic), Go, Rust, Maven and Gradle. npm's default `"no test specified"` placeholder is ignored.
 
+Formatters are listed too. A `format` script that rewrites files is recorded with `"mutates": true` and `required: "no"`; a `format:check` (or a `format` that only checks) is read-only. DevWorkspace never runs a command marked `mutates`.
+
 ### Commands are untrusted input
 
-Everything marked `origin: "repository-script"` comes from files in the repository. DevWorkspace **never runs these commands itself**; the agent does, and the generated instructions tell it to read what a script does before running unfamiliar ones, especially where scripts might deploy, migrate or write over the network.
+Everything marked `origin: "repository-script"` comes from files in the repository. `analyze`, `status`, `doctor` and `refresh` never run any of them. Only `devworkspace task run` executes a contract command, as an argument vector (never through a shell), and only after the safety rules below. The generated instructions still tell the agent to read what an unfamiliar script does first.
+
+### What `task run` will and will not run
+
+| Command | Runs? |
+| --- | --- |
+| typecheck, lint, build, unit tests, read-only format checks | yes |
+| migrations; anything whose definition mentions drop, truncate, reset, seed, migrate, flush; any command marked `mutates` | **never** |
+| integration, security and e2e checks; a catch-all `test` script in a package that depends on a database or Redis | only after you declare a test environment for that package and check |
+
+DevWorkspace does not read `.env` files or connection settings, so it **cannot verify which database a test would use**, and it does not guess from names (a database called `test` is not treated as safe). The only way to allow such a check is an explicit, local declaration by a person:
+
+```bash
+devworkspace testenv declare --package backend --check integration --target "disposable docker compose stack" --yes
+```
+
+This records your assertion in `.devworkspace/local/test-environment.json` (git-ignored). Targets that look like connection strings or credentials are refused. A refused check is recorded as `COULD_NOT_RUN`, never as a pass.
 
 ## Task-specific verification
 
@@ -32,9 +50,14 @@ Questions need none; docs need only documentation checks; bugs, features and ref
 ```bash
 devworkspace task tests <id> --phase baseline --passed 214 --failed 3   # before changing code
 devworkspace task tests <id> --phase after    --passed 218 --failed 3
-devworkspace task verify <id> unit pass
+devworkspace task run <id> typecheck          # executes the contract command for every package the task changed
+devworkspace task verify <id> review pass     # a report; recorded as a claim, not as an executed result
 ```
 
+### Package-aware completion
+
+A task records, when it is created, which files were already modified. When you complete it, DevWorkspace works out which files changed since, assigns them to packages (the `cwd` directories of the contract; a change outside every package counts for all of them) and requires **executed** evidence for each applicable check **in each changed package**, taken after the last change. A backend-only build is not evidence for frontend changes. A pass that was only reported with `task verify` is a claim and does not satisfy the gate unless you add `--reason user-override`. Tasks created by older versions keep the original rules.
+
 Pre-existing failures are recorded, not blamed on new work. Regressions block completion.
 
 ## Failure reporting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devworkspace",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
   "type": "module",
   "bin": {