npm - @warnyin/sdlc - Versions diffs - 0.3.0 → 0.4.0 - Mend

@warnyin/sdlc 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md +118 -95
package/README.md +85 -84
package/bin/cli.mjs +13 -2
package/package.json +1 -1
package/payload/adapters/claude/commands/sdlc/feedback.md +5 -0
package/payload/playbook/README.md +31 -30
package/payload/playbook/feedback.md +69 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,95 +1,118 @@
-# Changelog
-## 0.3.0 (2026-08-21)
-- **`/sdlc:auto` resumes an open change** instead of always starting at `new`. It
-  resolves its entry stage from `sdlc status` first: an argument naming an active
-  change maps that change's status to the entry stage and the pipeline starts
-  there, keeping the tier, Delta and Assumptions it was already triaged with. Only
-  an argument matching no active change starts at `new`. The entry stage is stated
-  in the plan line, so a resume is never silent. The status → stage table stays in
-  `next.md` alone rather than being copied into a second place that can drift.
-- **Fix (ownership)**: `installFile` dropped a file's manifest entry whenever it
-  kept the file. The next run then saw a path it had never installed, which
-  permanently disarmed `update`'s refresh branch — the file froze at its old
-  payload version and every later run relabelled it user-modified. That affects
-  anyone who re-runs `init` to upgrade before `update`. A kept file now carries
-  its recorded hash forward; prune is unaffected (its guard compares the file on
-  disk against that same hash) and in fact strictly safer, since a kept file is no
-  longer even a prune candidate.
-- A file whose content still matches its recorded hash is reported as
-  `kept (ours, older version — run update to refresh)` instead of
-  `kept (user-modified)`, which sent people hunting for an edit they never made.
-## 0.2.2 (2026-08-20)
-- `init` (and `update`) now drop a `.gitkeep` in `sdlc/changes/archive/`, so the
-  directory survives a commit and is still there after a clone. 0.2.1 made
-  `archive` recover from the missing directory; this stops it going missing.
-  The marker is not payload-owned — prune never reclaims it and the installer
-  never warns about it.
-## 0.2.1 (2026-08-20)
-- **Fix**: `archive` failed with `ENOENT` on the first change a repo ever ships.
-  `init` scaffolds `sdlc/changes/archive/`, but git does not track empty
-  directories, so the folder is absent for everyone who clones before that first
-  ship. The rename is now preceded by a `mkdir -p` of the archive root.
-  The failure landed mid-phase-2, after the delta had been merged into the living
-  specs, evals promoted, `status: shipped` stamped and the ship event journalled —
-  a repo left half-shipped while the CLI reported total failure. The directory is
-  now prepared next to the other destination checks, before phase 1 computes a
-  single merge, so an unusable archive path aborts with the specs untouched.
-## 0.2.0 (2026-08-20)
-`init` is now an installer you can actually see working — still zero dependencies.
-- **Interactive tool picker**: a searchable checkbox list replaces the
-  comma-separated typing prompt. Arrows move, `space` toggles, typing filters,
-  `ctrl+a` selects everything on screen, `enter` confirms, `ctrl+c` cancels
-  without installing anything.
-- **Tool detection**: tools the project already uses (`.claude/`, `.cursor/`,
-  `AGENTS.md`, …) come pre-selected; an empty project still defaults to claude.
-- **Post-install summary**: artifact counts, the adapter path per tool, a
-  written/unchanged/refreshed/kept tally, and Getting-started hints that differ
-  per tool (slash commands for Claude Code, prose for the rest).
-- **Colour** gated on `NO_COLOR` > `FORCE_COLOR` > TTY, with an ASCII glyph
-  fallback for legacy Windows consoles.
-- `--tool` accepts `all` and `none`; `--tools` is an alias. An empty `--tool`,
-  an unknown tool, or `all` mixed with a named tool now fails loudly.
-- **Fix**: `update` read an explicit `tools: []` (what `init --tool none` writes)
-  as "unset" and reinstalled claude. A missing key and a declared-empty one are
-  now distinguished.
-## 0.1.2 (2026-08-20)
-- Fix: `readStdinJson()` grew a 1s grace timeout — journal and hook utilities no
-  longer hang when stdin is open but idle.
-- Fix: hooks release stdin (pause + unref) so an open-idle stdin cannot keep a
-  hook process alive.
-## 0.1.1 (2026-08-20)
-- Fix: the entrypoint guard must realpath `process.argv[1]` — npx invokes through
-  a `node_modules/.bin` symlink, which made the CLI a silent no-op.
-- Fix (CI): `node --test` bare discovery; a quoted glob is not expanded on Node 20.
-## 0.1.0 (2026-08-20)
-Initial release — the full Day-1 SDLC loop:
-- CLI: `init` (multi-tool: claude/cursor/windsurf/copilot/cline/gemini/agents-md),
-  `update` (ownership-aware refresh + guarded prune), `validate`, `status`,
-  `observe`, `archive`.
-- Artifact model: constitution (≤30) + steering with inclusion modes + harness
-  (routing/triage/autonomy policy) + living specs + delta-based changes
-  (vibe/standard/deep caps 40/100/150) + contracts (tests ≤60, evals ≤40).
-- Managed Claude Code hooks: static-context injector, spec write-lock with TTL
-  gates, artifact validator + steering pointers, session token/cost journaling,
-  compact-event tracking.
-- 13 stage playbooks + 13 `/sdlc:*` commands + 3 background skills + 8 agents
-  with model routing (cheap/balanced/deepest).
-- Observability: per-change tokens/cost, first-pass rate, lead time, dead
-  steering and residency flags; post-ship learner loop (distill, never bloat).
+# Changelog
+## 0.4.0 (2026-08-25)
+- **New stage command `/sdlc:feedback`** — reports a bug, a rough edge, or a missing
+  feature in the framework itself to `warnyin/warnyin-sdlc`, from inside the session
+  where you hit it. It collects the context a maintainer triages by (framework and
+  Node version, OS, tool adapter, active change id and status), redacts it, shows you
+  the complete draft, and files it only after you approve. Submission goes through
+  `gh`; when `gh` is missing, logged out, or authenticated only against an enterprise
+  host, you get a prefilled issue URL instead — a normal path, not an error.
+  Nothing is attached automatically: no logs, no journal, no diff. Redaction is a
+  rule list rather than a guarantee, and the playbook says so — your eyes on the
+  draft are the control.
+- Human-written text never reaches a shell as an argument: the body travels over
+  stdin, while the title and the duplicate-search keywords are written by the agent
+  under a length and character allow-list instead of being pasted raw.
+- **New: `warnyin-sdlc version`** (also `--version` / `-v`). Nothing in an installed
+  project was readable as a version — an npx install leaves no package behind — so
+  every bug report would have carried `unknown` in the field that decides whether a
+  report can be acted on at all.
+- The repository now ships `.github/ISSUE_TEMPLATE/` bug and feature forms asking for
+  the same fields the command collects, so web-filed and command-filed reports read
+  alike.
+## 0.3.0 (2026-08-21)
+- **`/sdlc:auto` resumes an open change** instead of always starting at `new`. It
+  resolves its entry stage from `sdlc status` first: an argument naming an active
+  change maps that change's status to the entry stage and the pipeline starts
+  there, keeping the tier, Delta and Assumptions it was already triaged with. Only
+  an argument matching no active change starts at `new`. The entry stage is stated
+  in the plan line, so a resume is never silent. The status → stage table stays in
+  `next.md` alone rather than being copied into a second place that can drift.
+- **Fix (ownership)**: `installFile` dropped a file's manifest entry whenever it
+  kept the file. The next run then saw a path it had never installed, which
+  permanently disarmed `update`'s refresh branch — the file froze at its old
+  payload version and every later run relabelled it user-modified. That affects
+  anyone who re-runs `init` to upgrade before `update`. A kept file now carries
+  its recorded hash forward; prune is unaffected (its guard compares the file on
+  disk against that same hash) and in fact strictly safer, since a kept file is no
+  longer even a prune candidate.
+- A file whose content still matches its recorded hash is reported as
+  `kept (ours, older version — run update to refresh)` instead of
+  `kept (user-modified)`, which sent people hunting for an edit they never made.
+## 0.2.2 (2026-08-20)
+- `init` (and `update`) now drop a `.gitkeep` in `sdlc/changes/archive/`, so the
+  directory survives a commit and is still there after a clone. 0.2.1 made
+  `archive` recover from the missing directory; this stops it going missing.
+  The marker is not payload-owned — prune never reclaims it and the installer
+  never warns about it.
+## 0.2.1 (2026-08-20)
+- **Fix**: `archive` failed with `ENOENT` on the first change a repo ever ships.
+  `init` scaffolds `sdlc/changes/archive/`, but git does not track empty
+  directories, so the folder is absent for everyone who clones before that first
+  ship. The rename is now preceded by a `mkdir -p` of the archive root.
+  The failure landed mid-phase-2, after the delta had been merged into the living
+  specs, evals promoted, `status: shipped` stamped and the ship event journalled —
+  a repo left half-shipped while the CLI reported total failure. The directory is
+  now prepared next to the other destination checks, before phase 1 computes a
+  single merge, so an unusable archive path aborts with the specs untouched.
+## 0.2.0 (2026-08-20)
+`init` is now an installer you can actually see working — still zero dependencies.
+- **Interactive tool picker**: a searchable checkbox list replaces the
+  comma-separated typing prompt. Arrows move, `space` toggles, typing filters,
+  `ctrl+a` selects everything on screen, `enter` confirms, `ctrl+c` cancels
+  without installing anything.
+- **Tool detection**: tools the project already uses (`.claude/`, `.cursor/`,
+  `AGENTS.md`, …) come pre-selected; an empty project still defaults to claude.
+- **Post-install summary**: artifact counts, the adapter path per tool, a
+  written/unchanged/refreshed/kept tally, and Getting-started hints that differ
+  per tool (slash commands for Claude Code, prose for the rest).
+- **Colour** gated on `NO_COLOR` > `FORCE_COLOR` > TTY, with an ASCII glyph
+  fallback for legacy Windows consoles.
+- `--tool` accepts `all` and `none`; `--tools` is an alias. An empty `--tool`,
+  an unknown tool, or `all` mixed with a named tool now fails loudly.
+- **Fix**: `update` read an explicit `tools: []` (what `init --tool none` writes)
+  as "unset" and reinstalled claude. A missing key and a declared-empty one are
+  now distinguished.
+## 0.1.2 (2026-08-20)
+- Fix: `readStdinJson()` grew a 1s grace timeout — journal and hook utilities no
+  longer hang when stdin is open but idle.
+- Fix: hooks release stdin (pause + unref) so an open-idle stdin cannot keep a
+  hook process alive.
+## 0.1.1 (2026-08-20)
+- Fix: the entrypoint guard must realpath `process.argv[1]` — npx invokes through
+  a `node_modules/.bin` symlink, which made the CLI a silent no-op.
+- Fix (CI): `node --test` bare discovery; a quoted glob is not expanded on Node 20.
+## 0.1.0 (2026-08-20)
+Initial release — the full Day-1 SDLC loop:
+- CLI: `init` (multi-tool: claude/cursor/windsurf/copilot/cline/gemini/agents-md),
+  `update` (ownership-aware refresh + guarded prune), `validate`, `status`,
+  `observe`, `archive`.
+- Artifact model: constitution (≤30) + steering with inclusion modes + harness
+  (routing/triage/autonomy policy) + living specs + delta-based changes
+  (vibe/standard/deep caps 40/100/150) + contracts (tests ≤60, evals ≤40).
+- Managed Claude Code hooks: static-context injector, spec write-lock with TTL
+  gates, artifact validator + steering pointers, session token/cost journaling,
+  compact-event tracking.
+- 13 stage playbooks + 13 `/sdlc:*` commands + 3 background skills + 8 agents
+  with model routing (cheap/balanced/deepest).
+- Observability: per-change tokens/cost, first-pass rate, lead time, dead
+  steering and residency flags; post-ship learner loop (distill, never bloat).

package/README.md CHANGED Viewed

@@ -1,84 +1,85 @@
-# @warnyin/sdlc
-**Spec-driven, AI-driven SDLC for coding agents — token-lean by construction.**
-Operationalizes the *"New SDLC with Vibe Coding"* (Day-1) work process: the human configures
-the harness once; the AI drives changes end-to-end through contract-first gates; deterministic
-hooks and a validator enforce the rules; a journal prices every change in real tokens.
-Inspired by OpenSpec (delta specs, archive lifecycle), spec-kit (artifact grammar), and
-Kiro (steering + enforced hooks) — tuned for minimum context residency.
-## Install
-```bash
-cd your-project
-npx @warnyin/sdlc init          # interactive picker; tools already in the project are pre-selected
-```
-The picker is a checkbox list — arrows move, `space` toggles, typing filters, `ctrl+a` selects
-everything on screen, `enter` confirms. Skip it in CI or scripts:
-```bash
-npx @warnyin/sdlc init --tool claude,cursor   # explicit list
-npx @warnyin/sdlc init --tool all             # every supported tool
-npx @warnyin/sdlc init --tool none            # sdlc/ framework only, no agent adapters
-```
-Then in your coding agent:
-```
-/sdlc:init                      # interview → constitution + harness (the one human gate)
-/sdlc:auto Add rate limiting    # AI runs new → contract → build → verify → ship
-/sdlc:auto add-rate-limiting    # already opened it with /sdlc:new? auto resumes from there
-```
-## How it works
-```
-sdlc/
-├── context/constitution.md   ≤30 lines — the ONLY always-loaded prose (hook-injected)
-├── context/steering/*.md     scoped knowledge · inclusion: always|paths|manual|agent
-├── harness.md                tools, model routing, tier triage, autonomy policy
-├── specs/<capability>/       living specs — WHEN/THEN SHALL, merged mechanically at ship
-├── changes/<id>/             one change: change.md (Why+Delta+Tasks) + contract/ + journal
-└── changes/archive/          shipped changes + digests (the async human touchpoint)
-```
-- **Contract-first**: tests + evals are written *before* code and gate everything after.
-- **AI-driven, exception-only humans**: the autonomy policy in `harness.md` decides what
-  auto-ships and what escalates (hard-floor: security/payments/data-loss/irreversible).
-- **Managed hooks** (Claude Code): SessionStart injects ≤60 lines of static context;
-  PreToolUse write-locks living specs; PostToolUse validates caps and points at steering;
-  Stop journals real token usage. Other tools get the same rules as prose + the validator.
-- **Self-improving, leaner over time**: a post-ship learner proposes rules with evidence;
-  the always-loaded budget is fixed, so learning must distill, not accumulate.
-- **Measured**: `npx @warnyin/sdlc observe` — tokens/cost per change, first-pass rate,
-  lead time, dead steering, context-overflow flags.
-## CLI
-```
-warnyin-sdlc init [--tool all|none|a,b]   scaffold + adapters + hooks (picker when omitted)
-warnyin-sdlc update [--force]       refresh payload, guarded prune of stale files
-warnyin-sdlc validate [id] [--strict]
-warnyin-sdlc status | observe [--json]
-warnyin-sdlc archive <id>           merge deltas into living specs + archive
-```
-## Commands (in your agent)
-`/sdlc:init` · `/sdlc:auto` · `/sdlc:new` · `/sdlc:design` · `/sdlc:contract` · `/sdlc:build`
-· `/sdlc:verify` · `/sdlc:review` · `/sdlc:ship` · `/sdlc:observe` · `/sdlc:converge`
-· `/sdlc:steer` · `/sdlc:next`
-Playbooks live in `sdlc/.playbook/` — behavior is defined once there; commands are thin pointers.
-## Development
-Zero dependencies, Node ≥ 20. `npm test` runs the black-box suite (temp dirs, real CLI spawns).
-This repo self-hosts: its own development flows through `sdlc/changes/`. After cloning, run
-`npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
-`sdlc/.hooks/`, `.claude/`).
-MIT
+# @warnyin/sdlc
+**Spec-driven, AI-driven SDLC for coding agents — token-lean by construction.**
+Operationalizes the *"New SDLC with Vibe Coding"* (Day-1) work process: the human configures
+the harness once; the AI drives changes end-to-end through contract-first gates; deterministic
+hooks and a validator enforce the rules; a journal prices every change in real tokens.
+Inspired by OpenSpec (delta specs, archive lifecycle), spec-kit (artifact grammar), and
+Kiro (steering + enforced hooks) — tuned for minimum context residency.
+## Install
+```bash
+cd your-project
+npx @warnyin/sdlc init          # interactive picker; tools already in the project are pre-selected
+```
+The picker is a checkbox list — arrows move, `space` toggles, typing filters, `ctrl+a` selects
+everything on screen, `enter` confirms. Skip it in CI or scripts:
+```bash
+npx @warnyin/sdlc init --tool claude,cursor   # explicit list
+npx @warnyin/sdlc init --tool all             # every supported tool
+npx @warnyin/sdlc init --tool none            # sdlc/ framework only, no agent adapters
+```
+Then in your coding agent:
+```
+/sdlc:init                      # interview → constitution + harness (the one human gate)
+/sdlc:auto Add rate limiting    # AI runs new → contract → build → verify → ship
+/sdlc:auto add-rate-limiting    # already opened it with /sdlc:new? auto resumes from there
+```
+## How it works
+```
+sdlc/
+├── context/constitution.md   ≤30 lines — the ONLY always-loaded prose (hook-injected)
+├── context/steering/*.md     scoped knowledge · inclusion: always|paths|manual|agent
+├── harness.md                tools, model routing, tier triage, autonomy policy
+├── specs/<capability>/       living specs — WHEN/THEN SHALL, merged mechanically at ship
+├── changes/<id>/             one change: change.md (Why+Delta+Tasks) + contract/ + journal
+└── changes/archive/          shipped changes + digests (the async human touchpoint)
+```
+- **Contract-first**: tests + evals are written *before* code and gate everything after.
+- **AI-driven, exception-only humans**: the autonomy policy in `harness.md` decides what
+  auto-ships and what escalates (hard-floor: security/payments/data-loss/irreversible).
+- **Managed hooks** (Claude Code): SessionStart injects ≤60 lines of static context;
+  PreToolUse write-locks living specs; PostToolUse validates caps and points at steering;
+  Stop journals real token usage. Other tools get the same rules as prose + the validator.
+- **Self-improving, leaner over time**: a post-ship learner proposes rules with evidence;
+  the always-loaded budget is fixed, so learning must distill, not accumulate.
+- **Measured**: `npx @warnyin/sdlc observe` — tokens/cost per change, first-pass rate,
+  lead time, dead steering, context-overflow flags.
+## CLI
+```
+warnyin-sdlc init [--tool all|none|a,b]   scaffold + adapters + hooks (picker when omitted)
+warnyin-sdlc update [--force]       refresh payload, guarded prune of stale files
+warnyin-sdlc validate [id] [--strict]
+warnyin-sdlc status | observe [--json]
+warnyin-sdlc archive <id>           merge deltas into living specs + archive
+warnyin-sdlc version | --version    print the installed framework version
+```
+## Commands (in your agent)
+`/sdlc:init` · `/sdlc:auto` · `/sdlc:new` · `/sdlc:design` · `/sdlc:contract` · `/sdlc:build`
+· `/sdlc:verify` · `/sdlc:review` · `/sdlc:ship` · `/sdlc:observe` · `/sdlc:converge`
+· `/sdlc:steer` · `/sdlc:next` · `/sdlc:feedback`
+Playbooks live in `sdlc/.playbook/` — behavior is defined once there; commands are thin pointers.
+## Development
+Zero dependencies, Node ≥ 20. `npm test` runs the black-box suite (temp dirs, real CLI spawns).
+This repo self-hosts: its own development flows through `sdlc/changes/`. After cloning, run
+`npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
+`sdlc/.hooks/`, `.claude/`).
+MIT

package/bin/cli.mjs CHANGED Viewed

@@ -45,7 +45,7 @@ export function sha256(content) {
 }
 export function parseArgs(argv) {
-  const args = { _: [], tool: null, toolProvided: false, strict: false, force: false, json: false, help: false };
+  const args = { _: [], tool: null, toolProvided: false, strict: false, force: false, json: false, help: false, version: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--tool' || a === '--tools') {
@@ -56,6 +56,7 @@ export function parseArgs(argv) {
     else if (a === '--force') args.force = true;
     else if (a === '--json') args.json = true;
     else if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--version' || a === '-v') args.version = true;
     else if (a.startsWith('--')) console.warn(`unknown flag ${a} (ignored)`);
     else args._.push(a);
   }
@@ -526,6 +527,12 @@ function runValidate(projectRoot, args) {
   process.exitCode = res.status ?? 0;
 }
+// Read from our own package.json: an npx install leaves nothing readable in the
+// target project, and a report whose version is `unknown` cannot be triaged.
+function pkgVersion() {
+  return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+}
 const HELP = `@warnyin/sdlc — spec-driven AI-SDLC framework
 usage: warnyin-sdlc <command> [options]
@@ -536,14 +543,18 @@ usage: warnyin-sdlc <command> [options]
   status [--json]                   list active changes and their stage
   observe [--json]                  tokens/cost per change, residency, steering hits, drift flags
   archive <id>                      merge delta specs into living specs and archive the change
+  version | --version | -v          print the installed framework version
   help                              this text
 `;
 export async function main(argv = process.argv.slice(2), projectRoot = process.cwd()) {
   const args = parseArgs(argv);
   const cmd = args._[0];
-  if (args.help || !cmd || cmd === 'help') { console.log(HELP); return; }
   try {
+    // before the help branch: `--version` carries no command, and `!cmd` would
+    // otherwise print help instead of the version.
+    if (args.version || cmd === 'version') { console.log(pkgVersion()); return; }
+    if (args.help || !cmd || cmd === 'help') { console.log(HELP); return; }
     if (cmd === 'init') await cmdInit(projectRoot, args);
     else if (cmd === 'update') cmdUpdate(projectRoot, args);
     else if (cmd === 'validate') runValidate(projectRoot, args);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@warnyin/sdlc",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Spec-driven, AI-driven SDLC framework — token-lean specs, contract-first changes, autonomous pipeline with managed hooks. Operationalizes the Day-1 'New SDLC with Vibe Coding' work process.",
   "type": "module",
   "bin": {

package/payload/adapters/claude/commands/sdlc/feedback.md ADDED Viewed

@@ -0,0 +1,5 @@
+---
+description: Report a bug or request a feature in the framework itself — drafts a GitHub issue upstream, redacted, and files it only after you approve
+argument-hint: "[bug|idea] <one line>"
+---
+Read `sdlc/.playbook/feedback.md` and execute it now. Arguments: $ARGUMENTS

package/payload/playbook/README.md CHANGED Viewed

@@ -1,30 +1,31 @@
-# @warnyin/sdlc playbook
-One change = one folder in `sdlc/changes/<id>/` moving through:
-```
-new → [design] → contract → build → verify → [review] → ship
-```
-| Command | Day-1 phase | Reads | Writes | Gate (automatic unless noted) |
-|---|---|---|---|---|
-| /sdlc:init | Configure harness | interview | constitution, harness.md | human approves (once) |
-| /sdlc:auto | whole loop | status (resumes an open change) | everything below | escalation only |
-| /sdlc:new | Requirements | specs Purpose headers | change.md | validator: delta + assumptions |
-| /sdlc:design | Architecture | change + touched specs | change.md § Design | escalate irreversible only |
-| /sdlc:contract | Contract-first | change.md | contract/*, failing tests | adversarial panel + validator |
-| /sdlc:build | Run harness | change + contract + steering | code, task boxes | tasks done; specs locked by hook |
-| /sdlc:verify | Feedback loop | contract | journal events | tests green AND evals ≥ bar |
-| /sdlc:review | Review | diff + change | findings in change.md | blockers = 0 |
-| /sdlc:ship | Ship | change | specs merge, archive, digest | validate --strict; policy may require human |
-| /sdlc:observe | Observe | journals | report (chat) | — |
-| /sdlc:converge | Maintenance | specs + code | proposed change | — |
-| /sdlc:steer | Configure | context/ | steering, constitution | always-budget ≤ 60 |
-| /sdlc:next | — | status | chat only | — |
-Statuses: `new → contracted → building → verified → shipped`. Tiers: `vibe | standard | deep`
-(triage table + Autonomy policy live in `sdlc/harness.md`).
-Doctrine: `principles.md` (factory model, anti-garbage), `context.md` (static/dynamic),
-`routing.md` (model tiers). Non-Claude harnesses: `rules-card.md` is embedded in your
-tool's rules file; `npx @warnyin/sdlc validate` is the enforcement floor.
+# @warnyin/sdlc playbook
+One change = one folder in `sdlc/changes/<id>/` moving through:
+```
+new → [design] → contract → build → verify → [review] → ship
+```
+| Command | Day-1 phase | Reads | Writes | Gate (automatic unless noted) |
+|---|---|---|---|---|
+| /sdlc:init | Configure harness | interview | constitution, harness.md | human approves (once) |
+| /sdlc:auto | whole loop | status (resumes an open change) | everything below | escalation only |
+| /sdlc:new | Requirements | specs Purpose headers | change.md | validator: delta + assumptions |
+| /sdlc:design | Architecture | change + touched specs | change.md § Design | escalate irreversible only |
+| /sdlc:contract | Contract-first | change.md | contract/*, failing tests | adversarial panel + validator |
+| /sdlc:build | Run harness | change + contract + steering | code, task boxes | tasks done; specs locked by hook |
+| /sdlc:verify | Feedback loop | contract | journal events | tests green AND evals ≥ bar |
+| /sdlc:review | Review | diff + change | findings in change.md | blockers = 0 |
+| /sdlc:ship | Ship | change | specs merge, archive, digest | validate --strict; policy may require human |
+| /sdlc:observe | Observe | journals | report (chat) | — |
+| /sdlc:converge | Maintenance | specs + code | proposed change | — |
+| /sdlc:steer | Configure | context/ | steering, constitution | always-budget ≤ 60 |
+| /sdlc:next | — | status | chat only | — |
+| /sdlc:feedback | — | context + your words | an issue upstream | human approves the draft |
+Statuses: `new → contracted → building → verified → shipped`. Tiers: `vibe | standard | deep`
+(triage table + Autonomy policy live in `sdlc/harness.md`).
+Doctrine: `principles.md` (factory model, anti-garbage), `context.md` (static/dynamic),
+`routing.md` (model tiers). Non-Claude harnesses: `rules-card.md` is embedded in your
+tool's rules file; `npx @warnyin/sdlc validate` is the enforcement floor.

package/payload/playbook/feedback.md ADDED Viewed

@@ -0,0 +1,69 @@
+# /sdlc:feedback [bug|idea] <one line> — file an issue upstream
+Reports a bug, a rough edge, or a missing feature in the **framework itself** to
+`warnyin/warnyin-sdlc`. Bugs in the project you are working on belong in that
+project's own tracker — say so and stop.
+1. Collect context in one shot; never interrogate the human for it:
+   - version: `npx @warnyin/sdlc version` · node: `node --version` · OS and arch
+   - tool adapter: `tools:` in `sdlc/config.yaml`
+   - active change id + status: `npx @warnyin/sdlc status --json`
+   Any field you cannot read is `unknown` — continue, and never guess a value.
+2. If the invocation carried no description, ask once, in one message: what you
+   did, what you expected, what happened instead.
+3. Look for it first, when `gh` is available:
+   `gh issue list --repo warnyin/warnyin-sdlc --search "<keywords>" --state all --limit 5`.
+   Choose `<keywords>` yourself — two to four plain words, letters/digits/hyphen
+   only — never the reporter's raw sentence: it reaches the shell as an argument
+   exactly like the title does. If an existing thread matches, show it and ask
+   whether to comment there rather than open a duplicate.
+4. Redact before the draft is shown to anyone or sent anywhere:
+   - absolute paths → project-relative paths (a home directory or host name in a
+     path identifies the reporter's machine and employer)
+   - token-, key-, password- and connection-string-shaped values → `<redacted>`,
+     and tell the human which values you removed
+   - never copy the contents of `sdlc/context/constitution.md`, steering files,
+     `.env` files, credential files, journals, or diffs into the report
+   - this is a rule list, not a guarantee: the human reading the draft is the
+     real control, so never claim the report has been fully scrubbed
+5. Show the full draft — destination repo, title, labels, complete body — and ask
+   for approval. No network call happens before that approval. On anything other
+   than approval: revise the draft and ask again.
+6. Submit, once approved:
+   - `gh auth status` must report an authenticated **github.com** account; an
+     enterprise-only login goes to step 7 instead of publishing to the wrong host
+   - `gh issue create --repo warnyin/warnyin-sdlc --title "<title>"
+     --label <bug|enhancement> --body-file -`, body on stdin
+   - never pass the body as an inline `--body` argument: report text carries
+     backticks, quotes and newlines — inline it breaks on PowerShell and is a
+     shell-injection path straight from human-written text
+   - the title is human text on a command line too: write it yourself as a plain
+     summary (≤80 chars, no newline, no `` ` ``, `$`, `"`, `\`, `|`, `;`, `&`),
+     never paste the reporter's words in raw. If a needed character is not
+     allowed, reword the title — do not escape your way around it
+   - report the resulting issue URL back
+7. Fallback when `gh` is absent, logged out, or not on github.com — a normal
+   path, not an error: hand over a prefilled link
+   `https://github.com/warnyin/warnyin-sdlc/issues/new?labels=<label>&title=<t>&body=<b>`
+   with `<t>` and `<b>` URL-encoded. If the encoded link exceeds ~6000 characters,
+   truncate the body it carries and tell the human to paste the rest from the
+   draft shown above.
+Body shape (keep it this short — a maintainer triages it in one screen):
+```
+### What happened
+<one paragraph, redacted>
+### Expected
+<one line>
+### Steps
+1. <command or stage>
+### Environment
+sdlc <version> · node <version> · <os> · adapter <tool> · change <id> [<status>]
+```
+Labels: `bug` for something broken, `enhancement` for an idea or a request.
+Nothing else is attached — no logs, no journal, no diff.