Repository navigation
release: v2.0.0 - #24
Merged
Merged
Conversation
Replace directory-per-cycle design docs (docs/design/<NNNN-slug>/<slug>.md) with flat files (docs/design/<LEGEND>_<slug>.md). Cycle names are now legend-prefixed slugs (e.g. PROCESS_doctor-command) instead of numbered (0039-doctor-command), removing sequential numbering that doesn't scale for concurrent users. - Remove `number` field from CycleSchema - Design docs are flat files directly in docs/design/ - Retros keep directory layout for witness subdirs - Release-scoped design docs also flatten - Doctor detects legacy nested design doc dirs - Doctor repair flattens legacy dirs and updates frontmatter - Legacy NNNN-slug layout remains discoverable for backward compat - Delete extractReleasedCycleNumbers (number-based CHANGELOG detection) - Update process.md branch naming and path conventions BREAKING CHANGE: Cycle names no longer use sequential numeric prefixes. The `number` field has been removed from the Cycle type. Design docs are now flat files instead of directory-per-cycle.
…c-coupling - Flatten design doc from legacy nested dir to docs/design/PROCESS_*.md - Fill in hill, playback questions, and contract sections - Add 5 new tests matching playback questions (drift clean) - Close cycle with hill-met outcome and retro summary
Add `rm -rf dist` before `tsc` in the build script so every build starts from repo truth. Stale artifacts from renamed or deleted source modules can no longer persist in the published dist/ tree. Closes cycle PROCESS_dist-output-pruning.
…untime Audit all MCP tool handlers for schema-vs-runtime validation gaps. Two tools used type assertions instead of runtime validation: - method_pull: `args.item as string` → `validateString(args.item, 'item')` - method_capture_witness: `args.cycle as string` → `validateOptionalString(args.cycle, 'cycle')` Closes cycle PROCESS_mcp-runtime-input-validation-audit.
updateTypedFrontmatter now rejects writes that would change a field's type shape (e.g. array to string, boolean to string). Error messages name the field, expected type, and attempted type. readTypedFrontmatter already preserves YAML-native types (arrays, booleans, numbers). Legacy string-only callers are unaffected. Closes cycle PROCESS_typed-frontmatter-access.
…D_LANES Add SCAFFOLD_LANES as single source of truth for which lane directories init creates. Document the contract: individual lane dirs may be absent when empty without making the workspace unhealthy. Closes cycle PROCESS_backlog-lane-materialization-contract.
Extract cycle path resolution, discovery, and shared utilities into focused modules: - src/cycle-ops.ts: CYCLE_NAME_PATTERN, readCycleFromDoc, resolveCyclePacketPaths, readCycleRelease, path helpers - src/workspace-utils.ts: fileStem, slugify, normalizeRepoPath, collectMarkdownFiles, assertWorkspacePath, normalizeOptionalString Reduces src/index.ts from ~2207 to ~1975 lines. Workspace class remains the public facade with unchanged API. Closes cycle PROCESS_workspace-operation-split.
…ll sync
Replace the simple `localBody.includes('## GitHub Comments')` duplicate
check with stable GitHub comment ID tracking. Comment IDs are stored in
`github_synced_comment_ids` frontmatter and used to detect which
comments are new vs already synced. Repeated pulls only append genuinely
new comments.
Closes cycle PROCESS_github-comment-sync-identity.
7 items already implemented prior to v2.0.0: - backlog-authoring-command (method backlog add) - backlog-move-command (method backlog move) - doctor-repair-command (method repair) - retire-command (method retire) - signpost-helper-commands (method signpost status/init) - structured-repair-hints (DoctorRepairHintSchema) - task-dependency-dag (method backlog deps) 1 item replaced: - feedback-command → replaced by method inbox with --source, --captured-at, and --body-file flags
Replace the brittle exact-string-only drift matcher with three tiers: 1. Exact normalized match (lowercase, collapse whitespace) 2. Semantic normalization (also strips backticks, question-word prefixes like Does/Is/Can, trailing punctuation) 3. Token similarity with stemming (Jaccard on stemmed tokens, >= 0.85 = auto-match, 0.65-0.85 = near-miss hint) This fixes the common brittleness where "Does `X`?" in a playback question failed to match "X." in a test description. No LLM or network dependency — purely deterministic. Closes cycle PROCESS_semantic-drift-detector.
Near-miss hints now display the Jaccard similarity percentage: `Near miss (71%): "..."` so operators can judge relevance at a glance. Closes cycle PROCESS_drift-score-visibility.
Add `drift_thresholds.semantic_match` (default 0.85) and `drift_thresholds.near_miss` (default 0.65) to ConfigSchema. The drift detector reads these from workspace config so repos can tune matching tolerance without code changes. Closes cycle PROCESS_drift-threshold-config.
New `method spike <goal>` command and `method_spike` MCP tool for capturing behavior spikes as first-class backlog items. Creates SPIKE-prefixed items with structured scaffolding (goal, stack constraints, expected outcome) matching the behavior-spike convention in process.md. Closes cycle PROCESS_spike-command.
- Install Biome with recommended rules, add `npm run lint` script - CI now runs: audit, lint, build, test, pack --dry-run - Pre-commit hook enforces lint; pre-push hook enforces tests - Zero lint violations on the current codebase - Auto-fixed formatting across 31 files via Biome Closes cycle PROCESS_ci-hardening.
…r priority pullItem now validates backlog readiness before pulling. Missing acceptance_criteria, priority, or legend emit warnings (advisory, not blocking). Warnings are returned in the Cycle result and surfaced by both CLI (stderr) and MCP (structured content). Also defines the backlog readiness contract in a JSDoc comment on validateBacklogReadiness. Closes cycle PROCESS_validate-command.
Human playback questions must be verified by a human operator, and Agent playback questions must be verified by an agent. Neither seat can unilaterally sign off on the other's hill.
- Run `method doctor --repair` to flatten all 38 legacy NNNN-* design doc directories to flat LEGEND_slug.md files - Rename corresponding retro directories to match new cycle names - Add release invariant: `method doctor` must pass with zero issues before any release (process.md rule + release.md sequence step) - Fix VISION.md witness_ref and test paths broken by the rename
Doctor now warns when required directories are missing .gitkeep files (they'd vanish on clone). initWorkspace creates .gitkeep in all scaffolded directories. Repair supports create-gitkeep kind. Also adds release gate: method doctor must pass with zero issues before any release. This repo must practice what it preaches.
…ess scaffold The witness scaffold now includes a Human Verification section with clone, setup, build, test, and drift-check commands so reviewers can reproduce the verification independently in a sandbox. Also documents this requirement in process.md step 5.
… gates Release gates now require: - All cycle witnesses re-executed and green at the release commit - Human operator attestation for every human playback question - Agent cannot unilaterally confirm human hills Added Phase 3 (Witness and human verification) to the release runbook between versioning and technical validation. Updated process.md rules and release.md sequence to match.
…l retro method close now: - Requires human witness verification before writing the retro (interactive prompt or --witness-verified flag) - Prompts for retro content (summary, drift, debt, ideas) so retro docs ship with real content instead of TBD skeletons - Supports --summary flag to skip interactive prompts for tests/MCP closeCycle() accepts optional retroContent parameter. renderRetroDoc uses provided content instead of TBD placeholders. Closes cycle PROCESS_retro-conversational-closeout.
- Move docs/method/process.md → docs/PROCESS.md (signpost) - Merge docs/method/release.md + docs/method/release-runbook.md → docs/RELEASE.md (signpost) - Remove docs/method/release-runbook.md (content merged into RELEASE.md) - Update scaffold, doctor, ensureInitialized, and all test references - Update README, GUIDE, VISION cross-references BREAKING CHANGE: docs/method/process.md, docs/method/release.md, and docs/method/release-runbook.md no longer exist. Use docs/PROCESS.md and docs/RELEASE.md instead.
…ent move The README was slimmed from 561 to 107 lines with deep content moving to docs/PROCESS.md. Updated 13 failing tests in docs.test.ts and repo-discipline.test.ts to point assertions at their new locations: - Structure assertions now check Principles/Structure/The loop/Documentation - Cycle closeout, branch naming, RED step, abstract seats assertions -> PROCESS.md - Forge-agnostic distinction assertions -> PROCESS.md - Legend listing assertions simplified (README no longer enumerates each legend) - CI gate and drift detector assertions decoupled from README tooling section - CLI/MCP command listing assertions trimmed (README now just links to references) - Release-note surface assertions simplified for slim README - Open-cycle-packet-on-main assertions -> PROCESS.md only
Honest assessment of METHOD's friction points after a full session: - Right-sized cycle ceremony (t-shirt sizing S/M/L) - Optional posture sections in design doc template - Meaningful retros over template retros - Sponsors field is pure boilerplate - Drift detector rewards string-matching over meaningful tests - Signpost count scales with overhead not complexity - Maintenance track for sub-cycle work - Auto-regenerate reference docs instead of manual sync
Pre-commit hook now runs sync refs after lint, staging any changes to ARCHITECTURE.md, docs/CLI.md, docs/MCP.md, docs/GUIDE.md. No more stale generated docs. Closes cycle PROCESS_auto-regenerate-reference-docs-instead-of-manual-sync.
…tion prompts Retro template now has 3 focused sections instead of 6 hollow ones: - "What surprised you?" (replaces Drift + New Debt) - "What would you do differently?" (replaces Cool Ideas) - "Follow-up items" (replaces Backlog Maintenance checklist) CLI close prompts updated to match. Two honest sentences beat five empty sections. Closes cycle PROCESS_meaningful-retros-over-template-retros.
…mplate Every design doc said "Human: Backlog operator, Agent: Implementation agent" — pure boilerplate that never varied and communicated nothing. The Human/Agent distinction is already carried by the playback question split. Removed the Sponsors section and the "abstract roles" paragraph from the scaffold. Closes cycle PROCESS_sponsors-field-is-pure-boilerplate.
When a title like "DX-022 — Layout Inspector Overlay" is captured with legend=DX, createBacklogItem now strips the leading "dx-" from the slug to avoid producing "DX_dx-022-layout-inspector-overlay.md". Result: "DX_022-layout-inspector-overlay.md". Closes cycle PROCESS_backlog-helper-generates-malformed-note-filenames.
`method doctor --receipt` produces a JSON receipt anchored to the current commit SHA, including timestamp, status, counts, and checks. Release gates can now verify the doctor pass matches the exact state being shipped. Also exposed via MCP as `method_doctor_receipt`. Closes cycle PROCESS_doctor-sha-locked-health-receipts.
…kthrough - Cycle lifecycle flowchart - Backlog flow diagram - Git branch lifecycle (gitGraph) - File lifecycle diagram - Release flow diagram - Common commands quick reference table - Getting started section - Practical advice (capture ideas, single intake path)
CRITICAL: - Remove committed flyingrobots-method-1.0.0.tgz, add *.tgz to .gitignore HIGH: - Fix ghost "method doctor --repair" → "method repair --apply" in fix text - Bump MCP server version from 0.3.0 to 2.0.0 - Narrow catch(error: any) to catch(error: unknown) with type guard MEDIUM: - Add unicode flag to LEGEND_PATTERN, CYCLE_NAME_PATTERN, LEGACY_CYCLE_PATTERN - Enable noExplicitAny in biome.json (5 test usages annotated with biome-ignore) - Document up-next as legacy lane in orderedBacklogLaneNames LOW: - Dedupe collectMarkdownFiles (doctor.ts delegates to workspace-utils.ts) - Pre-commit hook warns on sync refs failure instead of silently swallowing - Use path.resolve() instead of string concatenation in workspace-utils.ts NIT: - Import resolve in workspace-utils.ts - Hoist 5 regex constants to module scope in drift.ts
- frontmatter.ts: assertNoTypeDowngrade now allows any type to replace a null value (typeof null === "object" was causing false downgrades) - doctor.ts: flatten-design-doc repair now matches by slug convention before falling back to first .md file, preventing data loss when legacy dirs contain multiple .md files (e.g. README.md alongside the actual design doc) - Added test for null-field type-downgrade edge case
- Tighten grammar in sponsor-abstractness invariant doc - Narrow legacy-layout detection to NNNN-slug pattern only (prevents false positives on non-cycle subdirectories) - Add defensive comment explaining repair snapshot idempotency - Add test proving CycleSchema strips legacy `number` field - Remove hardcoded backlog path in ship-sync test
|
Important Review skippedToo many files! This PR contains 285 files, which is 135 over the limit of 150. ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (285)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Owner
Author
|
@coderabbitai review please 🥕 |
|
✅ Actions performedReview triggered.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c1529cda13
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+1292
to
+1294
| if (value !== undefined) { | ||
| positionals.push(value); | ||
| } |
There was a problem hiding this comment.
method spike
The spike parser currently treats any unknown token (including values that start with -) as part of the goal text, so typos like --constraint silently succeed instead of failing fast. This can create malformed spike entries and hide operator mistakes that every other command parser reports as unknown options.
Useful? React with 👍 / 👎.
Owner
Author
There was a problem hiding this comment.
✅ Addressed in 7a8a785. parseSpikeArgs now rejects unrecognized --options with an error message, matching every other command parser.
Comment on lines
+809
to
+810
| // Remove the old directory (all files should be the single md) | ||
| rmSync(target, { recursive: true }); |
There was a problem hiding this comment.
The flatten-design-doc repair removes the entire legacy directory after copying a single selected Markdown file to the flat path. If that directory contains extra Markdown files or attachments, those files are irreversibly deleted during method repair --apply, which turns a “safe bounded repair” into data loss for real workspaces.
Useful? React with 👍 / 👎.
Owner
Author
There was a problem hiding this comment.
✅ Addressed in 7a8a785. Flatten repair now only deletes the source .md file and removes the directory only if empty. Non-cycle files (attachments, READMEs) are preserved.
| cycle: relativizeCycle(workspace, cycle), | ||
| }, | ||
| ); | ||
| const cycle = await workspace.closeCycle(cycleName, driftCheck, outcome); |
There was a problem hiding this comment.
The MCP method_close path closes cycles as soon as driftCheck and outcome validate, but unlike the CLI close flow it never requires an explicit witness-verification acknowledgement. That lets automated MCP callers bypass the human verification gate and close cycles without the process control introduced in this release.
Useful? React with 👍 / 👎.
Owner
Author
There was a problem hiding this comment.
✅ Addressed in 7a8a785. MCP method_close now requires witnessVerified: true as a required field. If false, the call is rejected with an error message. Matches the CLI's human-in-the-loop gate.
…CP witness gate) - cli-args.ts: parseSpikeArgs now rejects unrecognized --options - doctor.ts: flatten repair only deletes the source .md file, removes dir only if empty (prevents data loss for dirs with extra files) - mcp.ts: method_close now requires witnessVerified=true, matching the CLI's human-in-the-loop gate
Owner
Author
PR #24 Review Feedback — Resolution Summary
All 3 issues resolved. CI fix for git identity in |
Owner
Author
|
@coderabbitai full review please 🥕 |
|
✅ Actions performedFull review triggered. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v2.0.0 release branch — 42 commits, 17 closed cycles, 293 tests passing.
Breaking Changes
docs/design/<LEGEND>_<slug>.mdreplacesdocs/design/<NNNN>-<slug>/<slug>.mdPROCESS_fooreplaces0039-foonumberfield removed fromCycletypedocs/method/process.md→docs/PROCESS.md,docs/method/release.md+release-runbook.md→docs/RELEASE.mdNew Features
method spikecommand andmethod_spikeMCP toolmethod doctor --receiptfor SHA-locked health attestationsmethod_doctor_receiptMCP tool.method.jsonmethod close--summary,--witness-verifiedfor non-interactive)updateTypedFrontmatterFixes
rm -rf distbeforetsc(clean builds)method_pullandmethod_capture_witness.gitkeepin required directoriesNNNN-slugpatternInfrastructure
SCAFFOLD_LANESas single source of truth for lane materializationcycle-ops.tsandworkspace-utils.tsextracted from Workspace god classProcess Doctrine
Backlog
Test plan
method doctorzero issues