nono-skills 0.1.0 → 0.2.0

package/README.md

@@ -2,15 +2,16 @@
 
 A lightweight, reasoning-first engineering workflow pack for Codex. It provides 15 namespaced skills built around outcomes, evidence, verification, material decisions, and human escalation.
 
-The pack is designed for capable reasoning models such as GPT-5.6 Sol. Skills define intent and guardrails while leaving implementation strategy to the model. They do not impose mandatory approval gates, worktrees, test-first development, or subagent orchestration.
+The pack is designed for capable reasoning models such as GPT-5.6 Sol. Skills define intent and guardrails while leaving implementation strategy to the model. They do not impose mandatory design or implementation approval gates, worktrees, test-first development, or subagent orchestration. The only built-in gate is consent before Codex creates a durable workspace that the user did not explicitly request.
 
 ## How it works
 
-- Codex can select a skill implicitly from its focused trigger description, or you can invoke one explicitly.
-- Each skill defines its purpose, inputs, outputs, rules, decision-log updates, and conditions that require human judgment.
-- Workflow artifacts are optional. Skills update existing artifacts but do not create missing `docs/agent/` files unless you request durable artifacts or run `init`.
-- Decision logs capture costly, contractual, ambiguous, or risk-bearing choices—not routine edits or shell commands.
-- Overlapping intents have explicit boundaries: brainstorm before direction, plan after direction, implement general changes, fix-findings for validated findings, review for general defects, and security-review when security is the primary objective.
+- Install once, start a new Codex task, and ask for engineering work naturally. Explicit `$engineering:<skill>` invocation remains optional.
+- Small tasks stay artifact-free.
+- For work worth resuming or tracking, Codex proposes an isolated `docs/agent/work/<work-id>/` workspace and asks once before creating it.
+- An explicit request for a spec, plan, log, findings tracker, handoff, or named existing work item already grants artifact consent for that scope.
+- After approval, Codex maintains that work item's spec, plan, material decisions, findings, and handoff as needed without asking for every file update.
+- Codex asks again only for an ambiguous work-item match, material scope expansion, or an action that needs new authority.
 
 ## Install
 
@@ -20,7 +21,23 @@ Requires Node.js 20 or newer and Codex CLI with plugin support.
 npx nono-skills install
 ```
 
-Start a new Codex task after installation. Skills appear under the `engineering` namespace:
+Then work normally:
+
+```text
+Implement user authentication and keep me updated.
+```
+
+For a durable task, Codex may propose:
+
+```text
+This work has multiple stages and should remain resumable. I propose
+docs/agent/work/2026-07-16-user-auth/ for its spec, plan, and material
+decisions. Approve this workspace?
+```
+
+Declining keeps the work in the current conversation and creates no workflow files.
+
+Skills appear under the `engineering` namespace when you want to invoke one explicitly:
 
 ```text
 $engineering:plan
@@ -60,14 +77,16 @@ $engineering:database-design
 | Design a stable consumer contract | `$engineering:api-design` |
 | Design persistent data around invariants | `$engineering:database-design` |
 
-## Initialize a project
+## Optional repository guidance
 
-Initialization is optional. Add concise repository guidance and shared agent artifacts to the current project with:
+`init` is optional. The plugin works without it. Run this only when the repository needs a starter `AGENTS.md` for its setup commands, architecture rules, verification commands, and local conventions:
 
 ```bash
 npx nono-skills init
 ```
 
+Initialization no longer creates task artifacts. Existing 0.1.0 singleton files under `docs/agent/` are preserved and new durable work uses per-work-item directories.
+
 Preview changes or target another repository:
 
 ```bash
@@ -81,8 +100,6 @@ Existing differing files are reported as conflicts and no files are written. To
 npx nono-skills init --force
 ```
 
-Project artifacts include a repository-focused `AGENTS.md` and `docs/agent/` templates for specs, plans, decisions, findings, and handoffs. Without initialization, skills return the same material information in their final response instead of creating workflow files.
-
 ## Maintain the installation
 
 ```bash
@@ -93,13 +110,13 @@ npx nono-skills uninstall
 
 Start a new Codex task after install or update so the refreshed skill definitions are loaded.
 
-Uninstall preserves project files. Remove only project files that still match their installed checksums with:
+Uninstall preserves project files. Remove only installer-owned project files that still match their installed checksums with:
 
 ```bash
 npx nono-skills uninstall --purge-project /path/to/project
 ```
 
-Modified project files are always preserved.
+Modified project files are always preserved. Purge never removes user-owned `docs/agent/work/<work-id>/` directories.
 
 ## Moving away from Superpowers
 
@@ -113,7 +130,8 @@ This pack intentionally does not reproduce strict test-first enforcement, automa
 - Marketplace edits preserve unrelated entries and metadata.
 - Install and update roll back plugin source and marketplace changes when Codex registration fails.
 - Project files are never overwritten without `--force` and a backup.
-- Skills do not create missing workflow artifacts implicitly.
+- Codex-proposed durable workspaces require one explicit approval before creation; explicit artifact requests already provide consent for their scope.
+- Work-item directories are user-owned, and uninstall purge never removes them.
 - The CLI never disables or removes Superpowers automatically.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nono-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install a lightweight engineering workflow plugin for Codex.",
   "author": "thitikorn.j",
   "type": "module",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight, reasoning-first engineering workflows for Codex.",
   "author": {
     "name": "thitikorn.j"

package/plugin/references/workspaces.md

@@ -0,0 +1,61 @@
+# Adaptive Workspaces
+
+Use this protocol before deciding whether to create, select, or update workflow artifacts. The active skill still owns its task-specific behavior.
+
+## 1. Classify persistence
+
+Classify the task as transient or durable using judgment, not fixed size thresholds.
+
+Durable state is justified when the user asks for it, work is likely to cross Codex tasks or owners, multiple outcomes need tracking, migration/security/release/compatibility risk is material, findings need a fix lifecycle, or decisions must survive the conversation. Keep localized one-shot work transient unless the user asks otherwise.
+
+## 2. Establish consent
+
+Explicit requests for a spec, plan, progress log, decision log, findings tracker, handoff, or named existing work item already grant artifact consent for that scope.
+
+When Codex decides a new durable workspace would help, state why, the proposed path, scope, and initial files, then ask once before creating the workspace. Approval covers artifact maintenance inside that work-item scope; it does not authorize unrelated implementation, commits, pushes, deployments, production changes, destructive actions, external writes, or spend.
+
+If the user declines, create no equivalent files elsewhere. Continue safely in chat and report material decisions and residual risk in the final response.
+
+## 3. Resolve or create the work item
+
+Resolve in this order:
+
+1. the work item already approved in the current Codex task
+2. an explicit work ID, path, issue, or ticket from the user
+3. an exact issue or ticket metadata match
+4. an exact current non-default branch match to one active item
+5. one active item whose goal and scope clearly match
+
+Recency alone is never sufficient. Ask the user when multiple items remain plausible.
+
+For new work, prefer `issue-<number>-<slug>` when an issue exists; otherwise use `YYYY-MM-DD-<goal-slug>`. Add a numeric suffix on collision and never overwrite unrelated contents.
+
+## 4. Maintain the workspace
+
+The anchor is `docs/agent/work/<work-id>/spec.md` with YAML front matter containing `work_id`, `title`, `status`, optional `issue`, optional `branch`, `created`, and `updated`. Status is `active`, `blocked`, `completed`, or `superseded`.
+
+Start every new approved work item with `status: active`; set both `created` and `updated` when creating its anchor. Refresh `updated` on every authoritative work-item artifact or status mutation. Keep the current status truthful so work-item resolution never relies on stale `active` metadata.
+
+Use `blocked` only when in-scope progress cannot continue because of a concrete unresolved dependency, missing input or authority, or required external change. Record the blocker and resumption condition in `plan.md` or `handoff.md` as applicable; return the status to `active` and refresh `updated` when the blocker is resolved.
+
+Use `completed` only when all in-scope acceptance criteria and tracked plan items are satisfied, required verification evidence is recorded, and no unresolved blocking findings or work remain. Set the status to `completed` and refresh `updated`; do not move or delete the work-item directory.
+
+Use `superseded` only when the work is intentionally replaced. Record the reason and successor or reference as a material decision, set the status to `superseded`, and refresh `updated`; do not move or delete the work-item directory.
+
+Reopening completed work changes its status to `active`, refreshes `updated`, and records the material reason.
+
+Create files lazily:
+
+- `spec.md` for every approved durable work item
+- `plan.md` when outcomes, dependencies, or verification targets need tracking
+- `decisions.md` on the first material decision
+- `findings.md` when findings need lifecycle tracking
+- `handoff.md` only when work remains or ownership changes
+
+Do not create a global mutable index or move completed work-item directories. Log only contractual choices, meaningful ambiguity resolutions, accepted risks or tradeoffs, material re-plans, and assumptions future work must preserve.
+
+## 5. Respect scope and failures
+
+The original request controls implementation authority: an implementation request permits ordinary in-repository edits, while a planning request stops after planning. Ask again for material scope expansion, breaking or destructive behavior, production or external-system mutation, or significant spend.
+
+Repository instructions override the default artifact location. If creation fails, report exactly what exists and continue in chat when safe. Never silently create artifacts at another path. Treat existing 0.1.0 singleton files as legacy user content: read them only when explicitly named or unambiguously relevant, and never move, merge, or delete them automatically.

package/plugin/skills/api-design/SKILL.md

@@ -9,6 +9,10 @@ description: Use when creating or changing an HTTP, RPC, event, webhook, library
 
 Define a consumer-centered contract with precise semantics, failure behavior, authorization, compatibility, and operability before or alongside implementation.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Consumer use cases, domain language, invariants, and quality constraints
@@ -33,7 +37,7 @@ Define a consumer-centered contract with precise semantics, failure behavior, au
 ## Decision-log updates
 
 Record public contract choices, compatibility policy, naming or semantic decisions likely to recur, idempotency and consistency guarantees, and rejected alternatives with consumer impact.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append contract choices and compatibility consequences to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/architecture-review/SKILL.md

@@ -9,6 +9,10 @@ description: Use when architecture is the primary review objective for boundarie
 
 Evaluate whether system structure supports the stated product and operational needs, using repository evidence rather than generic pattern scoring.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Goals, constraints, quality attributes, diagrams or proposals
@@ -33,7 +37,7 @@ Evaluate whether system structure supports the stated product and operational ne
 ## Decision-log updates
 
 Record accepted boundaries, ownership, technology choices, quality-attribute priorities, and deliberately accepted coupling or debt. Capture alternatives and migration consequences.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append structural tradeoffs or accepted architecture risk to the selected work item's decisions.md and track actionable defects in findings.md; otherwise report them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/brainstorm/SKILL.md

@@ -9,6 +9,10 @@ description: Use when a product, feature, technical approach, workflow, or probl
 
 Turn an unclear opportunity into a small set of distinct, evidence-aware options and a recommended direction without prematurely implementing one.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Desired outcome, users, constraints, known pain, and prior attempts
@@ -34,7 +38,7 @@ Turn an unclear opportunity into a small set of distinct, evidence-aware options
 ## Decision-log updates
 
 Record the selected direction, rejected alternatives when the tradeoff may recur, key assumptions to validate, and the next experiment. Keep unselected raw ideas out of the durable log unless they explain a decision.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append the accepted direction, recurring tradeoffs, assumptions, and next experiment to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/database-design/SKILL.md

@@ -9,6 +9,10 @@ description: Use when designing or changing persistent data models, schemas, con
 
 Create a data model that enforces domain invariants, serves proven access patterns, evolves safely, and has explicit consistency and lifecycle semantics.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Domain concepts, invariants, lifecycle, ownership, and access patterns
@@ -33,7 +37,7 @@ Create a data model that enforces domain invariants, serves proven access patter
 ## Decision-log updates
 
 Record data ownership, normalization tradeoffs, identifiers, consistency model, transaction boundaries, retention, tenant isolation, and irreversible schema choices. Link migration and rollback implications.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append invariant, consistency, migration, and operational choices to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/debug/SKILL.md

@@ -9,6 +9,10 @@ description: Use when behavior is wrong, failing, flaky, slow, inconsistent, or
 
 Reproduce the symptom, trace the failing path, falsify competing hypotheses, isolate root cause, and verify the requested resolution.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Exact symptom, error, payload, timing, environment, and expected behavior
@@ -33,7 +37,7 @@ Reproduce the symptom, trace the failing path, falsify competing hypotheses, iso
 ## Decision-log updates
 
 Record confirmed root cause, discarded high-likelihood hypotheses, material diagnostic pivots, chosen remediation tradeoffs, and remaining uncertainty. Avoid logging every command.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append the validated root cause, rejected material hypotheses, and consequential fix choices to the selected work item's decisions.md and create handoff.md only when work remains; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed debugging scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/estimate/SKILL.md

@@ -9,6 +9,10 @@ description: Use when software work needs an evidence-based range for effort, du
 
 Provide a transparent range derived from scope, dependencies, uncertainty, and comparable work rather than a false-precision point value.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Goal, acceptance criteria, proposed plan, and definition of done
@@ -33,7 +37,7 @@ Provide a transparent range derived from scope, dependencies, uncertainty, and c
 ## Decision-log updates
 
 Record the committed estimation basis, major assumptions, exclusions, selected scenario, and later changes that materially move the range. Do not log exploratory arithmetic.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append scope interpretations, estimation model changes, and accepted schedule tradeoffs to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/fix-findings/SKILL.md

@@ -9,6 +9,10 @@ description: Use when validated review, audit, QA, or security findings must be
 
 Resolve accepted findings at their root cause, preserve intended behavior, and produce evidence that each fix closes the reported failure.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Findings with evidence, severity, and expected outcome
@@ -33,7 +37,7 @@ Resolve accepted findings at their root cause, preserve intended behavior, and p
 ## Decision-log updates
 
 Record chosen remediations when alternatives have meaningful compatibility, security, performance, or operational tradeoffs. Link the decision to finding IDs and record any accepted residual risk.
-Use existing `docs/agent/findings.md` and `decision-log.md` files when present. If they are absent, report state changes and decisions in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, update the selected work item's findings.md with status and verification evidence, and append material remediation tradeoffs to decisions.md; otherwise report state changes and decisions in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/implement/SKILL.md

@@ -9,6 +9,10 @@ description: Use for general software implementation from a requirement, spec, i
 
 Deliver the smallest complete change that satisfies the contract, preserves unrelated behavior, and is verified in proportion to risk.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - User request and acceptance criteria
@@ -33,7 +37,7 @@ Deliver the smallest complete change that satisfies the contract, preserves unre
 ## Decision-log updates
 
 Record material implementation choices, deviations from the plan, assumptions that affect behavior, accepted tradeoffs, and why a simpler or established pattern was not used. Include verification or follow-up consequences.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append the decision to the selected work item's `decisions.md` and update its plan or handoff when applicable; otherwise include it in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/migration/SKILL.md

@@ -9,6 +9,10 @@ description: Use when data, schema, API, dependency, platform, infrastructure, o
 
 Design or execute a staged, observable, reversible transition with explicit compatibility windows, validation, and cleanup.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Source and target states, invariants, data volume, traffic, and downtime tolerance
@@ -33,7 +37,7 @@ Design or execute a staged, observable, reversible transition with explicit comp
 ## Decision-log updates
 
 Record compatibility windows, cutover criteria, data ownership, transformation rules, rollback limits, accepted downtime, and irreversible checkpoints. Link evidence for completing each phase.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append compatibility, sequencing, rollback, and point-of-no-return choices to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/plan/SKILL.md

@@ -9,16 +9,20 @@ description: Use when a software direction is defined enough to map multi-step,
 
 Turn the request and repository evidence into a decision-ready spec and a concise, verifiable execution map. Plan to the level warranted by risk; do not add ceremony to trivial work.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - User goal, constraints, and expected behavior
 - Applicable `AGENTS.md`, current code, tests, docs, issues, and runtime evidence
-- Existing `docs/agent/spec.md`, `plan.md`, and `decision-log.md`
+- The selected work item's spec, plan, and decisions when durable state is active
 
 ## Outputs
 
 - A decision-ready spec and concise execution map with testable acceptance criteria
-- When the artifact files already exist or the user requests durable planning, updated `docs/agent/spec.md` and `docs/agent/plan.md`
+- For approved durable work, updated `spec.md` and `plan.md` in the selected work-item directory
 - A short summary of assumptions and human decisions needed
 
 ## Rules
@@ -33,7 +37,7 @@ Turn the request and repository evidence into a decision-ready spec and a concis
 ## Decision-log updates
 
 Record scope interpretations, contract choices, rejected approaches with non-obvious tradeoffs, and material re-plans. Link each entry to the affected plan item.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append the decision to the selected work item's `decisions.md`; otherwise include it in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/refactor/SKILL.md

@@ -9,6 +9,10 @@ description: Use when internal code structure, naming, duplication, coupling, co
 
 Improve changeability and clarity while preserving behavior and keeping the diff proportionate to a concrete maintenance problem.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Refactoring goal or documented code smell
@@ -33,7 +37,7 @@ Improve changeability and clarity while preserving behavior and keeping the diff
 ## Decision-log updates
 
 Record new module boundaries, ownership changes, intentionally retained debt, compatibility constraints, and abstraction choices with long-term consequences. Routine renames and local cleanup do not need entries.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append boundary changes, compatibility assumptions, and accepted tradeoffs to the selected work item's decisions.md; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed refactoring scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/release-readiness/SKILL.md

@@ -9,6 +9,10 @@ description: Use when a change, branch, build, migration, or release candidate m
 
 Produce an evidence-backed `ready`, `not ready`, or `ready with accepted risks` verdict. Assessment does not authorize release actions.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Release scope, target environment, acceptance criteria, and rollout expectations
@@ -23,6 +27,7 @@ Produce an evidence-backed `ready`, `not ready`, or `ready with accepted risks`
 
 ## Rules
 
+- For a selected work item, read its acceptance criteria, current plan state, findings, and verification evidence when available before judging readiness; reading this state neither authorizes release nor by itself requires artifact mutation.
 - Inspect current state; do not rely on stale claims that checks passed.
 - Run the strongest safe local checks and distinguish local proof from CI, staging, and production proof.
 - Treat code complete, merge ready, deploy ready, deployed, and verified in production as separate states.
@@ -32,7 +37,7 @@ Produce an evidence-backed `ready`, `not ready`, or `ready with accepted risks`
 ## Decision-log updates
 
 Record risk acceptance, waived gates, rollout or rollback choices, and readiness verdict changes with evidence. Link unresolved findings and owners.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append only accepted release risk, waivers, rollback choices, and readiness-scope decisions to the selected work item's decisions.md; otherwise include them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/review/SKILL.md

@@ -9,6 +9,10 @@ description: Use for a general objective code, diff, PR, or fix review without e
 
 Find actionable correctness, compatibility, security, reliability, and maintainability defects in the requested change or scope. Review is read-only.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Review baseline and target: diff, commit, branch, files, or stated behavior
@@ -31,8 +35,8 @@ Find actionable correctness, compatibility, security, reliability, and maintaina
 
 ## Decision-log updates
 
-Record only review-scope interpretations or accepted risk decisions that future work must preserve. Put individual defects in an existing `docs/agent/findings.md`; otherwise report them in the final response.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+Record only review-scope interpretations or accepted risk decisions that future work must preserve.
+When durable state is approved, track defects and their lifecycle in the selected work item's findings.md and append only review-scope or accepted-risk decisions to decisions.md; otherwise report them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/security-review/SKILL.md

@@ -9,6 +9,10 @@ description: Use when security is the primary assessment objective for code, con
 
 Identify plausible, evidence-backed security weaknesses across trust boundaries, attacker-controlled inputs, identities, secrets, data, and operational controls. Review is read-only.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Defined scope, threat assumptions, and deployment context
@@ -31,8 +35,8 @@ Identify plausible, evidence-backed security weaknesses across trust boundaries,
 
 ## Decision-log updates
 
-Keep vulnerabilities in an existing `docs/agent/findings.md`; otherwise report sanitized findings in the final response. Log only accepted security tradeoffs, threat-model assumptions, compensating controls, or risk acceptance decisions.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+Log only accepted security tradeoffs, threat-model assumptions, compensating controls, or risk acceptance decisions.
+When durable state is approved, track sanitized vulnerabilities in the selected work item's findings.md and append accepted security tradeoffs, threat assumptions, compensating controls, or risk acceptance to decisions.md; otherwise report them in the final response.
 
 ## Escalate to the human
 

package/plugin/skills/test/SKILL.md

@@ -9,6 +9,10 @@ description: Use when software behavior needs new or improved unit, integration,
 
 Create the smallest reliable test set that proves important behavior and failure modes through stable public seams.
 
+## Workspace protocol
+
+Read `../../references/workspaces.md` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.
+
 ## Inputs
 
 - Behavioral contract, bug report, acceptance criteria, or changed code
@@ -33,7 +37,7 @@ Create the smallest reliable test set that proves important behavior and failure
 ## Decision-log updates
 
 Record material test-boundary choices, intentionally excluded coverage, chosen substitutes for unavailable dependencies, and risk accepted because a scenario cannot be automated. Routine test cases do not need entries.
-Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+When durable state is approved, append material test-boundary, fidelity, or coverage-risk decisions to the selected work item's decisions.md; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed testing scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.
 
 ## Escalate to the human
 

package/scripts/validate.mjs

@@ -3,6 +3,14 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { listFiles } from '../src/fs-safe.js';
+import {
+  assertCanonicalSkillInventory,
+  assertWorkspaceProtocolContract,
+} from '../src/plugin-contract.js';
+import {
+  assertSkillWorkspaceContract,
+  expectedDurableEndings,
+} from '../src/skill-contract.js';
 
 const root = path.resolve(import.meta.dirname, '..');
 const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
@@ -12,7 +20,14 @@ assert.equal(plugin.version, packageJson.version);
 
 const skillRoot = path.join(root, 'plugin', 'skills');
 const skillFiles = (await listFiles(skillRoot)).filter((file) => file.endsWith('/SKILL.md'));
-assert.equal(skillFiles.length, 15);
+const skillNames = skillFiles.map((file) => file.split(path.sep)[0]);
+assertCanonicalSkillInventory(skillNames);
+assert.deepEqual(
+  skillNames.sort(),
+  Object.keys(expectedDurableEndings).sort(),
+);
+const workspaceProtocol = await readFile(path.join(root, 'plugin', 'references', 'workspaces.md'), 'utf8');
+assertWorkspaceProtocolContract(workspaceProtocol);
 for (const relative of skillFiles) {
   const expectedName = relative.split(path.sep)[0];
   const content = await readFile(path.join(skillRoot, relative), 'utf8');
@@ -20,7 +35,7 @@ for (const relative of skillFiles) {
   const shortDescription = metadata.match(/short_description: "([^"]+)"/)?.[1];
   assert.match(content, new RegExp(`^---\\nname: ${expectedName}\\ndescription: .+\\n---`, 's'));
   assert.doesNotMatch(content, /TODO|Superpowers|\.codex\/skills/);
-  assert.match(content, /create workflow artifacts only when the user requests them/);
+  assertSkillWorkspaceContract(expectedName, content);
   assert.ok(shortDescription && shortDescription.length >= 25 && shortDescription.length <= 64);
   assert.doesNotMatch(metadata, /Reusable engineering workflow|for this task\./);
   assert.match(metadata, new RegExp(`default_prompt: ".*\\$${expectedName.replaceAll('-', '\\-')}\\b`));

package/src/cli.js

@@ -4,7 +4,7 @@ export const HELP = `nono-skills <command> [options]
 
 Commands:
   install                 Install the engineering Codex plugin
-  init [directory]        Add project guidance and agent artifacts
+  init [directory]        Add optional repository guidance
   update                  Update an owned plugin installation
   doctor                  Diagnose the plugin installation
   uninstall               Remove the owned plugin installation
@@ -60,7 +60,12 @@ export async function run(argv, context) {
     return 1;
   }
   if (options.version) {
-    stdout.write(`${context.version ?? '0.1.0'}\n`);
+    const version = context.packageVersion ?? context.version;
+    if (version === undefined) {
+      stderr.write('Package version is unavailable\n');
+      return 1;
+    }
+    stdout.write(`${version}\n`);
     return 0;
   }
   if (options.help) {

package/src/plugin-contract.js

@@ -0,0 +1,89 @@
+import assert from 'node:assert/strict';
+
+export const canonicalSkillNames = Object.freeze([
+  'api-design',
+  'architecture-review',
+  'brainstorm',
+  'database-design',
+  'debug',
+  'estimate',
+  'fix-findings',
+  'implement',
+  'migration',
+  'plan',
+  'refactor',
+  'release-readiness',
+  'review',
+  'security-review',
+  'test',
+]);
+
+function protocolClause(id, text) {
+  return Object.freeze({ id, text });
+}
+
+export const workspaceProtocolClauses = Object.freeze([
+  protocolClause('document.title', '# Adaptive Workspaces'),
+  protocolClause('document.purpose', 'Use this protocol before deciding whether to create, select, or update workflow artifacts. The active skill still owns its task-specific behavior.'),
+  protocolClause('classification.heading', '## 1. Classify persistence'),
+  protocolClause('classification.transient-durable', 'Classify the task as transient or durable using judgment, not fixed size thresholds.'),
+  protocolClause('classification.transient-default', 'Durable state is justified when the user asks for it, work is likely to cross Codex tasks or owners, multiple outcomes need tracking, migration/security/release/compatibility risk is material, findings need a fix lifecycle, or decisions must survive the conversation. Keep localized one-shot work transient unless the user asks otherwise.'),
+  protocolClause('consent.heading', '## 2. Establish consent'),
+  protocolClause('consent.explicit', 'Explicit requests for a spec, plan, progress log, decision log, findings tracker, handoff, or named existing work item already grant artifact consent for that scope.'),
+  protocolClause('consent.proposed', 'When Codex decides a new durable workspace would help, state why, the proposed path, scope, and initial files, then ask once before creating the workspace. Approval covers artifact maintenance inside that work-item scope; it does not authorize unrelated implementation, commits, pushes, deployments, production changes, destructive actions, external writes, or spend.'),
+  protocolClause('consent.decline', 'If the user declines, create no equivalent files elsewhere. Continue safely in chat and report material decisions and residual risk in the final response.'),
+  protocolClause('resolution.heading', '## 3. Resolve or create the work item'),
+  protocolClause('resolution.precedence', 'Resolve in this order:'),
+  protocolClause('resolution.current-task', '1. the work item already approved in the current Codex task'),
+  protocolClause('resolution.explicit-id', '2. an explicit work ID, path, issue, or ticket from the user'),
+  protocolClause('resolution.issue-match', '3. an exact issue or ticket metadata match'),
+  protocolClause('resolution.branch-match', '4. an exact current non-default branch match to one active item'),
+  protocolClause('resolution.scope-match', '5. one active item whose goal and scope clearly match'),
+  protocolClause('resolution.recency-ambiguity', 'Recency alone is never sufficient. Ask the user when multiple items remain plausible.'),
+  protocolClause('resolution.new-id', 'For new work, prefer `issue-<number>-<slug>` when an issue exists; otherwise use `YYYY-MM-DD-<goal-slug>`. Add a numeric suffix on collision and never overwrite unrelated contents.'),
+  protocolClause('workspace.heading', '## 4. Maintain the workspace'),
+  protocolClause('workspace.anchor', 'The anchor is `docs/agent/work/<work-id>/spec.md` with YAML front matter containing `work_id`, `title`, `status`, optional `issue`, optional `branch`, `created`, and `updated`. Status is `active`, `blocked`, `completed`, or `superseded`.'),
+  protocolClause('workspace.creation-updated', 'Start every new approved work item with `status: active`; set both `created` and `updated` when creating its anchor. Refresh `updated` on every authoritative work-item artifact or status mutation. Keep the current status truthful so work-item resolution never relies on stale `active` metadata.'),
+  protocolClause('lifecycle.blocked', 'Use `blocked` only when in-scope progress cannot continue because of a concrete unresolved dependency, missing input or authority, or required external change. Record the blocker and resumption condition in `plan.md` or `handoff.md` as applicable; return the status to `active` and refresh `updated` when the blocker is resolved.'),
+  protocolClause('lifecycle.completed', 'Use `completed` only when all in-scope acceptance criteria and tracked plan items are satisfied, required verification evidence is recorded, and no unresolved blocking findings or work remain. Set the status to `completed` and refresh `updated`; do not move or delete the work-item directory.'),
+  protocolClause('lifecycle.superseded', 'Use `superseded` only when the work is intentionally replaced. Record the reason and successor or reference as a material decision, set the status to `superseded`, and refresh `updated`; do not move or delete the work-item directory.'),
+  protocolClause('lifecycle.reopen', 'Reopening completed work changes its status to `active`, refreshes `updated`, and records the material reason.'),
+  protocolClause('artifacts.lazy', 'Create files lazily:'),
+  protocolClause('artifacts.spec', '- `spec.md` for every approved durable work item'),
+  protocolClause('artifacts.plan', '- `plan.md` when outcomes, dependencies, or verification targets need tracking'),
+  protocolClause('artifacts.decisions', '- `decisions.md` on the first material decision'),
+  protocolClause('artifacts.findings', '- `findings.md` when findings need lifecycle tracking'),
+  protocolClause('artifacts.handoff', '- `handoff.md` only when work remains or ownership changes'),
+  protocolClause('artifacts.no-global-index', 'Do not create a global mutable index or move completed work-item directories. Log only contractual choices, meaningful ambiguity resolutions, accepted risks or tradeoffs, material re-plans, and assumptions future work must preserve.'),
+  protocolClause('scope.heading', '## 5. Respect scope and failures'),
+  protocolClause('scope.authority', 'The original request controls implementation authority: an implementation request permits ordinary in-repository edits, while a planning request stops after planning. Ask again for material scope expansion, breaking or destructive behavior, production or external-system mutation, or significant spend.'),
+  protocolClause('legacy.preservation', 'Repository instructions override the default artifact location. If creation fails, report exactly what exists and continue in chat when safe. Never silently create artifacts at another path. Treat existing 0.1.0 singleton files as legacy user content: read them only when explicitly named or unambiguously relevant, and never move, merge, or delete them automatically.'),
+]);
+
+export function assertCanonicalSkillInventory(actualNames) {
+  assert.deepEqual(
+    [...actualNames].sort(),
+    [...canonicalSkillNames].sort(),
+    'plugin skill inventory must contain exactly the 15 canonical skills',
+  );
+}
+
+export function assertWorkspaceProtocolContract(content) {
+  const authoritativeLines = content
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '');
+
+  for (const clause of workspaceProtocolClauses) {
+    assert.equal(
+      authoritativeLines.filter((line) => line === clause.text).length,
+      1,
+      `workspace protocol must include ${clause.id} exactly once`,
+    );
+  }
+
+  assert.deepEqual(
+    authoritativeLines,
+    workspaceProtocolClauses.map((clause) => clause.text),
+    'workspace protocol must contain only canonical authoritative clauses in order',
+  );
+}

package/src/skill-contract.js

@@ -0,0 +1,249 @@
+import assert from 'node:assert/strict';
+
+export const workspaceSection = `## Workspace protocol
+
+Read \`../../references/workspaces.md\` before selecting or creating workflow artifacts. Follow it for persistence, consent, work-item resolution, and lifecycle; this skill owns only the task-specific behavior below.`;
+
+export const expectedDurableEndings = Object.freeze({
+  'api-design': "When durable state is approved, append contract choices and compatibility consequences to the selected work item's decisions.md; otherwise include them in the final response.",
+  'architecture-review': "When durable state is approved, append structural tradeoffs or accepted architecture risk to the selected work item's decisions.md and track actionable defects in findings.md; otherwise report them in the final response.",
+  brainstorm: "When durable state is approved, append the accepted direction, recurring tradeoffs, assumptions, and next experiment to the selected work item's decisions.md; otherwise include them in the final response.",
+  'database-design': "When durable state is approved, append invariant, consistency, migration, and operational choices to the selected work item's decisions.md; otherwise include them in the final response.",
+  debug: "When durable state is approved, append the validated root cause, rejected material hypotheses, and consequential fix choices to the selected work item's decisions.md and create handoff.md only when work remains; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed debugging scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.",
+  estimate: "When durable state is approved, append scope interpretations, estimation model changes, and accepted schedule tradeoffs to the selected work item's decisions.md; otherwise include them in the final response.",
+  'fix-findings': "When durable state is approved, update the selected work item's findings.md with status and verification evidence, and append material remediation tradeoffs to decisions.md; otherwise report state changes and decisions in the final response.",
+  implement: "When durable state is approved, append the decision to the selected work item's `decisions.md` and update its plan or handoff when applicable; otherwise include it in the final response.",
+  migration: "When durable state is approved, append compatibility, sequencing, rollback, and point-of-no-return choices to the selected work item's decisions.md; otherwise include them in the final response.",
+  plan: "When durable state is approved, append the decision to the selected work item's `decisions.md`; otherwise include it in the final response.",
+  refactor: "When durable state is approved, append boundary changes, compatibility assumptions, and accepted tradeoffs to the selected work item's decisions.md; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed refactoring scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.",
+  'release-readiness': "When durable state is approved, append only accepted release risk, waivers, rollback choices, and readiness-scope decisions to the selected work item's decisions.md; otherwise include them in the final response.",
+  review: "When durable state is approved, track defects and their lifecycle in the selected work item's findings.md and append only review-scope or accepted-risk decisions to decisions.md; otherwise report them in the final response.",
+  'security-review': "When durable state is approved, track sanitized vulnerabilities in the selected work item's findings.md and append accepted security tradeoffs, threat assumptions, compensating controls, or risk acceptance to decisions.md; otherwise report them in the final response.",
+  test: "When durable state is approved, append material test-boundary, fidelity, or coverage-risk decisions to the selected work item's decisions.md; for a selected approved durable work item with an existing plan.md, update only relevant plan-item status and verification evidence for the performed testing scope, never invent unrelated work, and do not mark the work completed unless the workspace lifecycle criteria are satisfied; otherwise include material decisions and performed-scope verification in the final response.",
+});
+
+export const expectedRequiredResponsibilityLines = Object.freeze({
+  'release-readiness': Object.freeze([
+    '- For a selected work item, read its acceptance criteria, current plan state, findings, and verification evidence when available before judging readiness; reading this state neither authorizes release nor by itself requires artifact mutation.',
+  ]),
+});
+
+const planDurableOutput = '- For approved durable work, updated `spec.md` and `plan.md` in the selected work-item directory';
+
+export const allowedArtifactLines = Object.freeze(Object.fromEntries(
+  Object.entries(expectedDurableEndings).map(([name, ending]) => [
+    name,
+    Object.freeze(name === 'plan' ? [ending, planDurableOutput] : [ending]),
+  ]),
+));
+
+const workspaceBody = workspaceSection.slice(workspaceSection.indexOf('\n\n') + 2);
+const legacySingletonReference = /\bdecision-log\.md\b|\bdocs\/agent\/(?:spec|plan|decisions|decision-log|findings|handoff)\.md\b/i;
+const workflowArtifactReference = /\b(?:spec|plan|decisions|findings|handoff)\.md\b/i;
+
+function openingFence(line) {
+  const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+  if (!match || (match[1][0] === '`' && match[2].includes('`'))) return null;
+  return { character: match[1][0], length: match[1].length };
+}
+
+function closesFence(line, fence) {
+  const match = line.match(/^ {0,3}(`+|~+)[ \t]*$/);
+  return Boolean(
+    match
+      && match[1][0] === fence.character
+      && match[1].length >= fence.length,
+  );
+}
+
+function stripHtmlComments(line, commentOpen) {
+  let cursor = 0;
+  let text = '';
+  let hadComment = commentOpen;
+
+  while (cursor < line.length) {
+    if (commentOpen) {
+      const close = line.indexOf('-->', cursor);
+      if (close === -1) return { commentOpen: true, hadComment: true, text };
+      cursor = close + 3;
+      commentOpen = false;
+      hadComment = true;
+    } else {
+      const open = line.indexOf('<!--', cursor);
+      if (open === -1) {
+        text += line.slice(cursor);
+        break;
+      }
+      text += line.slice(cursor, open);
+      cursor = open + 4;
+      commentOpen = true;
+      hadComment = true;
+    }
+  }
+
+  return { commentOpen, hadComment, text };
+}
+
+function authoritativeLines(content) {
+  const sourceLines = content.split('\n');
+  const lines = [];
+  let fence = null;
+  let htmlCommentOpen = false;
+  let start = 0;
+
+  for (let index = 0; index < sourceLines.length; index += 1) {
+    const text = sourceLines[index];
+    const hasLineEnding = index < sourceLines.length - 1;
+    const end = start + text.length + (hasLineEnding ? 1 : 0);
+
+    if (fence) {
+      if (closesFence(text, fence)) fence = null;
+    } else {
+      const visible = stripHtmlComments(text, htmlCommentOpen);
+      htmlCommentOpen = visible.commentOpen;
+      if (!(visible.hadComment && visible.text.trim() === '')) {
+        if (/^(?: {4}|\t)/.test(visible.text)) {
+          start = end;
+          continue;
+        }
+        const openedFence = openingFence(visible.text);
+        if (openedFence) {
+          fence = openedFence;
+        } else {
+          lines.push({
+            text: visible.text,
+            start,
+            end,
+          });
+        }
+      }
+    }
+    start = end;
+  }
+
+  return lines;
+}
+
+function normalizedLevelTwoHeading(line) {
+  const match = line.match(/^ {0,3}##(?!#)(?:[ \t]+(.*))?[ \t]*$/);
+  if (!match) return null;
+  const name = (match[1] ?? '')
+    .trimEnd()
+    .replace(/[ \t]+#+$/, '')
+    .trim();
+  return name || null;
+}
+
+function markdownSections(lines) {
+  const sections = [];
+  for (const line of lines) {
+    const name = normalizedLevelTwoHeading(line.text);
+    if (name) sections.push({ name, start: line.start, bodyStart: line.end });
+  }
+  return sections;
+}
+
+function uniqueSectionIndex(name, sections, skillName) {
+  const indexes = sections
+    .map((section, index) => (section.name === name ? index : -1))
+    .filter((index) => index !== -1);
+  assert.equal(
+    indexes.length,
+    1,
+    `${skillName} must define exactly one normalized ${name} section`,
+  );
+  return indexes[0];
+}
+
+function sectionBody(content, sections, index) {
+  const end = sections[index + 1]?.start ?? content.length;
+  return content.slice(sections[index].bodyStart, end);
+}
+
+function normalizeInlineMarkdown(text) {
+  return text
+    .replace(/!?\[([^\]\n]*)\]\(((?:\\.|[^\\)\n])*)\)/g, '$1 $2')
+    .replace(/\\([\\`*_{}\[\]()#+\-.!])/g, '$1')
+    .replace(/[`*_~]/g, '');
+}
+
+function assertArtifactLines(name, lines) {
+  const allowedLines = allowedArtifactLines[name];
+  const normalizedLines = lines.map(({ text }) => ({
+    normalized: normalizeInlineMarkdown(text),
+    text,
+  }));
+
+  for (const { normalized } of normalizedLines) {
+    assert.doesNotMatch(
+      normalized,
+      legacySingletonReference,
+      `${name} must not reference legacy singleton workflow artifacts`,
+    );
+  }
+
+  for (const { normalized, text } of normalizedLines) {
+    if (workflowArtifactReference.test(normalized)) {
+      assert.ok(
+        allowedLines.includes(text.trim()),
+        `${name} must use only allowed authoritative workflow artifact lines`,
+      );
+    }
+  }
+
+  for (const allowedLine of allowedLines) {
+    assert.equal(
+      normalizedLines.filter(({ text }) => text.trim() === allowedLine).length,
+      1,
+      `${name} must include each allowed authoritative workflow artifact line exactly once`,
+    );
+  }
+}
+
+function assertRequiredResponsibilityLines(name, lines) {
+  for (const requiredLine of expectedRequiredResponsibilityLines[name] ?? []) {
+    assert.equal(
+      lines.filter(({ text }) => text.trim() === requiredLine).length,
+      1,
+      `${name} must include each required responsibility line exactly once`,
+    );
+  }
+}
+
+function finalAuthoritativeSectionLine(lines, sections, index) {
+  const start = sections[index].bodyStart;
+  const end = sections[index + 1]?.start ?? Number.POSITIVE_INFINITY;
+  return lines
+    .filter((line) => line.start >= start && line.start < end && line.text.trim() !== '')
+    .at(-1)?.text.trim();
+}
+
+export function assertSkillWorkspaceContract(name, content) {
+  const expectedEnding = expectedDurableEndings[name];
+  assert.ok(expectedEnding, `${name} must be in the expected skill inventory`);
+
+  const lines = authoritativeLines(content);
+  const sections = markdownSections(lines);
+  const purposeIndex = uniqueSectionIndex('Purpose', sections, name);
+  const workspaceIndex = uniqueSectionIndex('Workspace protocol', sections, name);
+  const decisionIndex = uniqueSectionIndex('Decision-log updates', sections, name);
+  assert.equal(
+    workspaceIndex,
+    purposeIndex + 1,
+    `${name} must place the Workspace protocol section immediately after Purpose`,
+  );
+  assert.equal(
+    sectionBody(content, sections, workspaceIndex).replace(/\n+$/, ''),
+    `\n${workspaceBody}`,
+    `${name} must use the exact Workspace protocol section`,
+  );
+
+  assert.equal(
+    finalAuthoritativeSectionLine(lines, sections, decisionIndex),
+    expectedEnding,
+    `${name} must end Decision-log updates with its durable-state contract`,
+  );
+
+  assertArtifactLines(name, lines);
+  assertRequiredResponsibilityLines(name, lines);
+}

package/src/uninstall.js

@@ -1,7 +1,8 @@
-import { readFile, rm, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readFile, realpath, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 
-import { sha256File } from './fs-safe.js';
 import { readMarketplace, removeMarketplaceEntry, verifyOwnership, writeJsonAtomic } from './plugin-state.js';
 
 async function exists(file) {
@@ -32,18 +33,163 @@ export async function uninstallPlugin({ home, runCodex }) {
   return { status: 'uninstalled', projectArtifactsPreserved: true };
 }
 
+function recordedPathPolicy(relative) {
+  const normalized = relative.replaceAll('\\', '/');
+  if (path.posix.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized)) {
+    return { safe: false };
+  }
+  const canonical = path.posix.normalize(normalized);
+  if (canonical === '..' || canonical.startsWith('../')) {
+    return { safe: false };
+  }
+  return {
+    safe: true,
+    canonical,
+    isWorkItem: canonical.toLowerCase().startsWith('docs/agent/work/'),
+  };
+}
+
+function isStrictDescendant(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== ''
+    && relative !== '..'
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+function sameFileSnapshot(left, right) {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs;
+}
+
+function isUnsafePathError(error) {
+  return error.code === 'ELOOP' || error.code === 'ENOTDIR';
+}
+
+async function inspectDescendant(root, candidate) {
+  if (!isStrictDescendant(root, candidate)) return { status: 'unsafe' };
+  const relative = path.relative(root, candidate);
+  let current = root;
+  let snapshot;
+  for (const component of relative.split(path.sep)) {
+    current = path.join(current, component);
+    try {
+      snapshot = await lstat(current, { bigint: true });
+    } catch (error) {
+      if (error.code === 'ENOENT') return { status: 'missing' };
+      if (isUnsafePathError(error)) return { status: 'unsafe' };
+      throw error;
+    }
+    if (snapshot.isSymbolicLink()) return { status: 'unsafe' };
+  }
+  return { status: 'safe', snapshot };
+}
+
+async function validatePhysicalCandidate({ lexicalRoot, physicalRoot, candidate, expected }) {
+  const lexical = await inspectDescendant(lexicalRoot, candidate);
+  if (lexical.status !== 'safe') {
+    return expected && lexical.status === 'missing' ? { status: 'unsafe' } : lexical;
+  }
+
+  let physical;
+  try {
+    physical = await realpath(candidate);
+  } catch (error) {
+    if (error.code === 'ENOENT' || isUnsafePathError(error)) return { status: 'unsafe' };
+    throw error;
+  }
+  if (!isStrictDescendant(physicalRoot, physical)) return { status: 'unsafe' };
+
+  const physicalInspection = await inspectDescendant(physicalRoot, physical);
+  const lexicalConfirmation = await inspectDescendant(lexicalRoot, candidate);
+  if (physicalInspection.status !== 'safe' || lexicalConfirmation.status !== 'safe') {
+    return { status: 'unsafe' };
+  }
+
+  let physicalConfirmation;
+  try {
+    physicalConfirmation = await realpath(candidate);
+  } catch (error) {
+    if (error.code === 'ENOENT' || isUnsafePathError(error)) return { status: 'unsafe' };
+    throw error;
+  }
+  if (physicalConfirmation !== physical
+    || !sameFileSnapshot(lexical.snapshot, physicalInspection.snapshot)
+    || !sameFileSnapshot(lexical.snapshot, lexicalConfirmation.snapshot)) {
+    return { status: 'unsafe' };
+  }
+  if (expected && (expected.physical !== physical || !sameFileSnapshot(expected.snapshot, lexical.snapshot))) {
+    return { status: 'unsafe' };
+  }
+  return { status: 'safe', physical, snapshot: lexical.snapshot };
+}
+
+async function hashValidatedFile(file, expectedSnapshot) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === 'ENOENT' || isUnsafePathError(error)) return { status: 'unsafe' };
+    throw error;
+  }
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!sameFileSnapshot(before, expectedSnapshot)) return { status: 'unsafe' };
+    const content = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    if (!sameFileSnapshot(before, after)) return { status: 'unsafe' };
+    return { status: 'safe', digest: createHash('sha256').update(content).digest('hex') };
+  } finally {
+    await handle.close();
+  }
+}
+
 export async function purgeProject({ targetRoot, recordedChecksums }) {
   const removed = [];
   const preserved = [];
+  const lexicalRoot = path.resolve(targetRoot);
+  let physicalRoot;
+  try {
+    physicalRoot = await realpath(lexicalRoot);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   for (const [relative, expected] of Object.entries(recordedChecksums).sort(([a], [b]) => a.localeCompare(b))) {
-    const file = path.join(targetRoot, relative);
+    const policy = recordedPathPolicy(relative);
+    if (!policy.safe || policy.isWorkItem) {
+      preserved.push(relative);
+      continue;
+    }
+    if (!physicalRoot) continue;
+    const file = path.resolve(lexicalRoot, ...policy.canonical.split('/'));
     try {
-      if (await sha256File(file) === expected) {
-        await rm(file);
-        removed.push(relative);
-      } else preserved.push(relative);
+      const beforeHash = await validatePhysicalCandidate({ lexicalRoot, physicalRoot, candidate: file });
+      if (beforeHash.status === 'missing') continue;
+      if (beforeHash.status !== 'safe') {
+        preserved.push(relative);
+        continue;
+      }
+      const hash = await hashValidatedFile(beforeHash.physical, beforeHash.snapshot);
+      if (hash.status !== 'safe' || hash.digest !== expected) {
+        preserved.push(relative);
+        continue;
+      }
+      const beforeRemoval = await validatePhysicalCandidate({
+        lexicalRoot, physicalRoot, candidate: file, expected: beforeHash,
+      });
+      if (beforeRemoval.status !== 'safe') {
+        preserved.push(relative);
+        continue;
+      }
+      await rm(beforeRemoval.physical);
+      removed.push(relative);
     } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
+      if (error.code === 'ENOENT') preserved.push(relative);
+      else throw error;
     }
   }
   return { removed, preserved };

package/templates/AGENTS.md

@@ -18,19 +18,11 @@ Keep this file specific to the repository. Replace placeholders with commands an
 - Keep external writes, commits, pushes, merges, releases, deployments, and production mutations behind explicit user authorization.
 - Verify changed behavior with the strongest safe repository checks available. Report what ran and what remains unverified.
 
-## Task artifacts
+## Durable task state
 
-Use existing files under `docs/agent/` only when they help the current task:
+Keep simple, one-shot work artifact-free; ask before creating a new durable workspace unless the user explicitly requested durable artifacts or named an existing work item.
 
-- `spec.md`: goal, scope, constraints, acceptance criteria, and unresolved product choices
-- `plan.md`: current execution map, status, dependencies, and verification targets
-- `decision-log.md`: material decisions, evidence, alternatives, and consequences
-- `findings.md`: review findings and their lifecycle
-- `handoff.md`: resumable state when work remains or ownership changes
-
-Do not create missing workflow artifacts unless the user requests durable artifacts or runs `npx nono-skills init`. Without them, put the same material information in the final response.
-
-Append a decision only when it changes a contract, resolves meaningful ambiguity, accepts risk or a costly tradeoff, changes the plan materially, or records an assumption future work must preserve. Supersede accepted entries instead of rewriting history. Do not log routine edits or shell commands.
+Approved work lives under `docs/agent/work/<work-id>/`. Keep each feature isolated, let its `spec.md` define scope and status, record only material decisions, and never select another work item by recency alone. Repository-specific instructions override the default location.
 
 ## Definition of done
 

package/templates/docs/agent/decision-log.md

@@ -1,15 +0,0 @@
-# Decision Log
-
-Append material decisions. Never silently rewrite an accepted decision; supersede it with a new entry.
-
-## YYYY-MM-DD HH:MM — Decision title
-
-- Status: proposed | accepted | superseded | rejected
-- Context:
-- Decision:
-- Alternatives:
-- Evidence and rationale:
-- Consequences:
-- Follow-up:
-- Related:
-

package/templates/docs/agent/findings.md

@@ -1,13 +0,0 @@
-# Findings
-
-## Finding ID — Short title
-
-- Severity: critical | high | medium | low
-- State: open | accepted | fixed | verified | wont-fix | not-reproducible
-- Evidence:
-- Impact:
-- Reproduction or reasoning:
-- Remediation direction:
-- Verification:
-- Owner or follow-up:
-

package/templates/docs/agent/handoff.md

@@ -1,20 +0,0 @@
-# Agent Handoff
-
-## Objective
-
-## Current status
-
-## Completed
-
-## In progress
-
-## Remaining
-
-## Decisions and assumptions
-
-## Blockers and human input
-
-## Verification performed
-
-## Resume from here
-

package/templates/docs/agent/plan.md

@@ -1,14 +0,0 @@
-# Working Plan
-
-Status values: `pending`, `in-progress`, `blocked`, `done`.
-
-| Status | Work item | Verification | Notes |
-|---|---|---|---|
-| pending |  |  |  |
-
-## Risks and dependencies
-
-## Human decisions needed
-
-## Latest checkpoint
-

package/templates/docs/agent/spec.md

@@ -1,20 +0,0 @@
-# Working Spec
-
-## Goal
-
-## Users and outcome
-
-## In scope
-
-## Out of scope
-
-## Constraints
-
-## Acceptance criteria
-
-- [ ]
-
-## Open questions
-
-## Evidence and references
-