devworkspace 0.0.0-stage → 0.1.1

package/docs/getting-started.md

@@ -0,0 +1,79 @@
+# Getting started
+
+## 1. Set up
+
+```bash
+cd path/to/your/project
+npx devworkspace init
+```
+
+`init` finds the project root (the Git top-level if you are in a subfolder, otherwise the current directory; override with `--root`), creates `.devworkspace/`, writes a nested `.gitignore` for machine-local state, and reports which integrations it can see. It never edits your source and is safe to repeat. Use `--dry-run` to preview.
+
+What you get:
+
+```text
+.devworkspace/
+├── project.json          identity (random id), name, settings, managed-file list
+├── .gitignore            ignores local/ and regenerable prompts
+├── context/              facts.json, commands.json (testing contract), your architecture.md etc.
+├── decisions/            0001-use-redis.md ...
+├── tasks/{active,completed}/
+├── sessions/             short summaries
+├── analysis/             discovery.json (+ onboarding-prompt.md, git-ignored)
+├── state/analysis.json   hashes/timestamps used for staleness
+└── local/                machine-specific; never committed
+```
+
+## 2. Analyze
+
+```bash
+npx devworkspace analyze
+```
+
+Deterministic only: reads manifests, lockfiles, configs and the file tree (skipping `node_modules`, build output, caches, `.git`, anything in `.gitignore` / `.devworkspaceignore`, and never reading credential files). It writes the discovery report, a **testing contract** (`context/commands.json`), detected facts, and the **onboarding prompt**.
+
+## 3. Onboard with Claude
+
+Open `.devworkspace/analysis/onboarding-prompt.md` and paste it into Claude Code. Claude will:
+
+1. validate the findings against the real code,
+2. use Graphify (if available) to understand structure,
+3. run `devworkspace agent install` (adds a small managed block to `CLAUDE.md` and installs the `devworkspace` skill, preserving anything you wrote),
+4. write concise knowledge into `.devworkspace/context/`,
+5. check the testing contract and record a baseline,
+6. offer to install and verify Graphify, Agent Skills and Ponytail (it asks once; nothing is installed without your yes),
+7. run `devworkspace doctor` and report unknowns and warnings.
+
+It is told not to modify application source during onboarding.
+
+## 4. Verify
+
+```bash
+npx devworkspace doctor
+```
+
+`READY` means the workspace is healthy, instructions are installed and architecture knowledge exists. Warnings (for example *Graphify: not detected*) tell you exactly what to do next and do not fail the command.
+
+## 5. Work normally
+
+Ask Claude for what you want. See [routing](routing.md) for how requests are handled and [claude.md](claude.md) for what was installed. After meaningful work Claude records durable knowledge; you can inspect it any time with `devworkspace context`, and run `devworkspace refresh` after large changes (or after pulling) to catch stale knowledge.
+
+## Start over
+
+```bash
+npx devworkspace reset                 # shows what would be deleted; deletes nothing
+npx devworkspace reset --yes           # deletes .devworkspace/ (knowledge, tasks, decisions, local state)
+npx devworkspace reset --yes --include-agent-files   # also removes the DevWorkspace block from CLAUDE.md and the managed skill
+npx devworkspace init                  # begin again with a new project id
+```
+
+Only DevWorkspace's own files are removed: your source code is never touched, text you wrote in `CLAUDE.md` is kept, and a skill you wrote yourself is left alone. Committed knowledge can still be recovered from Git history. Run `devworkspace export` first if you want a copy.
+
+## Install options
+
+```bash
+npm install -g devworkspace    # then: devworkspace init
+npx devworkspace <command>     # no installation
+```
+
+Requires Node.js 20.11+.

package/docs/integrations.md

@@ -0,0 +1,51 @@
+# Integrations
+
+Each integration sits behind the `Integration` interface (`src/integrations/types.ts`): `detect(ctx) → IntegrationStatus`. Core code only sees states `READY`, `PARTIAL`, `NOT_DETECTED`, `UNVERIFIED`, `ERROR` plus remediation text. A failing detector degrades to `ERROR` and never breaks a command. Missing integrations are warnings, not failures.
+
+Documentation below was read from each project's repository when this version was written. Re-check before relying on it; these projects evolve.
+
+| Integration | Role | Researched against |
+| --- | --- | --- |
+| Graphify | Structural discovery | `Graphify-Labs/graphify` README (Oct 2026) |
+| Agent Skills | Engineering workflows | `addyosmani/agent-skills` README (Oct 2026) |
+| Ponytail | Quality / simplification review | `DietrichGebert/ponytail` README (Oct 2026) |
+| OmniRoute | Optional model routing | not integrated in V1 |
+| Claude Code | Agent | `code.claude.com` memory and skills docs (Oct 2026) |
+
+## Graphify
+
+- **Install (documented):** `uv tool install graphifyy` (or `pipx install graphifyy` / `pip install graphifyy`), then `graphify install` (global) or `graphify install --project` (writes `.claude/skills/graphify/`).
+- **Use:** `/graphify .` in Claude Code builds the graph into `graphify-out/` (`graph.json`, `GRAPH_REPORT.md`, `graph.html`). Queries: `graphify query "…"`, `graphify path "A" "B"`, `graphify explain "…"`. `graphify hook install` auto-rebuilds on commits.
+- **Detection:** `graphify` on PATH, `graphify-out/graph.json`, project/user skill directory. `READY` = (CLI or skill) and a built graph; `PARTIAL` = installed but no graph (or graph without CLI).
+- **Authority:** the graph is an aid. The generated skill tells the agent to confirm in real files; repository evidence wins.
+- **Not done:** DevWorkspace does not run Graphify, build graphs, or parse `graph.json`. `graphify-out/` is excluded from scans.
+
+## Agent Skills
+
+- **Install (documented):** in Claude Code, `/plugin marketplace add addyosmani/agent-skills` then `/plugin install agent-skills@addy-agent-skills`. The equivalent shell form, which Claude can run for you during onboarding, is `claude plugin marketplace add addyosmani/agent-skills` and `claude plugin install agent-skills@addy-agent-skills`; verify with `claude plugin list`.
+- **Provides:** `/spec`, `/plan`, `/build`, `/test`, `/constraints`, `/review`, `/webperf`, `/code-simplify`, `/ship`, plus auto-activating skills.
+- **Division of labour:** the DevWorkspace skill says *when* (per task type, see [routing](routing.md)); Agent Skills says *how*. Nothing is copied.
+- **Detection:** best effort, searching Claude Code settings/plugin registries for `agent-skills`. Plugin state belongs to Claude Code, so absence is reported as `UNVERIFIED`, not "missing".
+
+## Ponytail
+
+- **Install (documented):** `/plugin marketplace add DietrichGebert/ponytail`, `/plugin install ponytail@ponytail` (shell form: `claude plugin marketplace add …` / `claude plugin install ponytail@ponytail`). Other agents: copy its `AGENTS.md` or install `skills/ponytail/SKILL.md`.
+- **Commands:** `/ponytail [lite|full|ultra|off]`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`. Optional config `~/.config/ponytail/config.json`, `PONYTAIL_DEFAULT_MODE`.
+- **Use here:** review of meaningful diffs and simplification only. It never substitutes for tests. Strictness maps to `project.json` → `settings.review` (`off` removes the review requirement from new tasks; `light` default; `strict` reserved for stricter policy).
+- **Detection:** plugin mention in settings, `.claude/skills/ponytail`, or `AGENTS.md` mention. Otherwise `UNVERIFIED`.
+
+## OmniRoute (optional)
+
+Not required, not in the V1 path, no API keys or model configuration. The adapter only reports whether an `omniroute` executable exists. A future provider boundary can build on it.
+
+## Claude Code
+
+See [claude.md](claude.md).
+
+## Adding an integration
+
+1. Implement `Integration` in `src/integrations/<name>.ts` (pure detection, no side effects, timeouts if you spawn anything).
+2. Add it to `INTEGRATIONS` in `src/integrations/index.ts`.
+3. Give it a `usage` string; the Claude skill renders it automatically for non-optional integrations.
+4. Add tests for READY / PARTIAL / NOT_DETECTED and a throwing detector.
+5. Document researched commands and limitations here.

package/docs/knowledge.md

@@ -0,0 +1,66 @@
+# Knowledge model
+
+DevWorkspace stores **knowledge**, not code: concise statements about the project, each with provenance. Stored facts are a cache of evidence, never a replacement for it.
+
+## Authority
+
+```text
+USER DECISIONS
+   ↓
+CURRENT REPOSITORY EVIDENCE   (what the code says right now)
+   ↓
+VERIFIED DEVWORKSPACE FACTS
+   ↓
+AI-DERIVED FINDINGS
+   ↓
+OLD SESSION INFORMATION
+```
+
+Enforced in `knowledge/facts.ts`: a lower-authority write never silently replaces a higher-authority fact (`CONFLICT` error with a hint), except when the existing fact is already `STALE`. Deterministic detection (rank 4) may replace an AI-verified fact (rank 3) because it reflects the repository *now*. User decisions (rank 5) are never replaced by an agent and are never auto-staled; if their sources change they are flagged *for human review*.
+
+## A fact
+
+```json
+{
+  "key": "auth.session-store",
+  "value": "Sessions are stored in Redis",
+  "source": "src/auth/session.ts",
+  "sourceType": "ai",
+  "sources": ["src/auth/session.ts"],
+  "sourceHashes": { "src/auth/session.ts": "sha256…" },
+  "confidence": "HIGH",
+  "status": "VERIFIED",
+  "createdAt": "…", "updatedAt": "…", "lastVerifiedAt": "…"
+}
+```
+
+- **status:** `VERIFIED`, `DETECTED`, `INFERRED`, `USER_DECISION`, `UNKNOWN`, `STALE`
+- **confidence:** `HIGH`, `MEDIUM`, `LOW`
+- **sourceType:** `detector`, `file`, `git`, `user`, `ai`
+
+Uncertainty is first-class: record `INFERRED`/`LOW` or `UNKNOWN` rather than guessing.
+
+## Staleness
+
+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.
+
+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.
+
+## What to store / not store
+
+Store: architecture, business rules, important modules, conventions, commands, test strategy, deployment facts, integrations, decisions, known constraints, important unresolved problems.
+
+Never store: source files, `node_modules`/generated output, chat transcripts, temporary logs, secrets or env values, machine-specific absolute paths. The CLI enforces the last two (secret patterns and absolute paths are rejected) and `doctor` re-checks.
+
+## Other records
+
+- **Decisions** (`decisions/0001-title.md`): human-readable Markdown with front matter; append-only. Superseding marks the old decision `superseded` and keeps its text.
+- **Tasks** (`tasks/…`): see [testing.md](testing.md) and [routing.md](routing.md).
+- **Sessions**: goal, work completed, areas, tests run, decisions, remaining issues, next step. Never a transcript.
+- **Context documents** (`context/*.md`): `architecture.md`, `conventions.md`, `testing.md`, `integrations.md` are written by the agent during onboarding and kept short.
+
+## 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.

package/docs/portability.md

@@ -0,0 +1,40 @@
+# Portability
+
+## Shared vs machine-local
+
+| Shared (commit it) | Machine-local (git-ignored) |
+| --- | --- |
+| `project.json`, `context/`, `decisions/`, `tasks/`, `sessions/`, `analysis/discovery.json`, `state/analysis.json` | `local/` (lock file, integration detection, backups), `analysis/onboarding-prompt.md`, `analysis/refresh-prompt.md` |
+
+`.devworkspace/.gitignore` is created by `init` and repaired by `doctor --fix`. Your root `.gitignore` is never modified; `doctor` warns if it hides `.devworkspace/` entirely.
+
+Agent files (`CLAUDE.md` block, `.claude/skills/devworkspace/`) are committed like any other project file. They are not part of the export bundle because they are fully regenerated, previewably and idempotently, by `devworkspace agent install`.
+
+## Identity
+
+`project.json` holds a random `projectId`. No absolute path is stored in portable files, so moving `D:\Company\CRM` to `C:\Projects\CRM` (or a different OS) needs no migration. `doctor` flags absolute paths that slip into knowledge, and `fact add` rejects them.
+
+## Another computer
+
+```bash
+git clone <repo> && cd <repo>
+npx devworkspace doctor
+```
+
+Machine-specific state (integration detection, locks) is regenerated on demand. If the Claude instructions and knowledge were committed, doctor reports `READY`. Run `devworkspace refresh` after pulling a large change to re-validate knowledge.
+
+## Export / import (when Git is not the transport)
+
+```bash
+devworkspace export --out knowledge.json        # context, decisions, tasks, sessions, discovery, project.json
+devworkspace import knowledge.json --dry-run
+devworkspace import knowledge.json
+```
+
+- Export contains no `local/` state, prompts, secrets or temp files; it refuses to run if the workspace holds secret-like values.
+- Import validates the entire bundle first (format, schema version, path allow-list, size, secrets, JSON) and changes nothing if anything is wrong.
+- It requires the same `projectId` (or `--allow-different-project`), never replaces `project.json`, merges `facts.json` per fact (newer wins unless that would lower authority), keeps the newer task, and reports every differing file as a **conflict** instead of overwriting. `--overwrite` replaces conflicts and keeps backups in `local/backups/import-…`.
+
+## Schema versions and migration
+
+Every persistent JSON file carries `schemaVersion`. A newer CLI reads older files by migrating in memory and, when it writes a file whose version changes, first copies the old one to `local/backups/`. `devworkspace migrate` upgrades everything explicitly (all-or-nothing plan, shared backup folder). A file from a **newer** schema is never modified: commands fail with an "upgrade DevWorkspace" hint. Schema v1 is the first release, so the migration registry is empty today; the machinery is tested with injected migrations.

package/docs/routing.md

@@ -0,0 +1,51 @@
+# Routing: how requests become workflows
+
+After onboarding you talk to Claude normally. The installed `devworkspace` skill makes it classify each request and apply a proportionate workflow. The table below is rendered from `src/tasks/routing.ts`, the single source of truth, and a test fails if this page drifts from it.
+
+| Type | Nature | Max context | Verification |
+| --- | --- | --- | --- |
+| QUESTION | read-only, no task file | L5 | None. Do not modify files or run tests. |
+| BUG | modifies code, tracked task | L6 | Regression test, applicable suite, typecheck, lint, build (whatever the testing contract marks required). |
+| FEATURE | modifies code, tracked task | L6 | Targeted tests, regression, typecheck, lint, build, review. |
+| REFACTOR | modifies code, tracked task | L6 | Baseline vs after (no regressions), typecheck, lint, build, review. |
+| DOCUMENTATION | modifies code, no task file | L4 | Only checks that apply to documentation. |
+| TESTING | modifies code, tracked task | L6 | Affected tests, typecheck, lint. |
+| PERFORMANCE | modifies code, tracked task | L6 | Before/after measurement, regression suite, build. |
+| SECURITY | modifies code, tracked task | L6 | Regression and exploit test, typecheck, lint, build, review. |
+| ARCHITECTURE | modifies code, tracked task | L6 | Baseline vs after, typecheck, lint, build, review. |
+| RELEASE | modifies code, tracked task | L6 | Everything in the testing contract. |
+| MAINTENANCE | modifies code, tracked task | L4 | Lint, build, tests if behaviour could change. |
+
+Context levels: L1 instructions · L2 relevant facts · L3 relevant decisions · L4 Graphify structure · L5 specific source files · L6 tests and deeper implementation context. Agents stop at the shallowest level that answers the request.
+
+## Expected behaviour (executable specification)
+
+These are asserted in `tests/unit/routing.test.ts` and `tests/integration/flows.test.ts`. The classifier is a keyword heuristic that *proposes* a type (`devworkspace task new "<request>"`); ambiguous input falls back to the safest type, a read-only QUESTION, with low confidence.
+
+| Request | Type | Expected behaviour |
+| --- | --- | --- |
+| "Where is authentication?" | QUESTION | Read-only investigation using facts and Graphify. No file changes, no tests, no task file. |
+| "Only explain this file." | QUESTION + `no-modify` | No modifications, no tests. |
+| "Fix login validation bug." | BUG | Investigate → reproduce where practical → regression test (confirm it fails) → fix → targeted + regression → typecheck/lint/build → review if enabled. Knowledge updated only if something durable was learned. |
+| "Add Redis caching." | FEATURE | Read architecture and decisions, identify scope, acceptance criteria and plan, tests, implementation, verification, review, then update knowledge (new integration/decision). |
+| "Refactor authentication." | REFACTOR | Deeper architecture analysis, **baseline test results recorded first**, plan, small verified steps, regression compared against the baseline, review. |
+| "Run tests but don't fix anything" | TESTING + `no-fix` | Run and report. Do not change code. |
+| "Add feature X but only make a plan" | FEATURE + `plan-only` | Read-only: produce the plan, change nothing. |
+
+## User overrides
+
+Phrases such as *only explain*, *do not modify anything*, *only make a plan*, *don't commit*, *do not run e2e*, *don't run the tests* are parsed into constraints (`no-modify`, `plan-only`, `no-commit`, `no-e2e`, `no-tests`, `no-fix`). They are stored on the task. A verification the user told the agent to skip stays on the task, marked `SKIPPED` with reason `user-override`: the gate accepts it **with a warning**, so completion is reported as less certain rather than silently complete.
+
+## Task lifecycle
+
+`IDEA → SPECIFIED → PLANNED → IN_PROGRESS → TESTING → REVIEW → COMPLETED`, with `BLOCKED` and `FAILED` as exits (`FAILED`/`COMPLETED` can be reopened to `IN_PROGRESS`). Illegal jumps are refused with the allowed list.
+
+### Completion gate
+
+`devworkspace task status <id> COMPLETED` is refused unless:
+
+- every required verification is `PASS` (or `SKIPPED` with reason `user-override`);
+- if a baseline was recorded: failures did not increase and passing tests did not decrease (214/3 → 218/3 is fine; 214/3 → 210/7 blocks);
+- for code-changing tasks: the agent attested that no user work was overwritten, knowledge was reviewed, and the final repository state was inspected, and a completion summary exists.
+
+Required checks come from the project's own testing contract; checks the project does not have are never demanded.

package/docs/security.md

@@ -0,0 +1,44 @@
+# Security and privacy
+
+## Privacy: what DevWorkspace does and does not do
+
+- **Local only.** The CLI makes no network requests and sends nothing anywhere. There is **no telemetry**.
+- **What it reads:** directory listings; `package.json`-style manifests and lockfile names; dependency files (`pyproject.toml`, `requirements*.txt`, `Pipfile`, `Cargo.toml` workspace section, `pnpm-workspace.yaml`); `.gitignore`/`.devworkspaceignore`; its own `.devworkspace/` files; Claude Code settings files and skill directories (to detect plugins); and Git state via read-only Git commands. It hashes files you cite as evidence for facts.
+- **What it stores:** counts, names of detected frameworks, the testing contract, relative file paths, hashes and the knowledge you or the agent record. Not source code.
+- **What it ignores:** `.git`, `node_modules`, build output, caches, virtual environments, anything in `.gitignore` or `.devworkspaceignore`, symlinks, and files over the size limits. Binary files are skipped.
+- **Important:** the generated prompts cause *your chosen AI agent* to read repository content. DevWorkspace cannot control what that agent's provider does with it. Review your agent's data policy.
+
+Ignore precedence: hard-coded skip list (always) → root and nested `.gitignore` → `.devworkspaceignore` (root). Credential files are never *read* regardless of ignore rules, and are listed by name only.
+
+## Secrets
+
+- Sensitive files (`.env`, `.env.*` except `.example/.sample/.template/.dist`, `*.pem`, `*.key`, `*.p12`, `id_rsa*`, `credentials.*`, `secrets.*`, `.npmrc`, `*.tfvars`, service-account JSON, …) are **never read**. `safeReadText` is the only way analysis reads repository text and it refuses them.
+- Every write path (facts, tasks, decisions, sessions, export) rejects text matching credential patterns (private keys, AWS/GitHub/Slack/npm/OpenAI-style tokens, JWTs, URLs with embedded credentials, `password=…`-style assignments). Logs are redacted.
+- Patterns are heuristic. They reduce risk; they are not a guarantee. `doctor` re-scans `.devworkspace/` and warns if a credential-like file is **tracked by Git**.
+
+## Prompt injection
+
+Repository files are untrusted data. The installed instructions and every generated prompt state that source, comments, READMEs, docs, fixtures, test data and generated content are things to inspect, never instructions, and cannot override the user, system instructions, security policy or DevWorkspace's rules. DevWorkspace does not copy README/comment prose into prompts (a test checks that attacker text in a fixture never appears in generated output). This reduces the attack surface but cannot make a model immune; keep the agent's tool permissions sensible.
+
+## Filesystem safety
+
+- Paths from imports/knowledge are validated: no absolute paths, `..`, backslashes, NUL, Windows-reserved characters or trailing dots/spaces; writes re-resolve inside the workspace and refuse symlink escapes.
+- Writes are atomic (temp file → fsync → rename). Mutating commands hold an advisory lock. Interrupted runs leave the previous file intact; `doctor` reports leftover `.tmp` files.
+- Nothing deletes user files. `doctor --fix` only *creates* missing folders/ignore rules.
+- `export` refuses to run if the workspace contains secret-like values. `import` validates **everything** (format, schema version, path allow-list, size, secrets, JSON validity) before writing anything, never replaces `project.json`, and never overwrites differing local files unless `--overwrite` (with backups).
+
+## Subprocesses
+
+Only `git` is executed, with argument arrays and `shell: false`, with timeouts and output caps. `.cmd`/`.bat` shims are never executed. Repository scripts are never run by DevWorkspace.
+
+## Git safety
+
+DevWorkspace issues only read-only Git commands. The generated instructions require `git status` before edits, protection of uncommitted changes, and forbid `git reset --hard`, `git clean -fd`, force-push and branch deletion without explicit user authorisation.
+
+## Supply chain
+
+Zero runtime dependencies. Dev-only tools (TypeScript, Vitest, ESLint) are pinned by `package-lock.json`; CI runs `npm audit`. Release publishing uses an explicit manual trigger with npm provenance (see [contributing](contributing.md)).
+
+## Reporting vulnerabilities
+
+Open a private security advisory on the repository (once published). Do not file public issues containing exploit details or real secrets.

package/docs/testing.md

@@ -0,0 +1,58 @@
+# Testing contract and verification
+
+## The testing contract
+
+`devworkspace analyze` infers which verification commands the *project* has and stores them in `.devworkspace/context/commands.json`:
+
+| Check | Available | Command | Required |
+| --- | --- | --- | --- |
+| typecheck | yes | `npm run typecheck` | yes |
+| unit | yes | `npm test` | yes |
+| integration | yes | `npm run test:integration` | context |
+| e2e | yes | `npm run test:e2e` | context |
+| lint | yes | `npm run lint` | yes |
+| build | yes | `npm run build` | yes |
+
+`required` is `yes` (always applies to code changes), `context` (only when relevant to the change) or `no`. Entries you or the agent edit by hand get `origin: "user"` and are never overwritten by later analysis.
+
+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.
+
+### 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.
+
+## Task-specific verification
+
+Questions need none; docs need only documentation checks; bugs, features and refactors derive their checks from the contract (see [routing](routing.md)). Baseline handling:
+
+```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
+```
+
+Pre-existing failures are recorded, not blamed on new work. Regressions block completion.
+
+## Failure reporting
+
+```text
+STATUS: BLOCKED
+Unit tests: FAIL   Typecheck: PASS   Lint: PASS   Build: FAIL
+Failure: <actual error>
+Task is not considered complete.
+```
+
+## Testing DevWorkspace itself
+
+```bash
+npm test                 # unit + integration + e2e (vitest)
+npm run test:unit | test:integration | test:e2e
+npm run coverage         # thresholds enforced (stricter on security, paths, tasks, knowledge, portability)
+npm run typecheck && npm run lint
+npm run smoke            # pack → install tarball into clean dirs → run the real CLI (local, --prefix, npx, PowerShell)
+npm run release:check    # the full pre-publish gate; never publishes
+```
+
+Layers: **unit** (pure logic, security, paths incl. `path.win32`, schemas, routing scenarios, prompts), **integration** (command flows through the real CLI in-process with a hermetic home directory), **e2e** (the ten acceptance scenarios, Windows-style paths, large repo simulation, concurrency, hostile imports). Fixtures live in `fixtures/` (Express, React/Vite, Next.js, NestJS, FastAPI, monorepo, no tests, failing tests, existing AI files, prompt injection); scenarios that need Git state, secrets or unusual paths are built at test time.
+
+The generated prompts are tested for *behaviour*, not snapshots: `prompts/requirements.ts` lists what every onboarding/refresh prompt must instruct (untrusted-data rule, no secrets, evidence, git safety, testing contract, completion gate, memory rules, …), and `validatePrompt` is used by the tests and by `doctor`.

package/docs/troubleshooting.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+Start with `devworkspace doctor`. Every warning/failure includes a remediation line.
+
+| Problem | What to do |
+| --- | --- |
+| **Unsupported Node version** | Needs Node ≥ 20.11. `node -v`; install from nodejs.org or use nvm/fnm. `doctor` shows the requirement. |
+| **Git unavailable** | Install Git. DevWorkspace still works but cannot report branch/working-tree state or tracked-secret problems, and Claude cannot protect uncommitted changes. |
+| **Not a Git repository** | Fine. `status` shows `Git: not a repository`. Consider `git init` so changes can be reviewed and reverted. |
+| **"No DevWorkspace found"** | Run `devworkspace init` in the project root. Commands search upward from the current directory; use `--cwd <dir>` if you are elsewhere. |
+| **Graphify unavailable / no graph** | `uv tool install graphifyy` (or `pipx`), `graphify install --project`, then run `/graphify .` in Claude Code. DevWorkspace keeps working without it. |
+| **Agent Skills / Ponytail "Unverified"** | Claude Code owns plugin state, so this is best-effort. In Claude Code run `/plugin` to see installed plugins, or install: `/plugin marketplace add addyosmani/agent-skills` → `/plugin install agent-skills@addy-agent-skills`; `/plugin marketplace add DietrichGebert/ponytail` → `/plugin install ponytail@ponytail`. |
+| **Claude config conflict** (`agent install` reports `CONFLICT`) | Unbalanced `devworkspace:start/end` markers in `CLAUDE.md`, or a user-authored skill at `.claude/skills/devworkspace/`. Fix/remove the stray marker or rename your skill, then re-run. Nothing was changed. |
+| **Claude ignores my `AGENTS.md`** | Claude reads `AGENTS.md` only when no `CLAUDE.md` exists. `agent install` adds an `@AGENTS.md` import when it creates `CLAUDE.md`; if you created `CLAUDE.md` yourself, add `@AGENTS.md` to it. |
+| **Stale context** | `devworkspace refresh`, then paste `.devworkspace/analysis/refresh-prompt.md` into Claude. Facts without cited `--file` sources can never be proven stale. |
+| **Want to start completely fresh** | `devworkspace reset --yes` (add `--include-agent-files` to also remove the Claude block and skill), then `devworkspace init`. `reset` without `--yes` only prints a plan. |
+| **Corrupted workspace** (`malformed JSON`, schema errors) | `git checkout -- .devworkspace/<file>`; or copy a backup from `.devworkspace/local/backups/`. A newer-schema file means upgrade DevWorkspace. Leftover `*.tmp` files come from an interrupted write and are safe to delete. |
+| **"Another DevWorkspace process is modifying this workspace"** | Wait. If no DevWorkspace process is running, delete `.devworkspace/local/workspace.lock` (stale locks from dead processes are normally broken automatically). |
+| **Tests were failing before my task** | Record a baseline: `devworkspace task tests <id> --phase baseline --passed N --failed M`. Only *increases* in failures block completion. |
+| **Project moved / different drive** | Nothing to do; identity is an id, not a path. `doctor` warns if knowledge contains absolute paths. |
+| **Package manager unavailable** | The testing contract is inferred from files, so it lists `pnpm`/`yarn` commands even if not installed. Edit `context/commands.json` (set `origin: "user"`) to use what you have. |
+| **Windows: `EPERM` on write** | Editors, antivirus or indexers can briefly lock files; writes retry for ~2 s. If it persists, close the program holding the file. |
+| **Windows: PowerShell blocks `devworkspace.ps1`** | `npm` creates `.cmd` and `.ps1` shims. Run via `devworkspace.cmd`, `npx devworkspace`, or relax the execution policy for your user (`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`). |
+| **`.devworkspace` not appearing in Git** | The root `.gitignore` ignores it. Remove that rule; `.devworkspace/.gitignore` already excludes the machine-local parts. |
+| **Analysis seems incomplete** | `status`/`doctor` says "partial" when file or depth limits were hit. Raise `settings.maxFiles` in `project.json` or add `.devworkspaceignore` entries for generated folders. |
+
+Add `--debug` to any command for stack traces and debug logs (secrets are still redacted).

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "devworkspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "devworkspace": "dist/cli/main.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "!docs/implementation"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "coverage": "vitest run --coverage",
+    "audit:security": "npm audit --omit=dev --audit-level=high",
+    "smoke": "node scripts/smoke.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "claude-code",
+    "agent",
+    "workspace",
+    "developer-tools",
+    "knowledge",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SHIKHIL8137/devworkspace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SHIKHIL8137/devworkspace/issues"
+  },
+  "homepage": "https://github.com/SHIKHIL8137/devworkspace#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  }
+}