Railspike v0.4.0

This stable release follows v0.1.0 and collects the work from the v0.2.0–v0.4.0 betas. It adds recovery checks for named users, optional effort estimates, one-shot mode for bounded tasks, one-prompt uninstallation, and a clearer welcome after installation.

Product revision: ea1ad5b524c2b447d3e61b15ccd3cd412ce6ecef. This is the same commit as v0.4.0-beta.3, now on main.

What changed since v0.1.0

Recovery and honest verification

• When a request names a user or environment, Step 2 states that user's ordinary entry point and recovery condition. Step 3 then replays each reported failure as acceptance evidence. Evidence from a different platform doesn't count.
• Step 4 reports each check as passed, failed, blocked, pending, or inapplicable. A focused pass is never presented as a full-suite or user-outcome result, and the handoff opens with anything unverified.

One-shot mode

• For a bounded task you explicitly authorize, the agent keeps one evolving record instead of separate step files, with no intermediate approvals. The record holds the request, authorization, scope, approach, changes, verification and outcome.
• Questions and plan references never grant authority. A request that grows needs renewed authorization or a move to staged planning. An interrupted one-shot resumes from its record.

Effort estimates (optional)

• A project can enroll its cycles in a relative effort study. Estimates are recorded at each planning checkpoint and as a retrospective at closeout, measured against bundled reference examples (R1).
• For enrolled cycles, every Step 1 option and every Step 3 stage gets an estimate, shown as a bold line under its heading. Originals, revisions and retrospectives are kept separately. Estimates are relative judgments, not hours or forecasts.
• Agents sign their plan contributions with their name and date, adding model and settings only when verified. A Step 3 plan written in one pass gets a single footer.

Installing and removing

• A new Uninstall section gives a one-prompt removal for copied and submodule installations. It keeps your docs/plans/ and stops when anything is unclear.
• After installation, the welcome asks whether to add Railspike guidance to AGENTS.md as a question on its own. Your first task is asked for afterwards. The agent reports the outcome: added, declined, or not answered.
• The README describes agent-led upgrades and legacy migration, including preserving local edits.

Compatibility and migration

• The planning steps, Approved Step N gates, feature branches, and planning and stage commits still work as they did in v0.1.0. The new Step 2–4 recovery and reporting requirements apply when a user or environment is named, and they shape what each step records.
• One-shot mode and effort estimates are opt-in.
• Existing installations are not changed until you upgrade them. Use the README's reviewed upgrade process and select v0.4.0. Local edits and the installation source record are preserved.
• The welcome runs only after a new installation, and the AGENTS.md guidance text is unchanged, so existing guidance sections remain valid.
• To roll back, select v0.1.0 (or an earlier beta) through the same process. Before you roll back, finish or pause any one-shot cycle, because older instructions don't know about one-shot mode.

Verification

These checks passed on a clean clone of main at the exact commit:

• Markdown links with all three checkers: 16 files.
• The README Git-workflow fixture.
• Whitespace against v0.1.0.
• The repository-separation fixture with legacy baseline b59f7df89842ba17f710ae1f2dc955bb361cc620. It covered remote clone, copied install, actual-history submodule migration, old-source rejection, local-edit preservation, rollback and host isolation, with 18 product files.

The maintainer also ran these live checks in real projects:

• A reinstall in which the welcome asked the AGENTS.md question on its own.
• An uninstall of a copied installation.
• An interrupted one-shot cycle resumed in a new session with OpenAI Codex v0.164.0 and the prompt "Please resume". The agent found the record and its authorization and kept the partial work and unrelated changes. It reran verification, recorded the resumption honestly, and committed without pushing.

Known limitations

• Uninstalling a submodule installation was tested only by following the documented steps in disposable repositories, not by a live agent.
• The live one-shot test used a project with no effort study enrolled, and the effort-study mechanics were not exercised live in this release:
  • an estimate revised mid-stage;
  • opt-outs;
  • recovery of older cycles.
• Railspike is a set of instructions, not technical enforcement. These checks show the instructions are consistent and that some agents follow them in practice; they do not guarantee every agent will.
• The tag is annotated and unsigned. It identifies the revision but does not authenticate a signer. A maintainer signing key has not been set up yet.

Railspike v0.4.0-beta.3

The post-install welcome now asks whether to add Railspike guidance to AGENTS.md as a question on its own, so the offer gets an answer instead of being overlooked.

• The welcome ends with one yes/no question, such as "Add this to AGENTS.md? (yes/no)", with nothing after it. The agent asks for your first task only after you reply.
• Yes: the agent adds or updates the guidance under the existing consent rules. It preserves unrelated AGENTS.md content and does not add a duplicate Railspike section.
• No: the agent leaves the file alone and doesn't offer again.
• Anything else, such as a task: the agent leaves the file alone, tells you in one line that the guidance was not added and that you can ask for it later, and carries on with what you said. It won't ask again in that session.
• The agent always states the result: AGENTS.md: added, declined, or not answered.
• A task you included with the installation request is still kept. It starts after the guidance question, and you aren't asked for it again.

The previous welcome put the offer and "What would you like to work on first?" in the same turn. It also told agents to treat an unanswered offer as declined without saying so.

Merge and compatibility

Compared with v0.4.0-beta.2, this beta changes only WELCOME.md and two Quick start sentences in README.md. Workflow steps, approvals, artifacts, branches, commits, and the installation, update, and uninstall procedures are unchanged. The guidance text offered for AGENTS.md is unchanged, so existing Railspike sections remain valid.

Following the default beta policy, this beta is tagged on the unmerged product branch feature/welcome-guidance-question; main is not changed. Default installs from main still get v0.4.0-beta.2 content. To try this beta, name the tag in an install or upgrade request. Stable Latest remains v0.1.0.

Revision and evidence

• Product commit: ea1ad5b524c2b447d3e61b15ccd3cd412ce6ecef on feature/welcome-guidance-question.
• Annotated tag: v0.4.0-beta.3; tag object d87f3f8800ecedaf19056a3690fa623b4c6b5a45. The tag is unsigned: it identifies a revision but does not provide cryptographic signer authentication.

These checks passed on a clean clone of the exact commit:

• Markdown links with all three checkers (Python, Perl, Node.js): 16 files.
• The README Git-workflow fixture.
• Whitespace (git diff --check against beta 2).

The repository-separation fixture was not rerun because installation and migration procedures are unchanged.

A written walk-through of the revised welcome covered seven replies: yes; no; a task instead; yes with an existing section; a task supplied with the install request; "later" or a question; and an explicit opt-out. It also replayed the maintainer's own beta 2 install transcript. Under the new text, that welcome stops at the guidance question.

Not verified: a live agent following the new welcome, including the maintainer's Kiro Web and CLI. The checks establish consistent instructions, not agent compliance.

Update and recovery

Use the existing reviewed upgrade process. Select v0.4.0-beta.3 from https://github.com/rlspk/railspike and verify the product commit above. Preserve local edits and the installation source record. No host installation is upgraded automatically.

The welcome runs only after a new installation, so existing installations see no behavior change until someone reinstalls. To roll back, select v0.4.0-beta.2 through the same process.

Stable exit criterion

The criteria from beta 2 are unchanged. In addition, confirm in a live installation that the welcome asks the guidance question on its own and reports the outcome. Publishing this beta does not claim these criteria are met.

Railspike v0.4.0-beta.2

You can now remove Railspike with one prompt to your coding agent. Your own plans stay in place.

• A new Uninstall section in the README has a copyable prompt and step-by-step agent guidance. The agent:
  • identifies whether Railspike is installed as a copy or a submodule;
  • reports local edits before removing anything;
  • removes the installation, the optional ## Railspike section of AGENTS.md, and the optional .railspike_debug_on marker;
  • stops and asks when the installation type is unclear (for example, a subtree).
• Your docs/plans/ and all unrelated files are kept. Changes are left uncommitted for your review. For a submodule, the removal is staged, and empty submodule metadata and an empty .gitmodules are cleaned up.
• The Quick start now links to the Uninstall section. The same prompt appears on railspike.dev.

Merge and compatibility

Compared with v0.4.0-beta.1, this beta changes only README.md (21 lines added, 1 changed). No workflow instructions, approvals, artifacts, branch rules, or commit rules changed. The installation, update, and migration procedures are unchanged.

The maintainer explicitly requested this beta on the current product main, which already contains the change. As with beta 1, default installs from main already include it. The GitHub release is a pre-release; stable Latest remains v0.1.0.

Revision and evidence

• Product commit: 5952bfddba579ca3e76bbf397e7a0a5bbf150785 on main.
• Annotated tag: v0.4.0-beta.2; tag object 2ca4fe090819e47fc4fa5ef7ec67b565b376a9cc. The tag is unsigned: it identifies a revision but does not provide cryptographic signer authentication.

These checks passed on a clean clone of the exact commit:

• Markdown links with all three checkers (Python, Perl, Node.js): 16 files.
• The README Git-workflow fixture.
• Whitespace (git diff --check against beta 1).
• The repository-separation fixture, with legacy baseline b59f7df89842ba17f710ae1f2dc955bb361cc620. It covered remote clone, copied install, actual-history submodule migration, old-source rejection, local-edit preservation, rollback and host isolation, with 18 product files.

The uninstall steps were tested by following them as shell commands in disposable projects:

• a copy;
• a customized copy;
• a copy whose AGENTS.md has no Railspike section;
• a submodule;
• a submodule alongside an unrelated submodule with local edits.

In every case only the listed items were removed, and docs/plans/, unrelated files and other submodules were kept.

Not verified: a live coding agent following the uninstall prompt, including the maintainer's Kiro Web and CLI. The checks establish consistent instructions and fixture behavior, not agent compliance.

Update and recovery

Use the existing reviewed update process: select v0.4.0-beta.2 from https://github.com/rlspk/railspike and verify the product commit above. Preserve local edits and the installation source record. No host installation is upgraded automatically. To roll back, use the same process to return to v0.4.0-beta.1.

Stable exit criterion

Unchanged from beta 1:

• Review real one-shot records for evidence parity, bounded authorization, interrupted-session recovery, scope transitions and honest incomplete outcomes, including the maintainer's Kiro Web/CLI use.
• Confirm that staged behavior remains intact, and preserve the prior beta criteria.

In addition, confirm that a live agent follows the uninstall prompt correctly for both copied and submodule installations. Publishing this beta does not claim these criteria are met.

Railspike v0.4.0-beta.1

Railspike v0.4.0 beta 1

One-shot fixes can now retain development evidence comparable to staged Railspike cycles in one evolving record, without intermediate step approvals.

• Explicit bounded execution authorization is recorded before implementation. Questions and plan references grant no new authority; questions also do not automatically revoke existing authority.
• The record preserves intent, scope, approach, decisions, changes, verification, recovery and delivery status. Scope expansion needs renewed authorization or a linked transition to staged planning.
• One-shot cycles use a feature branch and normally a completion commit, with no separate planning commit. Explicit no-commit requests take precedence. Existing staged approval and commit requirements remain in force.
• Host study/debug policies apply independently. One-shot checkpoints preserve original estimates, scope revisions and incomplete outcomes without fabricating stages or historical approvals.

Merge and compatibility

The maintainer explicitly requested both merging and this beta release. Product main now contains the reviewed one-shot changes and their prior beta ancestry. This is a release-specific exception to the usual policy of keeping beta branches off main: default installs from main receive the new guidance. The GitHub release is still a pre-release, and stable Latest remains v0.1.0.

Compared with v0.3.0-beta.4, this adds optional one-shot mode and its recovery/documentation contract. Compared with the previous main, it also includes known-user recovery and qualified verification reporting, optional effort-study collection with recoverable references, extended estimates enabled by default for new enrolled cycles, prominent estimate presentation and verified-only attribution, and the single-footer rule for single-pass Step 3 plans. Existing study opt-outs and historical records are preserved; ordinary small tasks can still remain outside Railspike.

Revision and evidence

Product merge commit: 0dcab22380874e53dae641b3d82a24c703241ac9 on main.

Annotated tag: v0.4.0-beta.1; tag object: 75e776094fcf327a58cb4f40fe47018296203058. The tag is unsigned and identifies a revision without cryptographic signer authentication.

Product Markdown links, whitespace and the existing Git-workflow fixture passed on the merged revision. Manual document scenarios cover the reported instruction/approval failures, interruption, scope changes, no-commit requests, incomplete outcomes and study/debug combinations. See the verification record.

These checks establish document consistency and fixture behavior, not live Kiro Web/CLI compliance, trusted approval enforcement or calibrated effort forecasts. Runtime/UI/deployment checks are inapplicable; unchanged installation/migration procedures did not require rerunning their separate fixture.

Update and recovery

Use the existing reviewed installation update process to select v0.4.0-beta.1 from https://github.com/rlspk/railspike and verify the product commit above. Preserve local edits, installation source/revision records and host plan histories. No host installation is automatically upgraded.

Choose one-shot mode explicitly for bounded execution; existing staged cycles stay staged unless you authorize a mode/scope change. Do not convert old work into fabricated prospective records. Roll back through the same reviewed update process to the prior installed tag, such as v0.3.0-beta.4, while retaining host records. Stop an active cycle and reconcile its mode before using older instructions that lack one-shot support.

Stable exit criterion

Review real one-shot records for evidence parity, bounded authorization, interrupted-session recovery, scope transitions and honest incomplete outcomes, including the maintainer's Kiro Web/CLI use. Confirm staged behavior remains intact and preserve prior beta criteria for effort-history recovery, attribution and known-user outcome verification. Beta publication does not claim those live-agent criteria are met.

Railspike v0.3.0-beta.4

Railspike v0.3.0 beta 4

Step 3 plans written by one agent in one pass now use a single attribution footer for the whole plan, regardless of length.

• Use stage-level attribution only for stages subsequently authored or substantively revised separately.
• Preserve the original plan footer and prior attribution when recording revisions. Include model/settings only when verified.
• The generation template, review checklist and two-stage example now agree on this layout.

Extended estimates remain enabled by default for new enrolled cycles. Existing opt-outs, older cycle state, estimate semantics and approval/commit rules are unchanged.

Revision and evidence

Product commit: f8c8d2588a4a849a12acc7c425d99f533e218f8d on non-default branch fix/step3-attribution-footer.

Annotated tag: v0.3.0-beta.4; tag object: 8ddb8ef880c6e2bf3424ef71967b5a0bbbde43f0. Unsigned: identifies a revision without cryptographic signer authentication.

Product/development Markdown links, the existing Git-workflow fixture, whitespace/file-scope review and static attribution scenarios passed. See the verification record.

Checks establish document consistency and fixture behavior, not live-agent compliance or forecast accuracy. Runtime/UI/deployment checks are inapplicable. Installation/migration fixtures were not rerun because those procedures and behavior are unchanged.

Update and recovery

Use the existing reviewed installation update process to select v0.3.0-beta.4 from https://github.com/rlspk/railspike and verify commit f8c8d2588a4a849a12acc7c425d99f533e218f8d. Preserve local edits, a recoverable prior state, source/tag/revision records, and existing host plan histories. No host installation is automatically updated.

Apply the footer rule as plans are authored or revised; do not erase previous attribution. Roll back through the same reviewed process to the previous installed tag, such as v0.3.0-beta.3, retaining host records. This is a GitHub pre-release; default installation remains main and stable Latest remains v0.1.0.

Stable exit criterion

Review real Step 3 plans showing one footer for a single-pass author and preserved attribution for subsequent separate stage contributions. Retain beta 3's estimate visibility, history preservation, verified-only metadata, activation/recovery and known-user ordinary-entry recovery criteria. Publication does not establish calibrated forecasts or authenticated authorship.

Railspike v0.3.0-beta.3

Railspike v0.3.0 beta 3

Estimates are easier to scan, and agents attribute their plan contributions with verified model/settings when available.

Changes

• Each estimated option/stage has a standalone bold estimate line directly beneath its heading. The cycle estimate appears near the top of the artifact. Use plain numbers without approximation signs; keep drivers, uncertainty and metadata separate. Comparison/history tables use a dedicated estimate column.
• Original, revised and retrospective values stay separately labeled with retained history. Missing and unavailable values remain explicit. Estimate meanings, R1 and mode defaults are unchanged.
• Agents sign beneath their authored/revised contributions with their name and UTC date. Include model/version and relevant settings such as reasoning effort or temperature when verified for that contribution. Omit unknown fields rather than guessing or delaying work.
• Preserve earlier signatures and append dated “Revised by” attribution on revisions, including changed model/settings. Attribution applies across Steps 1–4 independently of estimate/debug mode. It is textual authorship, not cryptographic signing, approval or an independent rating.

Revision and evidence

Product commit: 690c596307b2087515b7c258008e5835af89048b on non-default branch feature/estimate-presentation-attribution.

Annotated tag: v0.3.0-beta.3; tag object: 860af3ca9497e712ca1d9942ca901c369e3494dc. The tag is unsigned and identifies the revision without cryptographic signer authentication.

Product/development Markdown links, the existing Git-workflow fixture, whitespace/file-scope review, six example-format checks and sixteen static scenarios passed. See the verification record.

These checks establish document consistency and fixture behavior, not live-agent compliance, verified historical authorship or forecast accuracy. Runtime/UI/deployment checks are inapplicable. Installation/migration fixtures were not rerun: their procedures and behavior are unchanged; beta-2 evidence remains historical.

Update and recovery

Use the existing reviewed update process to select v0.3.0-beta.3 from https://github.com/rlspk/railspike, verify commit 690c596307b2087515b7c258008e5835af89048b, preserve local edits and a recoverable prior state, and record source/tag/revision. No host installations are updated automatically.

Apply the presentation and attribution guidance as plans are authored or revised. Preserve prior scores, scope histories, signatures and cycle settings; do not invent historical authors or runtime metadata. No bulk plan rewrite is required. To roll back, use the same reviewed process with the previous installed tag, such as v0.3.0-beta.2, while retaining host records.

Published as a GitHub pre-release: default installation stays on main and stable Latest remains v0.1.0. Existing approval, branch and commit requirements are unchanged.

Stable exit criterion

Review real cycles showing readily visible estimates, preserved revision histories, useful contribution attribution and honest handling of unknown model/settings. Retain beta 2's activation/opt-out/legacy recovery criteria and the earlier known-user ordinary-entry recovery criterion. Maintainer fit/study acceptance remains separate from technical completion; publication does not establish calibrated forecasting or authenticated authorship.

Railspike v0.3.0-beta.2

Railspike v0.3.0 beta 2

Extended effort estimates now default to enabled for new enrolled effort-study cycles. Each Step 1 option gets a complete scoped-cycle estimate; each planned stage gets a separate work estimate preserved through execution revisions and retrospective assessment.

Changes and compatibility

• No separate extension opt-in is needed for a new enrolled cycle. Study enrollment itself remains optional, and debug mode remains independent.
• Mode precedence is explicit user override, recorded cycle state, applicable host policy, then the enabled new-cycle default. Disable estimates for a cycle or set a host opt-out policy for future cycles.
• Existing settings survive upgrades. Older cycles with no mode field recover their earlier opt-in behavior; explicitly enable them prospectively if desired. Missing historical estimates remain missing.
• Frozen R1, independent cycle totals, append-only histories and existing approval/commit requirements are unchanged. Estimates remain provisional relative judgments, not hours, measured labor or additive forecasts.

Revision and evidence

Product commit: 14981be1a2b8944c481740cf683a96712e5c44f0 on non-default branch feature/extended-estimates-default.

Annotated tag: v0.3.0-beta.2; tag object: dda40fafe0824b52546693506272f5d2e764d33f. Unsigned: identifies the revision without cryptographic signer authentication.

Product/development Markdown links, Git-workflow fixture, whitespace/file-scope review, 13 static activation/history scenarios and exact-candidate installation/migration/rollback checks passed. See the verification record.

Evidence establishes document consistency and disposable fixture behavior, not live-agent compliance, forecast accuracy, stage-level calibration or measured labor. Runtime/UI/deployment checks are inapplicable.

Update and rollback

Ask your agent to update the installed Railspike from https://github.com/rlspk/railspike to tag v0.3.0-beta.2, verify commit 14981be1a2b8944c481740cf683a96712e5c44f0, preserve local edits and a recoverable prior state, and record source/tag/revision. Identify the installation method before choosing the update procedure; follow the host's normal staging/commit workflow. No host installation is automatically updated.

For new enrolled cycles, extended estimates now start enabled. Ask “Disable extended effort estimates for this cycle” to opt out, or “Enable extended effort estimates for this cycle” to activate an older disabled cycle prospectively. Roll back through the same reviewed update procedure to the previous installed tag, such as v0.3.0-beta.1, retaining host study histories.

This is a GitHub pre-release. Default installation remains main and stable Latest remains v0.1.0.

Stable exit criterion

Review real enrolled cycles demonstrating default-on option/stage estimates, explicit and host opt-outs, inherited state, legacy recovery, original retention through revisions and honest retrospective/missing-state handling. Retain the preceding beta's known-user ordinary-entry recovery criterion with appropriate user/environment evidence. Maintainer comfortable-fit/study acceptance remains separate from technical completion; publishing this beta does not establish validated forecasting.

Railspike v0.3.0-beta.1

Railspike v0.3.0 beta 1

This opt-in beta adds extended effort estimates for every Step 1 option and every stage in Steps 3 and 4. It also includes exact frozen-reference recovery improvements since v0.2.1-beta.1.

Changes

• Step 1: each option gets a complete scoped-cycle estimate, a complexity driver and material uncertainty. Combined approaches receive a fresh estimate; the recommended-cycle checkpoint remains separate.
• Step 3: each stage gets a separately labeled work estimate covering its changes, verification, documentation and ordinary correction. Shared work has an explicit owner; the whole-cycle total is judged independently rather than calculated by summing stages.
• Step 4: preserve original stage estimates, append material entire-stage revisions before dependent work where possible, and record retrospective assessments separately at completion. Keep blocked/skipped/split histories and honest missing values.
• Reference recovery: recover exact historical source bytes, verify recorded hashes and retain portable host-local copies/provenance. A changed current document does not replace a frozen reference.

Extended estimates are optional: enable them for an established effort-study cycle or once through a standing host policy. Study enrollment alone does not enable the extension. Mode inheritance is independent of debug mode. Existing approvals, branching, commit cadence and frozen R1 meanings remain unchanged. Estimates are provisional relative judgments, not hours, measured actual effort, percentages complete or additive delivery forecasts.

Revision and verification

Product commit: c336536f88d1ce471b4f582a7d87203864f8526e on non-default branch feature/detailed-effort-estimates.

Annotated tag: v0.3.0-beta.1; tag object: 01c4e306c8dcb50f0d1beb9a91f2c17e6d0e67c2. The tag is unsigned and identifies a revision without cryptographic signer authentication.

Product Markdown links, the existing Git-workflow fixture, candidate-range whitespace and the exact-candidate installation/migration fixture passed. Fifteen document scenario walkthroughs cover activation, option comparison, planned stages, revisions, completion and missing-history/reference recovery. See the verification record.

These checks establish document consistency and disposable fixture behavior, not live-agent compliance or predictive accuracy. Stage-level calibration, independent rating agreement and measured labor are not established. Application/runtime/UI and deployment checks are inapplicable to these instruction-only changes.

Opt in and rollback

Ask your agent to update the installed Railspike to tag v0.3.0-beta.1 from https://github.com/rlspk/railspike, verify commit c336536f88d1ce471b4f582a7d87203864f8526e, preserve local edits and a recoverable prior state, and record the source/tag/revision. Identify the installation method before choosing the update procedure; leave host staging/committing to its normal workflow.

After the study/reference is established, ask: “Enable extended effort estimates for this cycle,” or explicitly enable the extension through the host's standing policy. Updating alone does not enroll or enable it. No host installations are automatically updated by this release.

Rollback uses the same reviewed procedure with the prior installed tag, such as v0.2.1-beta.1. Preserve host study records and estimate histories. Default installation continues to use main; stable “Latest” remains v0.1.0.

Stable exit criterion

Review real opted-in cycles demonstrating every option/stage estimate, original-value retention through a discovery-driven revision, honest retrospective/missing-state handling, standing-mode inheritance and unchanged off-mode behavior without extra approval gates. Retain the earlier beta's known-user recovery criterion: demonstrate ordinary-entry recovery for the named user/environment with appropriate evidence. Maintainer comfortable-fit/study acceptance remains explicit and separate from technical completion; no validated forecast or measured-effort claim follows from publishing this beta.

Railspike v0.2.1-beta.1

Railspike v0.2.1 beta 1

Changes

• Adds optional relative effort estimation, provisional R1 reference examples, and checkpoints throughout planning and implementation.
• Supports continuing host studies with standing enrollment, stable cycle identities, preserved scope revisions, and separate retrospective assessments and maintainer acceptance.
• Clarifies agent-led upgrades for copied installations and legacy source/subtree migration, including preservation and recovery.
• Includes the previous beta's known-user recovery guidance.

Effort estimation remains opt-in and independent of debug mode. Existing approvals, branching and commit requirements remain in force. Study data stays in the consuming project; no automatic upload occurs. The Mermaid documentation policy remains a separate recommendation and is not included.

Revision and verification

Product commit: b6c399424f75dc2e94af496411467480487cc319 on non-default branch feature/effort-estimation-beta.

Annotated tag: v0.2.1-beta.1; tag object: 60a906a5c2481fa3579e5620f88a33771f79bc4e. The tag is unsigned; it provides no cryptographic signer authentication.

Rechecked for this release:

• Product Markdown local links: passed, 15 Markdown files.
• README Git-workflow fixture: passed.
• Product whitespace and clean working tree: passed.
• Repository-separation fixture: passed at the exact product candidate using a disposable local clone, with only the scratch branch renamed main. Covers clone/copy installation, actual-history submodule migration, old-source rejection, local-edit preservation, rollback and host isolation; 17 product files. Actual product main was not changed.
• Reviewed the product changes since v0.2.0-beta.1.

These checks establish document consistency and fixture behavior, not future agent compliance or predictive accuracy of effort scores. References are provisional retrospective judgments, not measured labor. Independent rating agreement, time conversion and forecast accuracy are not established. Application/runtime/UI tests are inapplicable to these instruction-only changes.

Opt in and rollback

Ask an agent to review and update the existing installation to tag v0.2.1-beta.1 from https://github.com/rlspk/railspike, verifying the product commit above, preserving local edits and a recoverable prior copy, and recording old/new provenance. Identify the installation type before choosing the update procedure; do not silently convert legacy subtree bookkeeping.

Rollback uses the same reviewed procedure with the previous installed tag or commit. Preserve host study records across rollback. Default installation continues to use main; stable Latest remains v0.1.0.

Stable exit criterion

Before stable promotion, review real enrolled cycles demonstrating retained initial/revised scores, honest missing checkpoints, scope/recovery handling and closeout evidence without repeated selection questions or altered approvals. Retain the prior beta's known-user recovery exit criterion: demonstrate ordinary-entry recovery for the named user/environment with appropriate evidence. Study acceptance remains explicit; calibration review does not end ongoing collection.

This supersedes the locally prepared, unpublished v0.2.0-beta.2 release designation at the user's request. Neither that tag nor a corresponding release was published.

Railspike v0.2.0-beta.1 (pre-release)

Railspike v0.2.0-beta.1 (pre-release)

A beta of Railspike's next minor version. It is opt-in: the default install and "Latest" stay at v0.1.0.

Product revision: 9774132db592c3bc9026163f50384f52376bac1c, based on the v0.1.0 revision 579c0c13956be36c308e50df60b1849f9e213da6.

What changed

• Step 2: when a request names a known user or environment, Step 2 states that user's ordinary entry point and recovery condition (the mismatch or failure, an unaided next action, how to verify or retry, and the evidence). Evidence from a different supported platform does not satisfy it.
• Step 3: a stage replays each reported failure as acceptance evidence. The after-checklist rejects an installer or other-platform pass; manual guidance can be the accepted outcome.
• Step 4: checks are reported as passed, failed, blocked, pending, or inapplicable, with reproduced baseline failures identified. A focused pass is never an unqualified full-suite or user-outcome result, and the handoff opens with anything unverified.
• Failure modes: a new section, "Passing tests did not establish the user's recovery".

Instruction text only: six files, +12 lines, one line modified. The four-step structure, approval gates, branch and commit requirements are unchanged, so this is a minor version under the policy.

Why a beta, and the evidence boundary

These changes came from reviewing recorded debug logs, mainly a case where installer tests passed on a supported platform while the known user's recovery stayed unusable. They were verified by replaying recorded cases against the new wording, not by running live agents, so their effect on agent behavior is unmeasured. The beta exists to get that evidence. Records (plans, replay cases, and verification) are in the railspike-dev repository under docs/plans/debug_log_process_improvements/.

Opt in

Ask your agent, from the project with the installed copy:

Review and update the Railspike copy at docs/railspike to tag v0.2.0-beta.1 of https://github.com/rlspk/railspike. Use its recorded source revision to identify local changes before replacing anything. Inspect the proposed snapshot, preserve local edits and a recoverable prior copy, verify the result, and report old/new revisions and project changes. Leave staging and committing to my normal project workflow.

Your agent follows the README's copied-installation update procedure. Local edits to files the beta changes are reported for you to resolve and are not overwritten.

Roll back

Make the same request with tag v0.1.0. The recorded revision in RAILSPIKE_SOURCE.md shows which version is installed.

Exit criterion

The beta is promoted to v0.2.0 after at least one real planning cycle on an opted-in project, with debug mode on and its log reviewed, shows no unnecessary gates on work that names no user or environment and no missed recovery condition when one is named. Promotion merges this same commit to main. Corrections ship as v0.2.0-beta.2; a published tag is never moved.

Verification

On 2026-10-15, with the product at the revision above:

• product Markdown links (14 files), the Git workflow fixture, and whitespace checks passed;
• the repository-separation fixture passed against the candidate revision (legacy baseline b59f7df89842ba17f710ae1f2dc955bb361cc620; 16 product files);
• in a disposable project, an update from v0.1.0 to this revision preserved a local edit, recorded the new revision, and rolled back cleanly to v0.1.0; a local edit to a file this release changes was detected as requiring resolution.

The upgrade test followed the README procedure with a local clone standing in for GitHub and was run by the maintainer's own agent, not an independent one. Treat the first real opt-in as the live test.

The release tag is unsigned and annotated: it identifies a revision but does not authenticate a signer. Railspike provides instructions, not technical enforcement of agent behavior or a safety guarantee.