Repository navigation
[codex] refresh METHOD signposts and legend structure - #1
Merged
Merged
Conversation
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 17 minutes and 18 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (23)
WalkthroughReorganizes and expands documentation: README restructured into explicit Stances/Design constraints/Quality gates/Coordination; adds signposts ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
flyingrobots
marked this pull request as ready for review
April 3, 2026 00:29
![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: 0e7b57a33c
ℹ️ 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".
| import { resolve } from 'node:path'; | ||
| import { describe, expect, it } from 'vitest'; | ||
|
|
||
| const REPO_ROOT = resolve(import.meta.dirname, '..'); |
There was a problem hiding this comment.
REPO_ROOT is derived from import.meta.dirname, which is only available in newer Node runtimes; this repo declares "node": ">=18", so running npm test on Node 18 will resolve import.meta.dirname as undefined and fail before any docs assertions run. Using a URL-based pattern (for example via import.meta.url) keeps the test suite compatible with the stated engine range.
Useful? React with 👍 / 👎.
| title: "METHOD - Executive Summary" | ||
| generated_at: 2026-04-02 | ||
| generator: "manual synthesis during cycle 0004-readme-and-vision-refresh" | ||
| generated_from_commit: "bc8ee26e5b4dea02079fbeabfb610873ceb4b65a" |
There was a problem hiding this comment.
The generated_from_commit value points at bc8ee26..., which is not in the ancestry of this reviewed commit (dcafbd...), so the provenance pointer can be non-reproducible in histories where this change is applied without that side branch. Because this document claims repo-state grounding, the commit it cites should be reachable from the same history so readers can actually inspect the referenced state.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CHANGELOG.md`:
- Around line 9-10: Two changelog bullets describing docs-test changes are
duplicated/overlapping; consolidate them into a single concise entry that
captures both intents (keeping the current legend split and preserving the
VISION signpost truthfulness) and remove the redundant line. Edit CHANGELOG.md
to replace the two separate bullets with one merged, tighter sentence that
mentions "extended docs tests" and both outcomes (legend split preservation and
VISION signpost accuracy).
In `@docs/method/backlog/inbox/PROCESS_legend-audit-and-assignment.md`:
- Around line 7-9: The document uses legacy legend codes CORE/WARP; update all
occurrences of CORE to PROCESS and WARP to SYNTH (including the sentence "define
a new `CORE` legend" and "classify every backlog item under either `CORE` or
`WARP`") so the wording, examples, and any inline code/labels match the repo's
standardized taxonomy (`PROCESS`/`SYNTH`); ensure the legend definition,
examples, and any downstream references in this file are renamed consistently to
avoid mismatch with tooling and audits.
In `@docs/method/backlog/inbox/SYNTH_executive-summary-protocol.md`:
- Around line 1-22: The document titled "Executive Summary Protocol" currently
only records session context and requirements rather than a formal, actionable
protocol; replace the requirements analysis with a concrete protocol section
(e.g., add a "Protocol specification" heading) that enumerates ordered steps for
Phase 1 Inventory (explicit precedence: README, docs/method/process.md and
instructions, docs/method/legends/*, docs/design/*, docs/method/retro/*, backlog
lanes, graveyard), Phase 2 Read & Synthesize (what to extract: identity, state,
legends, roadmap; required output sections: Identity, Current state, Signposts,
Legends, Roadmap, Open questions, Limits), Phase 3 Generate Witness (timestamp,
commit SHA, source manifest, witness reference, frontmatter contract), and Phase
4 Verification (repo tests, METHOD CLI checks); ensure the protocol clearly
separates synthesis from mutating follow-up steps and mandates citation/witness
rules for each required output section so the procedure is repeatable and
auditable.
In `@docs/method/backlog/inbox/SYNTH_generated-signpost-provenance.md`:
- Around line 1-3: In the "Generated Signpost Provenance" document add a new
explicit "Provenance Contract" section that enumerates each metadata field, its
canonical field name, data type, and whether it is required or optional; for
example: generation_time (required, ISO-8601 string), commit (required, git SHA
string), source_files (required, array of objects with path:string and
content_hash:string), read_order_version (required, semantic or integer
version), origin_request (optional, object with request_id:string and
requester:string), witness_location (required, URI or storage reference string),
plus an optional metadata map for extensibility; include a short single-example
JSON object illustrating these fields and a note that the full session witness
must be referenced by witness_location rather than inlined.
- Around line 1-21: The tests in tests/docs.test.ts use weak toContain()
assertions for provenance (variable vision), which allow empty/invalid values;
replace those toContain() checks (around the assertions for generated_at,
generator, witness_ref, source_files and source file list) with regex assertions
using toMatch() to validate actual values—e.g., assert generated_at has a
non-empty token, generator is a quoted non-empty string, witness_ref is a
non-empty token, source_files header exists, and at least one "- <file>" list
item appears; keep/retain the existing generated_from_commit regex check but
swap any remaining toContain() checks to equivalent toMatch() patterns to
enforce real provenance values.
In `@docs/method/retro/0003-readme-revision/witness/verification.md`:
- Line 13: The verification artifact contains a local absolute path with a
personal username ("RUN v4.1.2 /Users/james/git/method"); sanitize these
entries across the file (and the other occurrences at lines 30 and 67) by
replacing local absolute paths with a neutral placeholder such as "<REPO_ROOT>"
or a relative path; update the witness/verification.md content wherever the
string "/Users/james/" or similar user-specific paths appear so committed logs
contain no personal identifiers.
In `@docs/method/retro/0004-readme-and-vision-refresh/witness/playback.md`:
- Around line 42-49: The playback claims six frontmatter fields but the test
suite only asserts five fields weakly; update the tests in tests/docs.test.ts to
assert all six provenance fields (generated_at, generator,
generated_from_commit, provenance_level, witness_ref, source_files) and
strengthen assertions to verify non-empty/valid values (e.g., non-empty string
or appropriate format for generated_at/commit) rather than using toContain() so
the mechanical checkability claim matches actual coverage; also update the
playback text if needed to reflect the tightened tests.
In `@docs/VISION.md`:
- Around line 73-75: The three consecutive list items starting with "`docs/`"
create monotony; update the three bullets referencing README.md,
docs/BEARING.md, and docs/VISION.md so they vary their leading phrasing (for
example, start one with "See README.md", another with "Refer to BEARING
(docs/BEARING.md)", and keep the VISION line as "docs/VISION.md for a bounded
executive synthesis"), ensuring the same content is preserved but the first
token differs to satisfy the style check.
- Around line 80-82: Remove the duplicate hard-coded commit hash sentence ("This
summary describes repo state as of commit
`bc8ee26e5b4dea02079fbeabfb610873ceb4b65a`.") and either delete that line or
replace it with a generic cross-reference to the frontmatter key
generated_from_commit (e.g., "See frontmatter generated_from_commit for the
source commit") so provenance is driven solely by the generated_from_commit
value.
- Line 3: Update the generated_at entry to include a full ISO 8601 timestamp
with time and timezone instead of a date-only value; replace the current
"generated_at: 2026-04-02" value with a timestamp like "2026-04-02T17:04:50Z"
(or an appropriate local offset) so it satisfies the provenance contract
referenced by SYNTH_generated-signpost-provenance.md and records precise
generation time.
In `@README.md`:
- Around line 184-186: Update the stale legend code examples that currently use
`VIZ`/`PROTO`/`TUI` so they match the declared active legends `PROCESS` and
`SYNTH` (or use neutral placeholders); specifically locate the example usages
referenced (the sentence "A legend code (`VIZ`, `PROTO`, `TUI`) prefixes backlog
filenames..." and other occurrences) and replace the legacy codes with `PROCESS`
and `SYNTH` (or a neutral example like `LEGEND1`/`LEGEND2`) so the README's
examples are consistent with the declarations.
In `@tests/docs.test.ts`:
- Around line 1-6: Replace the use of import.meta.dirname (which breaks on Node
<20.11) when computing REPO_ROOT in tests; instead reproduce the pattern used in
src/cli.ts by converting import.meta.url to a path via
fileURLToPath(import.meta.url) and then resolve('..') from that directory to set
REPO_ROOT (update the const REPO_ROOT assignment in tests/docs.test.ts and
reference fileURLToPath/import.meta.url rather than import.meta.dirname).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7d06ac3c-ce94-4a75-9384-0ed26484ac8f
📒 Files selected for processing (23)
CHANGELOG.mdREADME.mddocs/BEARING.mddocs/VISION.mddocs/design/0003-readme-revision/readme-revision.mddocs/design/0004-readme-and-vision-refresh/readme-and-vision-refresh.mddocs/method/backlog/inbox/PROCESS_behavior-spike-convention.mddocs/method/backlog/inbox/PROCESS_legend-audit-and-assignment.mddocs/method/backlog/inbox/SYNTH_artifact-history-and-semantic-provenance.mddocs/method/backlog/inbox/SYNTH_executive-summary-protocol.mddocs/method/backlog/inbox/SYNTH_generated-signpost-provenance.mddocs/method/backlog/up-next/PROCESS_drift-detector.mddocs/method/legends/PROCESS.mddocs/method/legends/SYNTH.mddocs/method/retro/0003-readme-revision/readme-revision.mddocs/method/retro/0003-readme-revision/witness/README.mddocs/method/retro/0003-readme-revision/witness/playback.mddocs/method/retro/0003-readme-revision/witness/verification.mddocs/method/retro/0004-readme-and-vision-refresh/readme-and-vision-refresh.mddocs/method/retro/0004-readme-and-vision-refresh/witness/README.mddocs/method/retro/0004-readme-and-vision-refresh/witness/playback.mddocs/method/retro/0004-readme-and-vision-refresh/witness/verification.mdtests/docs.test.ts
Owner
Author
|
@coderabbitai review please 🥕 |
|
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/method/backlog/inbox/PROCESS_legend-audit-and-assignment.md`:
- Around line 17-18: The phrase "silently require" in the sentence referencing
METHOD is ambiguous; replace it with precise wording that states the intended
behavior—either "METHOD should not enforce full legend coverage by default;
repos must opt in to require full coverage" or "METHOD should provide a
configurable coverage policy and document the default." Update the sentence
containing "silently require" (search for that exact phrase) to one of the two
clearer alternatives and ensure the doc explicitly mentions opt-in or
configurability and the documented default.
- Around line 7-9: Split the long sentence into two clear sentences so the
legend taxonomy is front-loaded: first state that you defined a new legend named
PROCESS and that every backlog item was classified as either PROCESS or SYNTH
(use the literal names PROCESS and SYNTH prominently), then add a follow-up
sentence with the context about generating the graft executive summary (do not
format the project name as code). Ensure the legend names appear in the main
clause and the contextual detail is a separate, shorter sentence.
- Line 3: The phrase "exhaustive legend coverage optional" is too vague—update
PROCESS_legend-audit-and-assignment.md to define exactly what "optional" means,
how a repo opts in, and the resulting tooling behavior: specify a concrete
config key (e.g., method.config: enforceLegendCoverage: true/false) and/or
repo-level toggle (CI variable or .methodrc flag) to opt in, state the default
(false = untagged backlog items allowed), and define enforced behavior when true
(e.g., PRs blocked by a "legend-audit" CI check, method status returns
non-zero/fails, and legend-audit CLI reports orphaned items), and add the
commands/check names that will reflect failures (e.g., legend-audit, method
status) so implementers know what to wire up.
In `@docs/method/backlog/inbox/SYNTH_generated-signpost-provenance.md`:
- Around line 59-60: Update the wording in the sentence that currently reads
"METHOD should define which provenance fields are mandatory and which are
optional for generated docs" to reflect that the contract is already defined;
change it to a present-tense statement such as "METHOD defines which provenance
fields are mandatory and which are optional for generated docs" (or similar).
Locate the sentence labeled "METHOD" near the contract table and replace the
future/conditional phrasing with a present-tense or declarative form to match
the already-defined contract table.
In `@tests/docs.test.ts`:
- Around line 47-61: The test currently uses
expect(codes.length).toBeGreaterThan(0) which will fail with a generic message
if the legends directory is empty or missing; update the assertion in the test
that uses legendCodes() (the test block starting with "describes the discovered
legends in repo-visible docs") to provide a clear custom failure message (or
assert codes is defined and then use toBeGreaterThan(0) with a message like "no
legends found in docs/method/legends — expected at least one legend") so that a
missing/empty legends directory yields a descriptive error instead of a cryptic
length mismatch.
- Around line 89-95: The test only checks for macOS paths ('/Users/') so it
misses Linux and Windows absolute-home paths; update the test that reads
readmeRevisionVerification and visionRefreshVerification (the variables returned
by readRepoFile in the 'sanitizes personal absolute paths from committed
verification witnesses' test) to also assert they do not contain common Linux
and Windows home path patterns (e.g., '/home/', '/root/', '/mnt/' and
Windows-style 'C:\\Users\\' or other drive-letter patterns) or use a single
regex check that rejects common absolute path prefixes across platforms; change
the expect calls to include those additional patterns (or replace them with a
cross-platform regex) so commits from Linux/Windows contributors are caught.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 94e693d5-6780-474f-a2d2-6eb0a4a84604
📒 Files selected for processing (10)
CHANGELOG.mdREADME.mddocs/VISION.mddocs/method/backlog/inbox/PROCESS_legend-audit-and-assignment.mddocs/method/backlog/inbox/SYNTH_executive-summary-protocol.mddocs/method/backlog/inbox/SYNTH_generated-signpost-provenance.mddocs/method/retro/0003-readme-revision/witness/verification.mddocs/method/retro/0004-readme-and-vision-refresh/witness/playback.mddocs/method/retro/0004-readme-and-vision-refresh/witness/verification.mdtests/docs.test.ts
Owner
Author
|
@coderabbitai review please 🥕 |
|
✅ Actions performedFull review triggered. |
Moved from warp-ttd inbox — these are Method process items, not warp-ttd-specific.
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CHANGELOG.md`:
- Around line 5-19: CHANGELOG.md currently has several consecutive doc-focused
bullets that read like a commit log; consolidate them into 2–3 user-facing,
high-signal entries by merging the related bullets that start with "Clarified
that METHOD...", "Clarified legend coverage...", "Extended docs tests...",
"Sorted the METHOD backlog...", and "Added `docs/VISION.md`/`docs/BEARING.md`"
into concise statements describing the user-visible impact (e.g., “Improved
documentation and tests to prevent path/legend leaks and to clarify METHOD usage
and legends”), remove file-level noise, and keep one short entry describing
README/structure revisions (from the bullet that begins "Revised the README
structure...") so the changelog communicates outcomes rather than listing
touched files.
In `@docs/method/backlog/inbox/playback-witness-convention.md`:
- Around line 1-10: This document lacks the backlog legend prefix and has
ambiguous language; rename the file to include the PROCESS_ legend (e.g.,
PROCESS_playback-witness-convention) and update the "Playback Witness
Convention" content to explicitly state it belongs to PROCESS (cycle discipline)
rather than leaving it untagged, clarify what "step 4" refers to (explicitly say
"step 4 of the retro/cycle loop"), and replace "Maybe a small script" with a
clear decision: either require automated capture (describe minimal spec: capture
pnpm test stdout/stderr, screenshots, transcript, file naming/location under
docs/method/retro/<cycle>/witness/) or mark it as optional guidance; commit the
chosen stance and tighten the wording accordingly.
In `@docs/method/backlog/inbox/SYNTH_generated-signpost-provenance.md`:
- Around line 34-48: Replace the JSON example with a YAML frontmatter example
matching actual usage (emit the block as YAML frontmatter using keys
generated_at, generator, generated_from_commit, provenance_level, witness_ref,
source_files, read_order_version) and explicitly state that generated_at
requires a full ISO 8601 timestamp including timezone (e.g.
2026-04-02T17:41:54-07:00); alternatively, make the contract format-agnostic by
showing both JSON and YAML examples and clarifying that either is acceptable but
generated_at must conform to the full-timestamp regex used in tests.
In `@README.md`:
- Around line 81-84: Add a unit test to tests/docs.test.ts (e.g., test titled
"enforce signpost depth") that scans the repo for signpost files named in
ALL_CAPS.md format and fails if any are located deeper than allowed;
specifically, allow README.md at repo root and allow ALL_CAPS.md files directly
under docs/ (docs/<NAME>.md) or at repo root, but reject any ALL_CAPS.md found
in subdirectories below docs/ (e.g., docs/**/ALL_CAPS.md) or any other deeper
path. Implement the test using a glob (or fs walk) to find files matching the
ALL_CAPS.md pattern, filter paths by relative depth (permit root and
docs/<file>.md), and assert.fail with the list of offending paths if any are
found.
In `@tests/docs.test.ts`:
- Around line 128-134: The tests assert YAML fields on the string vision with
inconsistent quoting rules; update the expect(...) regexes so they are either
consistently quoted or accept optional quotes: change the generated_from_commit
regex (the expect(vision).toMatch for generated_from_commit) to allow optional
surrounding double quotes around the 40-hex commit, update the provenance_level
regex (the expect for provenance_level) to allow optional quotes around
artifact_history, and make the generator regex allow optional quotes while still
requiring a non-empty value (i.e., accept generator: value or generator: "value"
but not empty string).
- Around line 79-103: The provenance test in the "records synthesis protocol and
provenance contract details in backlog docs" spec (tests/docs.test.ts) only
checks for presence of certain field names; update the test to also validate
optional fields in the provenance doc (SYNTH_generated-signpost-provenance.md)
by: reading the provenance string (provenance variable via readRepoFile),
asserting that if `read_order_version`, `origin_request`, or `metadata` appear
they match the expected format (e.g., backticked key plus appropriate
value/structure or YAML/JSON snippet) and adding negative assertions that these
optional keys are not present in an unexpected format; use the provenance
variable name and the test block to add these conditional regex/structure checks
so the test fails when optional fields are either missing when expected or
present but malformed.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0579dfab-945b-4e7a-962b-04c0a9fa7840
📒 Files selected for processing (8)
CHANGELOG.mdREADME.mddocs/method/backlog/inbox/PROCESS_legend-audit-and-assignment.mddocs/method/backlog/inbox/SYNTH_generated-signpost-provenance.mddocs/method/backlog/inbox/drift-detector.mddocs/method/backlog/inbox/method-cli.mddocs/method/backlog/inbox/playback-witness-convention.mdtests/docs.test.ts
Owner
Author
|
@coderabbitai review please 🥕 |
|
✅ Actions performedFull review triggered. |
This was referenced Apr 3, 2026
This was referenced Apr 5, 2026
This was referenced Jun 1, 2026
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.
What changed
PROCESSandSYNTHlegends and added legend docs for bothdocs/BEARING.mdanddocs/VISION.mdas bounded repo signposts0003-readme-revisionand0004-readme-and-vision-refreshwith retros and witness packetsWhy
METHOD's repo surfaces had drifted behind the way the repo is now actually being used. This PR makes the signposts truthful again, dogfoods a bounded executive summary for METHOD itself, and leaves behind the backlog needed to turn that manual synthesis into real tooling later.
Impact
Validation
npm testnpm run buildnpm run method -- status