diff --git a/memory-bank/features/FT-013/README.md b/memory-bank/features/FT-013/README.md index 5338b90..3494439 100644 --- a/memory-bank/features/FT-013/README.md +++ b/memory-bank/features/FT-013/README.md @@ -2,9 +2,9 @@ title: "FT-013: Self-update from latest GitHub release" doc_kind: feature doc_function: index -purpose: "Bootstrap-safe navigation for the FT-013 feature package. Read feature.md first, then solution.md, decision-log.md, and implementation-plan.md." +purpose: "Navigation for the FT-013 feature package, which owns the reconciled issue #35/#13 self-update slice. Read brief.md, design.md, decision-log.md, and implementation-plan.md in that order." derived_from: - - feature.md + - brief.md status: active audience: humans_and_agents --- @@ -13,18 +13,26 @@ audience: humans_and_agents ## About -This feature package tracks issue #13: adding a first-class self-update workflow for `start-issue` that upgrades the running installation from the latest published GitHub release. +This feature package tracks issue #35 and reconciles it with the already +delivered issue #13 contract. It is the single feature owner for self-update. ## Annotated Index -- [feature.md](feature.md) - Read for the canonical problem statement, scope, constraints, acceptance scenarios, and verification contract. +- [brief.md](brief.md) + Canonical problem statement, scope, constraints, acceptance scenarios, and verification contract. -- [solution.md](solution.md) - Read for the selected update architecture, command-entry equivalence, and operational failure handling. +- [design.md](design.md) + Canonical selected design, contracts, invariants, and failure handling. - [decision-log.md](decision-log.md) Read for feature-local decisions that close issue ambiguities and document conflict resolution. - [implementation-plan.md](implementation-plan.md) Read for execution order, touchpoints, risks, and planned verification. + +- [feature.md](feature.md) and [solution.md](solution.md) + Archived legacy redirects retained for migration traceability; they are not + active requirement or design owners. + +- [feature-review-report.md](feature-review-report.md) + Final review-improve cycle report and verification note. diff --git a/memory-bank/features/FT-013/brief.md b/memory-bank/features/FT-013/brief.md new file mode 100644 index 0000000..fe1494c --- /dev/null +++ b/memory-bank/features/FT-013/brief.md @@ -0,0 +1,111 @@ +--- +title: "FT-013: Self-update command for installed CLI" +doc_kind: feature +doc_function: canonical +purpose: "Canonical problem-space and verification contract for issue #35, reconciled with the already delivered issue #13 slice." +derived_from: + - https://github.com/dapi/start-issue/issues/35 + - https://github.com/dapi/start-issue/issues/13 + - ../../flows/feature-flow.md + - ../../product/context.md + - ../../engineering/testing-policy.md + - ../../../README.md + - ../../../README.ru.md + - ../../../doc/spec.md +status: active +delivery_status: done +audience: humans_and_agents +must_not_define: + - selected_design + - implementation_sequence +--- + +# FT-013: Self-update command for installed CLI + +## What + +### Problem + +An installed `start-issue` binary needs a release-backed way to update itself +without requiring a source checkout. Issue #35 restates the self-update slice +originally tracked by issue #13; the existing FT-013 package is therefore the +single feature owner. + +### Outcome + +Users can run `start-issue update` or `start-issue --update` to compare the +running installation with the latest `dapi/start-issue` GitHub Release and +upgrade that installation when a newer compatible release exists. + +## Scope + +- `REQ-01` Support `start-issue update` and `start-issue --update` as equivalent entry points. +- `REQ-02` Resolve the latest published release for `dapi/start-issue` through GitHub Release metadata. +- `REQ-03` Use the executable resolved for the current invocation as the update target and version source. +- `REQ-04` Treat an equal or newer installed version as a successful no-op without downgrading. +- `REQ-05` For an available update, download the current-platform binary and checksum manifest, verify both, and install with executable permissions. +- `REQ-06` Fail with actionable errors for missing access/tooling, release lookup, missing assets, download, checksum, staged-version, or installation failures. +- `REQ-07` Work outside a git repository and leave the ordinary issue-start workflow unchanged. +- `REQ-08` Document both entry points, update states, prerequisites, and failure behavior in the public README/spec surfaces. + +## Non-Scope + +- `NS-01` No automatic update during ordinary issue-start commands. +- `NS-02` No arbitrary release selection or downgrade command. +- `NS-03` No package-manager integration and no change to local-source `make install` semantics. +- `NS-04` No second feature package for issue #35; issue #35 is reconciled to FT-013. + +## Constraints / Assumptions + +- `CON-01` The release source and repository are `dapi/start-issue`, unless the existing documented repository override is intentionally used for tests or compatible deployments. +- `CON-02` The update path must not require repository, worktree, issue, or agent context. +- `CON-03` Installation must be staged and verified before replacement so a failed update does not replace the existing executable. +- `CON-04` Platform-specific release assets and `checksums.txt` are the current release contract documented by the repository. + +## Design Requirement Decision + +| Decision | Reason | Downstream owner | +| --- | --- | --- | +| `Design required: yes` | The feature changes CLI mode parsing, external GitHub Release interaction, executable replacement, checksum verification, and failure handling. | `design.md` | + +## Verify + +### Exit Criteria + +- `EC-01` Both command forms enter the same update workflow. +- `EC-02` Current, newer, and update-available versions produce the specified no-op or update result. +- `EC-03` A successful update replaces only the invoked executable after checksum and staged-version verification, preserving executable permissions. +- `EC-04` Lookup, download, checksum, staged-version, permission, and unsupported-platform failures are actionable and non-zero where applicable. +- `EC-05` The workflow works outside git and existing issue-start behavior remains covered. +- `EC-06` README/spec documentation matches the implemented Go CLI contract. + +### Acceptance Scenarios + +- `SC-01` Older installed binary + `update` installs the latest current-platform release. +- `SC-02` Older installed binary + `--update` has the same result as `update`. +- `SC-03` Equal versions exit `0` and do not download or replace the executable. +- `SC-04` Installed version newer than latest exits `0` and does not downgrade. +- `SC-05` Lookup, asset, checksum, staged-version, or install failure exits with an actionable error and leaves the old executable intact. +- `SC-06` Update from outside a git repository does not invoke repo/worktree discovery. +- `SC-07` Existing issue-start invocation remains behaviorally compatible. + +### Checks and Evidence + +| Check ID | Covers | Procedure | Evidence | +| --- | --- | --- | --- | +| `CHK-01` | `REQ-01`–`REQ-07`, `SC-01`–`SC-07` | `go test ./...` | `EVID-01` | +| `CHK-02` | `REQ-08`, `EC-06` | `make test` and `git diff --check` | `EVID-02` | + +`EVID-01` is focused Go/parity test output covering release lookup, version +ordering, checksum/staged verification, executable replacement, no-op paths, +failure paths, and outside-git execution. `EVID-02` is repository-level check +output and documentation/index validation. + +### Traceability Matrix + +| Requirement | Acceptance | Checks | +| --- | --- | --- | +| `REQ-01` | `SC-01`, `SC-02` | `CHK-01` | +| `REQ-02`–`REQ-06` | `SC-01`–`SC-06` | `CHK-01` | +| `REQ-07` | `SC-06`, `SC-07` | `CHK-01` | +| `REQ-08` | `EC-06` | `CHK-02` | diff --git a/memory-bank/features/FT-013/decision-log.md b/memory-bank/features/FT-013/decision-log.md index 1f4b1f7..a06b44d 100644 --- a/memory-bank/features/FT-013/decision-log.md +++ b/memory-bank/features/FT-013/decision-log.md @@ -2,11 +2,11 @@ title: "FT-013: Decision Log" doc_kind: feature doc_function: decision_log -purpose: "Feature-local decisions for FT-013. Records how issue ambiguities and document conflicts were resolved." +purpose: "Feature-local decisions and conflict resolutions for the issue #35/#13 self-update slice." derived_from: - - feature.md - - solution.md - - ../../../install.sh + - brief.md + - design.md + - ../../../cmd/start-issue/main.go - ../../../README.md - ../../../doc/spec.md status: active @@ -17,115 +17,80 @@ audience: humans_and_agents ## Decisions -### `DL-01` Release-backed installer contract is the update baseline +### `DL-01` Issue #35 is reconciled to FT-013 -- Date: 2026-05-24 +- Date: 2026-08-04 - Status: accepted -- Context: - Issue #13 requires the update source to be the latest GitHub Release rather than the local checkout. - The current repository already documents and implements a release-backed install path in `README.md`, `README.ru.md`, and `install.sh`. -- Decision: - The self-update workflow reuses the same release-backed contract as `install.sh`: release asset plus checksum, verification before install, and installation into the project's standard binary target shape. -- Evidence: - `install.sh` downloads `releases/latest/download/start-issue` and `start-issue.sha256`, verifies the checksum, and installs with mode `0755`. - `README.md` documents that install path as the primary "latest release" installation flow. -- Consequence: - Update behavior stays consistent with the documented installation story and avoids inventing a second release-install mechanism. - -### `DL-02` The running executable path is the safe default update target - -- Date: 2026-05-24 +- Context: Issue #35 requests a release-backed self-update command for the installed CLI. The feature inventory identifies it as a duplicate of the existing issue #13 self-update slice. +- Decision: FT-013 remains the single feature package; issue #35 is added as provenance and no second package is created. +- Evidence: GitHub issue #35, `memory-bank/features/missing.md`, and the existing FT-013 package. +- Consequence: Scope, design, plan, and verification have one canonical owner. + +### `DL-02` Current Go runtime is the implementation baseline + +- Date: 2026-08-04 +- Status: accepted +- Context: Legacy FT-013 documents referenced `scripts/start-issue` and Bash tests, but the current repository entrypoint is `cmd/start-issue/main.go` and the current test surfaces are Go and parity tests. +- Decision: Active feature documents use the current Go implementation and tests as grounding; legacy `feature.md` and `solution.md` are archived redirects. +- Evidence: `cmd/start-issue/main.go`, `cmd/start-issue/main_test.go`, `cmd/start-issue/parity_integration_test.go`, `Makefile`. +- Consequence: Plan steps and evidence no longer claim unstarted Bash work. + +### `DL-03` Release metadata and platform assets are the update contract + +- Date: 2026-08-04 - Status: accepted -- Context: - Issue #13 explicitly notes that multiple `start-issue` executables may exist in `PATH` and says the safest default is to update the resolved executable path for the current invocation. -- Decision: - The update workflow detects the executable path of the running `start-issue` process and updates that path rather than guessing a different installation target. -- Evidence: - The issue's design notes define this as the safest default. - This matches the feature requirement to detect the currently installed version from the executable the user is running. -- Consequence: - The command updates the installation the user actually invoked and avoids silently modifying another `PATH` entry. - -### `DL-03` Update mode must not depend on git repository state - -- Date: 2026-05-24 +- Context: Issue #35 requires the latest GitHub Release, a binary, and SHA-256 verification. The current Go CLI resolves release metadata with `gh`, selects the current-platform asset, and downloads `checksums.txt`. +- Decision: Use `gh api repos//releases/latest`, the current-platform binary asset, and `checksums.txt`; keep the documented repository override available. +- Evidence: `updateMode`, `githubRelease.assetURLs`, `releaseAssetName`, `validChecksum`, README self-update section, and `doc/spec.md`. +- Consequence: Verification covers both metadata resolution and asset integrity without reintroducing the legacy shell installer as a runtime dependency. + +### `DL-04` The running executable is the update target + +- Date: 2026-08-04 - Status: accepted -- Context: - Issue #13 requires the command to work outside a git repository. - The normal issue-starting workflow currently depends on git repo discovery, remote detection, and worktree planning. -- Decision: - Update mode is treated as a separate top-level workflow that bypasses issue parsing, repo detection, base-branch detection, and worktree orchestration. -- Evidence: - The issue says the update command should work outside a git repository. - Current `doc/spec.md` shows the ordinary workflow requires git repository context for issue starts. -- Consequence: - Update mode can run from any directory and does not create accidental coupling to the issue-starting path. - -### `DL-04` Version comparison uses normalized tags, not raw surface strings - -- Date: 2026-05-24 +- Context: Issue #35 requires updating the executable invoked by the user. Multiple installations may exist, and the current implementation resolves `os.Executable()` then evaluates symlinks. +- Decision: Update the resolved executable path for the current process; never guess another PATH entry or silently fall back to the default install path. +- Evidence: `runningExecutablePath`, `SD-01`, and issue #35 user experience/acceptance text. +- Consequence: The command updates the installation actually invoked. + +### `DL-05` Update is upgrade-only + +- Date: 2026-08-04 - Status: accepted -- Context: - The current CLI exposes a bare numeric version such as `1.12.0` in `scripts/start-issue`. - Issue #13 refers to GitHub release names with a `v` prefix such as `v1.11.1`. - Raw string comparison would therefore misclassify equivalent versions. -- Decision: - The update workflow compares normalized version strings by stripping one optional leading `v` from both the installed version and the latest release tag before equality and ordering checks. -- Evidence: - `scripts/start-issue` currently defines `VERSION=\"1.12.0\"`. - Issue #13 states the latest published release is `v1.11.1`. -- Consequence: - The no-op path reflects semantic version equality rather than formatting differences, and tests must cover the normalization rule. - -### `DL-05` Release lookup and asset download are separate contracts - -- Date: 2026-05-24 +- Context: The requirement says current or newer installations must exit successfully without downloading; unconditional “latest release” replacement could downgrade a newer binary. +- Decision: Compare semantic versions; equal or newer is a successful no-op. +- Evidence: `compareVersions`, `updateMode`, `SC-03`, and `SC-04`. +- Consequence: Self-update never replaces a newer installed version. + +### `DL-06` Replacement requires checksum and staged-version verification + +- Date: 2026-08-04 - Status: accepted -- Context: - Issue #13 requires the command to resolve the latest published release from GitHub Releases and also to install the release artifact. - `install.sh` already defines how assets and checksum files are downloaded, but it does not need to compare versions first. -- Decision: - FT-013 separates release metadata lookup from asset download: - lookup resolves the canonical latest release tag and asset/checksum URLs; - installer helpers then download, verify, and install those resolved assets. -- Evidence: - The issue requires both latest-release resolution and version comparison. - `install.sh` already provides the download and verification contract for the release asset and checksum. -- Consequence: - The design keeps one source of truth for "what is latest" and a separate source of truth for "how to install it," reducing drift and simplifying tests. - -### `DL-06` Self-update must not downgrade a newer local executable - -- Date: 2026-05-24 +- Context: A checksum verifies bytes, while a release asset can still be mislabeled or incompatible. Replacement must not destroy the working binary on a failed update. +- Decision: Download to memory, verify `checksums.txt`, stage beside the target with executable mode, verify staged `--version` against the release tag, then rename atomically. +- Evidence: `validChecksum`, `stageBinary`, `verifyStagedBinary`, `installVerifiedUpdate`, and focused tests. +- Consequence: checksum, version, permission, or rename failures leave the existing target untouched. + +### `DL-07` Update mode is independent of repository context + +- Date: 2026-08-04 - Status: accepted -- Context: - The repository currently contains `VERSION="1.12.0"` in `scripts/start-issue`. - Issue #13 states that on 2026-05-24 the latest published release is `v1.11.1`. - A self-update command that blindly installed "latest published release" would therefore downgrade a newer local executable. -- Decision: - If the running executable version is newer than the latest published GitHub release, the update workflow exits successfully with a no-op status and leaves the executable unchanged. -- Evidence: - `scripts/start-issue` currently exposes version `1.12.0`. - Issue #13 states that the latest published release is `v1.11.1`. -- Consequence: - Self-update remains an upgrade-only workflow and does not clobber a newer local or pre-release installation. +- Context: Issue #35 explicitly requires operation outside a git repository; ordinary issue-starting flow has separate repository/worktree prerequisites. +- Decision: Dispatch update mode before ordinary repo/worktree orchestration and require only the update-specific external boundary. +- Evidence: `main`, `runMode`, `updateMode`, `SC-06`, and `TestRunModeUpdateDoesNotRequireHomeDirectory`. +- Consequence: update can run outside git while ordinary issue-start behavior remains isolated. ## Conflict Resolution -- Resolved conflict: "standard install location used by the project" versus "update the resolved executable path for the current invocation." - Conflicting sources: - issue #13 requirements emphasize the standard install location; - issue #13 design notes emphasize the running executable path as the safest default when multiple installations exist. - Resolution: - interpret the release-backed installer contract as the standard install behavior and the running executable path as the concrete target for self-update. - Why this is consistent: - it preserves the existing installation method while making the self-update target explicit and safe. - -- Resolved conflict: bare CLI version strings versus `v`-prefixed release tags. - Conflicting sources: - `scripts/start-issue` exposes a bare numeric `VERSION`; - issue #13 and GitHub Releases use `v`-prefixed release tags. - Resolution: - compare normalized versions rather than raw strings. - Why this is consistent: - it preserves the current CLI output surface while matching the release system's tagging convention. +### Legacy FT-013 documents vs current Go implementation + +The archived `feature.md` / `solution.md` described Bash paths and issue #13 +only. They conflicted with the current Go change surface and issue #35 +provenance. `DL-02` resolves this by making `brief.md` and `design.md` active +owners and retaining the old files only as migration redirects. + +### Generic checksum wording vs current release manifest + +Issue #35 says “its SHA-256 checksum”; the repository's current release contract +uses a platform binary plus `checksums.txt`. `DL-03` makes that existing +contract explicit without changing issue scope. diff --git a/memory-bank/features/FT-013/design.md b/memory-bank/features/FT-013/design.md new file mode 100644 index 0000000..10df166 --- /dev/null +++ b/memory-bank/features/FT-013/design.md @@ -0,0 +1,88 @@ +--- +title: "FT-013: Design" +doc_kind: feature +doc_function: canonical +purpose: "Canonical solution-space contract for the release-backed self-update command." +derived_from: + - brief.md + - decision-log.md + - ../../../cmd/start-issue/main.go + - ../../../cmd/start-issue/main_test.go +status: active +audience: humans_and_agents +must_not_define: + - ft_013_scope + - ft_013_acceptance_criteria + - implementation_sequence +--- + +# FT-013: Design + +## C4 Applicability + +| C4 ID | Decision | Reason | Artifact | +| --- | --- | --- | --- | +| `C4-01` | `C1` | The CLI introduces a user-to-CLI interaction with GitHub Release metadata and release assets across a trust boundary. | This design's flow and contracts | + +### `C4-01` System Context Artifact + +| Element | Direction / boundary | Responsibility | +| --- | --- | --- | +| Developer | invokes `start-issue update` or `--update` | Starts an explicit update and observes status/errors | +| `start-issue` CLI | outbound authenticated `gh` call and HTTPS asset download | Resolves, compares, verifies, and installs the release | +| GitHub Releases / `gh` | release metadata and asset bytes enter the CLI trust boundary | Supplies latest tag, platform binary, and checksum manifest | +| Invoked executable path | local filesystem write after staged verification | Receives only the verified replacement binary | + +## Selected Solution + +- `SOL-01` Normalize `update` and `--update` in the existing Go parser and dispatch them to one top-level update mode. +- `SOL-02` Resolve the latest release through `gh api repos//releases/latest`; use the current-platform binary asset and `checksums.txt`. +- `SOL-03` Compare the running version with the release tag using semantic ordering, including optional `v` normalization and source-build suffix handling. +- `SOL-04` Resolve `os.Executable()`, follow symlinks, stage the downloaded binary beside the target, verify its `--version`, then atomically rename it into place with mode `0755`. +- `SOL-05` Keep update mode before repository/worktree orchestration; Windows follows the documented manual path. + +## Alternatives Considered + +| Alternative | Why not selected | +| --- | --- | +| `ALT-01` Invoke `install.sh` from the CLI | It creates a second process contract and cannot own the running executable path as precisely as the Go implementation. | +| `ALT-02` Update the default `~/.local/bin/start-issue` path | It can modify a different installation when multiple binaries or symlinks exist. | +| `ALT-03` Download without staged verification | A checksum alone does not prove the downloaded binary reports the requested release tag. | + +## Accepted Local Decisions + +- `SD-01` The resolved running executable is the concrete update target; symlinks are evaluated before replacement. +- `SD-02` Equal or newer versions are successful no-ops, so self-update never downgrades. +- `SD-03` `gh` is the external release/auth boundary; release data and binary downloads remain separately testable. + +## Contracts + +| Contract | Input / Output | Semantics | +| --- | --- | --- | +| `CTR-01` | CLI args → update mode | `update` and `--update` are equivalent and mutually exclusive with issue input. | +| `CTR-02` | repository + platform → release tag and asset URLs | Latest release metadata must contain the platform binary and `checksums.txt`. | +| `CTR-03` | installed version + release tag → compare decision | Equal/newer means exit `0` without download or replacement; older means update. | +| `CTR-04` | verified binary + target path → replaced executable | Stage, verify `--version`, preserve executable mode, then rename; failures leave the target untouched. | + +## Invariants + +- `INV-01` Update mode does not require git repository discovery or issue context. +- `INV-02` A checksum or staged-version failure cannot replace the target executable. +- `INV-03` The ordinary issue-start path is not routed through update mode. + +## Failure Modes + +- `FM-01` Missing `gh` or authentication prevents release lookup with remediation in the error. +- `FM-02` Missing platform asset/checksum or failed download stops before replacement. +- `FM-03` Checksum or staged-version mismatch leaves the existing executable intact. +- `FM-04` Permission or rename failure is returned rather than falling back to another installation. + +## Traceability + +| Requirement | Solution | Contract / invariant | Failure | +| --- | --- | --- | --- | +| `REQ-01` | `SOL-01` | `CTR-01` | `INV-03` | +| `REQ-02`–`REQ-04` | `SOL-02`, `SOL-03` | `CTR-02`, `CTR-03` | `FM-01`, `FM-02` | +| `REQ-05`–`REQ-06` | `SOL-04` | `CTR-04`, `INV-02` | `FM-02`–`FM-04` | +| `REQ-07` | `SOL-05` | `INV-01`, `INV-03` | `FM-01` | +| `REQ-08` | existing public docs/spec | `CTR-01`–`CTR-04` | `FM-*` | diff --git a/memory-bank/features/FT-013/feature-review-report.md b/memory-bank/features/FT-013/feature-review-report.md new file mode 100644 index 0000000..e96a802 --- /dev/null +++ b/memory-bank/features/FT-013/feature-review-report.md @@ -0,0 +1,70 @@ +--- +title: "FT-013: Feature Pack Review Report" +doc_kind: feature-support +doc_function: report +purpose: "Final report for the issue #35 feature-pack review-improve cycles." +derived_from: + - brief.md + - design.md + - decision-log.md + - implementation-plan.md +status: active +audience: humans_and_agents +--- + +# FT-013 review-improve report + +## Final status + +`done` — document and runtime review stopped early after cycle 3 because no +`critical` or `important` findings remained. No human gate was required. + +## Cycle 1 + +- Review: Issue #35 was not provenance of the existing FT-013 package, and the + active package described the legacy Bash implementation rather than the + current Go runtime. +- Critical: none. +- Important: duplicate issue/package ownership; stale active problem/design + references and change surface. +- FPF closure: bounded the delivery unit to one FT-013 owner using the issue + inventory and issue acceptance; selected current Go paths as the evidence + boundary using repository grounding. +- Changes: added `brief.md` and `design.md`, reconciled `missing.md`, updated + navigation, rewrote the plan and decision log, and archived legacy owners. +- Human gate: no. + +## Cycle 2 + +- Review: The first revision had a broken `derived_from` path, unindexed legacy + redirects, a nonexistent `DL-08` reference, and no explicit C1 artifact. +- Critical: none. +- Important: feature-flow navigation/C4 traceability defects. +- FPF closure: treated feature-flow as the governing boundary contract and + used the current release flow to make the C1 actor/system/data boundary + explicit. +- Changes: fixed paths and IDs, indexed archived redirects, added the C1 + system-context artifact, and reduced legacy files to redirects. +- Human gate: no. + +## Cycle 3 + +- Review: Feature-flow audit passed; active owners, required identifiers, + traceability, decision log, and navigation are coherent. +- Critical: none. +- Important: none. +- Changes: none; cycle stopped early by rule. +- Human gate: no. + +## Verification + +- `python3 scripts/check_memory_bank_index.py --max-depth 4`: passed. +- `git diff --check`: passed. +- `make test`: passed on 2026-08-04, including `go vet ./...`, `go test ./...`, + the memory-bank link audit, and `git diff --check`. + +## Remaining observations + +No critical or important document or runtime findings remain. The existing Go +implementation satisfies issue #35, local verification gates pass, and the +feature lifecycle is closed as `done` with its implementation plan archived. diff --git a/memory-bank/features/FT-013/feature.md b/memory-bank/features/FT-013/feature.md index 65ee495..fcd96ad 100644 --- a/memory-bank/features/FT-013/feature.md +++ b/memory-bank/features/FT-013/feature.md @@ -1,117 +1,15 @@ --- -title: "FT-013: Self-update from latest GitHub release" +title: "FT-013: Legacy feature redirect" doc_kind: feature -doc_function: canonical -purpose: "Canonical feature document for adding a release-backed self-update workflow to start-issue. Owns only the problem space and verification contract." +doc_function: legacy +purpose: "Archived migration redirect to the canonical FT-013 brief." derived_from: - - https://github.com/dapi/start-issue/issues/13 - - ../../../README.md - - ../../../README.ru.md - - ../../../doc/spec.md - - ../../../install.sh -status: active -delivery_status: in_progress + - brief.md +status: archived audience: humans_and_agents -must_not_define: - - selected_design - - implementation_sequence --- -# FT-013: Self-update from latest GitHub release +# Legacy redirect -## What - -### Problem - -`start-issue` can currently be installed from the latest GitHub Release through `install.sh` or the documented manual download flow, but the CLI has no built-in way to upgrade an existing installation to the latest published release. Users must detect new releases and reinstall on their own. - -As of 2026-05-24, issue #13 states that the latest published release is `v1.11.1` published on 2026-05-18, and the new workflow must resolve updates from GitHub Releases rather than from the local checkout state. - -### Outcome - -`start-issue` exposes a first-class self-update workflow through both `start-issue update` and `start-issue --update`, compares the running installation against the latest published GitHub release, installs an update when needed, and reports the result clearly. - -### Scope - -- `REQ-01` Support both `start-issue update` and `start-issue --update` as equivalent entry points. -- `REQ-02` Resolve the latest published release from GitHub Releases for `dapi/start-issue`, not from the local checkout state. -- `REQ-03` Detect the currently installed version from the executable path of the running `start-issue` invocation. -- `REQ-04` If the installed version already matches the latest release, exit successfully with a clear "already up to date" message. -- `REQ-05` If a newer release exists, download and install that release using the project's release-backed installation contract while preserving executable permissions. -- `REQ-06` Fail with a clear error message when release lookup, download, checksum verification, or installation fails. -- `REQ-07` Keep the existing `start-issue ISSUE` workflow unchanged. -- `REQ-08` Document the new update workflow in `README.md`, `README.ru.md`, and `doc/spec.md`, including both command-entry forms and expected output states. - -### Non-Scope - -- `NS-01` Do not add auto-update on ordinary issue-starting commands. -- `NS-02` Do not change how `make install` builds from the local checkout. -- `NS-03` Do not add support for selecting arbitrary target releases; this issue covers only updating to the latest published release. -- `NS-04` Do not broaden the feature into a package-manager integration beyond the project's existing release-backed install path. - -### Constraints - -- `CON-01` The update source must be a published GitHub Release asset or release-backed installer path. -- `CON-02` The update workflow must work outside a git repository. -- `CON-03` Multiple `start-issue` executables may exist in `PATH`; the feature must define a safe default target without guessing about other installations. -- `CON-04` The normal `start-issue ISSUE` path must remain behaviorally unchanged. - -## Verify - -### Exit Criteria - -- `EC-01` `start-issue update` and `start-issue --update` both enter the same update workflow. -- `EC-02` The workflow compares the running executable version against the latest GitHub Release and either reports "already up to date" or installs the newer release. -- `EC-03` The workflow updates the intended local executable path, preserves executable permissions, and fails clearly on lookup, download, checksum, or install failures. -- `EC-04` Documentation and spec describe the new command forms, install/update behavior, and output states without contradicting the implementation. -- `EC-05` Existing issue-starting behavior remains intact and automated coverage passes. - -### Acceptance Scenarios - -- `SC-01` Given `start-issue` is installed at an older version, when the user runs `start-issue update`, then the command installs the latest GitHub release and `start-issue --version` reports that release version. -- `SC-02` Given `start-issue` is installed at an older version, when the user runs `start-issue --update`, then the command performs the same update behavior as the subcommand form. -- `SC-03` Given the installed version already matches the latest release, when the user runs either update form, then the command exits `0` and reports that no update was necessary. -- `SC-04` Given release lookup, download, checksum verification, or installation fails, when the user runs either update form, then the command exits non-zero with an actionable error message. -- `SC-05` Given the user runs `start-issue 123`, then the existing issue workflow behaves exactly as before. -- `SC-06` Given the user runs an update command outside a git repository, then the command still resolves the running executable path and performs update checks without repo discovery. -- `SC-07` Given the installed version and the latest release tag differ only by an optional leading `v`, when the user runs either update form, then the command treats them as the same version and exits successfully without reinstalling. -- `SC-08` Given the installed version is newer than the latest published GitHub release, when the user runs either update form, then the command exits `0`, reports that no update is needed, and does not downgrade the executable. - -### Traceability Matrix - -| Requirement ID | Acceptance refs | Checks | Evidence IDs | -| --- | --- | --- | --- | -| `REQ-01` | `EC-01`, `SC-01`, `SC-02` | `CHK-01`, `CHK-02` | `EVID-01` | -| `REQ-02` | `EC-02`, `SC-01`, `SC-02`, `SC-03`, `SC-04`, `SC-07`, `SC-08` | `CHK-01`, `CHK-02` | `EVID-01` | -| `REQ-03` | `EC-02`, `EC-03`, `SC-01`, `SC-03`, `SC-06`, `SC-07`, `SC-08` | `CHK-01`, `CHK-02` | `EVID-01` | -| `REQ-04` | `EC-02`, `SC-03`, `SC-07`, `SC-08` | `CHK-02` | `EVID-01` | -| `REQ-05` | `EC-02`, `EC-03`, `SC-01`, `SC-02` | `CHK-01`, `CHK-02` | `EVID-01` | -| `REQ-06` | `EC-03`, `SC-04` | `CHK-01`, `CHK-02` | `EVID-01` | -| `REQ-07` | `EC-05`, `SC-05` | `CHK-02` | `EVID-01` | -| `REQ-08` | `EC-04` | `CHK-03` | `EVID-01` | - -### Checks - -| Check ID | Covers | How to check | Expected | -| --- | --- | --- | --- | -| `CHK-01` | `EC-01`, `EC-02`, `EC-03` | `bash -n scripts/start-issue && shellcheck install.sh scripts/start-issue scripts/lib/start_issue/*.sh` | CLI parsing, update helpers, and installer-related code remain syntactically valid and shellcheck-clean. | -| `CHK-02` | `EC-01`, `EC-02`, `EC-03`, `EC-05`, `SC-01` - `SC-08` | `mise exec -- bats test` | Automated coverage proves both update entry points, version normalization, no-downgrade behavior, success/no-op/failure paths, outside-git support, and unchanged issue workflow. | -| `CHK-03` | `EC-04` | `git diff --check` | Documentation/spec edits are internally consistent and whitespace-clean. | - -### Test Matrix - -| Check ID | Evidence IDs | Evidence path | -| --- | --- | --- | -| `CHK-01` | `EVID-01` | Local terminal output from syntax and shellcheck runs. | -| `CHK-02` | `EVID-01` | Local terminal output from Bats runs and CI output after branch update. | -| `CHK-03` | `EVID-01` | Local terminal output from `git diff --check`. | - -### Evidence - -- `EVID-01` Verification command output showing update workflow coverage, version normalization, no-downgrade and no-op behavior, failure handling, and unchanged existing workflow. - -### Evidence Contract - -| Evidence ID | Artifact | Producer | Path contract | Reused by checks | -| --- | --- | --- | --- | --- | -| `EVID-01` | Local and CI command output | implementer / CI | Terminal output and GitHub Actions job | `CHK-01`, `CHK-02`, `CHK-03` | +The active problem-space owner is [brief.md](brief.md). This file is retained +only so links from the pre-feature-flow package remain recoverable. diff --git a/memory-bank/features/FT-013/implementation-plan.md b/memory-bank/features/FT-013/implementation-plan.md index 4c7fb22..4ea8f8c 100644 --- a/memory-bank/features/FT-013/implementation-plan.md +++ b/memory-bank/features/FT-013/implementation-plan.md @@ -2,142 +2,111 @@ title: "FT-013: Implementation Plan" doc_kind: feature doc_function: derived -purpose: "Execution plan for FT-013. Tracks discovery context, implementation steps, risks, and verification strategy without redefining canonical feature or solution facts." +purpose: "Execution and verification plan for the reconciled issue #35 self-update slice." derived_from: - - feature.md - - solution.md + - brief.md + - design.md - decision-log.md -status: active + - ../../engineering/testing-policy.md +status: archived audience: humans_and_agents must_not_define: - ft_013_scope - ft_013_selected_design - ft_013_acceptance_criteria - - ft_013_blocker_state --- # FT-013: Implementation Plan -## Current Goal - -Add a self-update workflow to `start-issue` that upgrades the running installation from the latest published GitHub release without changing the existing issue-starting workflow. - ## Grounding / Support References -| Document | Role in this plan | Facts reused | Conflict action | -| --- | --- | --- | --- | -| `feature.md` | canonical problem / verify owner | `REQ-*`, `SC-*`, `CHK-*`, `EVID-01` | Update `feature.md` first | -| `solution.md` | canonical solution owner | `SOL-*`, `CTR-*`, `FM-*`, `RB-*`, `SD-*` | Update `solution.md` first | -| `decision-log.md` | ambiguity and conflict owner | `DL-*` | Update `decision-log.md` first | -| `../../../install.sh` | release-backed install contract | asset URLs, checksum verification, install mode | Update only if contract changes intentionally | -| `../../../README.md`, `../../../README.ru.md` | public install and CLI docs | install path, current CLI docs | Update if user-facing behavior changes | -| `../../../doc/spec.md` | canonical script spec | workflow requirements, CLI flags, algorithm details | Update if implementation or workflow contract changes | +| Path | Current role | Relevance | +| --- | --- | --- | +| `cmd/start-issue/main.go` | Go CLI, parser, update workflow, release/install helpers | Current implementation and change surface | +| `cmd/start-issue/main_test.go` | Focused unit/integration tests | Version, release, failure, staging, and update behavior | +| `cmd/start-issue/parity_integration_test.go` | Bash-v1/Go parity and installer checks | Regression and release-contract evidence | +| `README.md`, `README.ru.md`, `doc/spec.md` | Public CLI/spec contract | User-facing update entry points and prerequisites | +| `Makefile`, `.github/workflows/*` | Local/CI verification | Required repository gates | -## Current State / Reference Points +## Test Strategy -| Path / module | Current role | Why relevant | Reuse / mirror | +| Surface | Canonical refs | Automated coverage | Required verification | | --- | --- | --- | --- | -| `scripts/start-issue` | CLI entrypoint with version constant and module bootstrap. | Update mode starts at CLI parsing and version reporting. | Preserve ordinary entry behavior while adding update mode. | -| `scripts/lib/start_issue/cli.sh` | Parses flags and positional arguments. | Must normalize `update` and `--update` without breaking issue input parsing. | Extend, do not fork parsing logic. | -| `scripts/lib/start_issue/output.sh` | Renders help and user-facing status. | Must document the new mode and its output states. | Keep output style consistent. | -| `scripts/lib/start_issue/github.sh` | Fetches GitHub issue metadata. | Existing `gh` integration shows the current network integration style. | Avoid coupling update mode to issue-fetch semantics. | -| `install.sh` | Release-backed installer implementation. | Strongest existing source for asset, checksum, and install behavior. | Reuse or mirror its contract. | -| `test/start_issue.bats`, `test/helpers/fake-bin/gh` | End-to-end and fake CLI coverage. | Update mode needs deterministic coverage for release lookup and install outcomes. | Extend helpers to simulate release APIs and failures. | - -## Test Strategy +| Entry points and dispatch | `REQ-01`, `SC-01`, `SC-02` | Go parser/run-mode tests | `go test ./...` | +| Release metadata/assets | `REQ-02`, `REQ-05`, `SC-01`, `SC-05` | Fake `gh`, HTTP fixtures, asset selection tests | `go test ./...` | +| Version ordering/no downgrade | `REQ-03`, `REQ-04`, `SC-03`, `SC-04` | Semantic-version and no-op tests | `go test ./...` | +| Safe replacement | `REQ-05`, `REQ-06`, `SC-05` | Checksum, staged-version, mode, rename tests | `go test ./...` | +| Outside-git and ordinary workflow | `REQ-07`, `SC-06`, `SC-07` | Mode isolation and parity tests | `go test ./...`, `make test` | +| Documentation/index integrity | `REQ-08` | Memory-bank and whitespace checks | `make test`, `git diff --check` | -| Test surface | Canonical refs | Existing coverage | Planned automated coverage | Required local suites / commands | Required CI suites / jobs | Manual-only gap / justification | Manual-only approval ref | -| --- | --- | --- | --- | --- | --- | --- | --- | -| Update command entry parsing | `REQ-01`, `SC-01`, `SC-02` | No current coverage. | Add Bats coverage for both `update` and `--update`. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| Release resolution and install/no-op/failure behavior | `REQ-02` - `REQ-06`, `SC-01` - `SC-04` | No current coverage. | Add fake release API and asset flows for update-needed, already-current, and failure scenarios. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| Version normalization | `REQ-03`, `REQ-04`, `SC-07` | No current coverage. | Add Bats coverage for equivalent installed/release versions such as `1.11.1` and `v1.11.1`. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| No-downgrade behavior | `REQ-03`, `REQ-04`, `SC-08` | No current coverage. | Add Bats coverage for an installed version newer than the latest published release. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| Outside-git execution for update mode | `REQ-03`, `REQ-07`, `SC-06` | Existing workflow assumes git repo for issue flow. | Add Bats coverage that runs update mode outside a repository. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| Existing issue workflow regression | `REQ-07`, `SC-05` | Existing Bats suite covers core flow. | Re-run the suite and add assertions only if update parsing creates edge regressions. | `mise exec -- bats test` | Existing CI `test` job | none | none | -| Docs/spec consistency | `REQ-08`, `EC-04` | Existing docs in-tree. | Update docs plus whitespace check. | `git diff --check` | Existing CI static checks | none | none | +No manual-only gap is currently required; live GitHub access is represented by +deterministic fakes in automated tests. ## Open Questions / Ambiguities -None currently open. Blocking ambiguities from issue #13 were resolved in `decision-log.md` as `DL-01` through `DL-06`. +None blocking. The issue's generic “asset and SHA-256 checksum” wording is +resolved by the existing repository release contract: current-platform binary +asset plus `checksums.txt`, as recorded in `DL-03`. ## Environment Contract -| Area | Contract | Used by | Failure symptom | -| --- | --- | --- | --- | -| setup | Worktree may contain unrelated user changes and must not be reset. | all steps | Auto-edits overwrite unrelated work. | -| test | `bash`, `shellcheck`, `mise`, and `bats` are available per repo tooling. | verification steps | Local verification cannot complete and must be reported. | -| access / network / secrets | Real network access is not required for automated tests because fake release responses can be injected. | update tests | Tests become flaky or depend on live GitHub state. | +| Area | Contract | Failure symptom | +| --- | --- | --- | +| Build/test | Go toolchain, git, Python, and repository Make checks are available | Required local gate cannot run | +| Release boundary | Tests use fake `gh` and local HTTP fixtures; no live network is required | Test becomes nondeterministic or needs credentials | +| Filesystem | Tests use temporary targets and must not modify the installed user binary | Unsafe test setup or cleanup failure | ## Preconditions -| Precondition ID | Canonical ref | Required state | Used by steps | Blocks start | -| --- | --- | --- | --- | --- | -| `PRE-01` | `DL-01` - `DL-06` | The update target, comparison rule, no-downgrade rule, and installer contract are fixed. | `STEP-02` - `STEP-06` | yes | -| `PRE-02` | `CON-04`, `REQ-07` | Existing issue-starting workflow remains the regression baseline. | `STEP-02`, `STEP-05`, `STEP-06` | yes | +| ID | Canonical ref | Required state | +| --- | --- | --- | +| `PRE-01` | `brief.md`, `design.md`, `DL-07` | Reconciled scope and current Go design are active | +| `PRE-02` | `REQ-07`, `INV-03` | Existing issue-start regression tests remain the baseline | ## Workstreams -| Workstream | Implements | Result | Owner | Dependencies | -| --- | --- | --- | --- | --- | -| `WS-01` | `REQ-01`, `REQ-07` | CLI parsing and orchestration gain an isolated update mode. | agent | `PRE-01`, `PRE-02` | -| `WS-02` | `REQ-02` - `REQ-06` | Release-backed update execution resolves latest release, normalizes versions, and installs safely. | agent | `WS-01` | -| `WS-03` | `REQ-08` | Public docs and spec describe the new workflow consistently. | agent | `WS-01`, `WS-02` | +- `WS-01` Verify parser and isolated update-mode behavior (`REQ-01`, `REQ-07`). +- `WS-02` Verify release lookup, semantic comparison, checksums, staged version, and replacement (`REQ-02`–`REQ-06`). +- `WS-03` Align public docs and memory-bank navigation (`REQ-08`). ## Approval Gates -None. The plan does not require destructive repo actions, but permission errors on the target executable must surface as user-facing command failures rather than silent fallback behavior. +None. The plan only changes repository documentation and uses temporary test +targets; it does not authorize replacing a user's installed binary during this +review pass. ## Work Order -| Step ID | Actor | Implements | Goal | Touchpoints | Artifact | Verifies | Evidence IDs | Check command / procedure | Blocked by | Needs approval | Escalate if | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| `STEP-01` | agent | `REQ-08` | Establish the FT-013 feature package and working contract. | `memory-bank/features/FT-013/*` | Feature docs | `CHK-03` | `EVID-01` | Review document boundaries and issue alignment. | none | none | Feature package drifts from issue #13 intent. | -| `STEP-02` | agent | `REQ-01`, `REQ-07` | Extend CLI parsing and top-level flow for isolated update mode. | `scripts/start-issue`, `scripts/lib/start_issue/cli.sh`, orchestration modules | Code changes | `CHK-01`, `CHK-02` | `EVID-01` | Syntax check and regression suite. | `PRE-01`, `PRE-02` | none | Update mode alters issue-input parsing or normal workflow behavior. | -| `STEP-03` | agent | `REQ-02` - `REQ-06` | Implement release metadata lookup, normalized version comparison, checksum verification, and install flow. | update helpers, `install.sh`, relevant modules | Code changes | `CHK-01`, `CHK-02` | `EVID-01` | Automated update-path coverage. | `STEP-02` | none | The release-backed contract must diverge from `install.sh` to work. | -| `STEP-04` | agent | `REQ-02` - `REQ-07` | Extend test doubles and Bats scenarios for metadata lookup, version-normalized no-op, failure, and outside-git update runs. | `test/start_issue.bats`, `test/helpers/fake-bin/gh`, fixtures | Tests | `CHK-02` | `EVID-01` | `mise exec -- bats test` | `STEP-02`, `STEP-03` | none | Fake release behavior cannot model the needed flows deterministically. | -| `STEP-05` | agent | `REQ-08` | Update English/Russian docs and canonical spec with the new workflow and expected outputs. | `README.md`, `README.ru.md`, `doc/spec.md` | Docs | `CHK-03` | `EVID-01` | `git diff --check` | `STEP-02`, `STEP-03` | none | Docs and implementation disagree about update target or release source. | -| `STEP-06` | agent | `EC-01` - `EC-05` | Run verification and record completion status. | full change surface | Verification output | `CHK-01`, `CHK-02`, `CHK-03` | `EVID-01` | `bash -n scripts/start-issue`, `shellcheck install.sh scripts/start-issue scripts/lib/start_issue/*.sh`, `git diff --check`, `mise exec -- bats test` | `STEP-02` - `STEP-05` | none | Required tools are unavailable or a regression remains unresolved. | - -## Parallelizable Work - -- `PAR-01` Feature docs can be reviewed and refined before code changes. -- `PAR-02` Test-double updates should follow the chosen release-resolution contract. -- `PAR-03` Public docs should wait until update-target and install behavior are fixed in code. +| Step | Implements | Artifact | Verifies | Evidence | +| --- | --- | --- | --- | --- | +| `STEP-01` | `REQ-01`, `REQ-07` | Focused parser/mode test results | `CHK-01` | `EVID-01` | +| `STEP-02` | `REQ-02`–`REQ-06` | Release/update test results | `CHK-01` | `EVID-01` | +| `STEP-03` | `REQ-08` | README/spec and feature-pack docs | `CHK-02` | `EVID-02` | +| `STEP-04` | `EC-01`–`EC-06` | Final local verification output | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | ## Checkpoints -| Checkpoint ID | Refs | Condition | Evidence IDs | -| --- | --- | --- | --- | -| `CP-01` | `STEP-02`, `STEP-03` | Update mode is isolated from the issue workflow and uses a release-backed install contract. | `EVID-01` | -| `CP-02` | `STEP-04`, `STEP-06` | Both update entry forms, no-op behavior, failure handling, and normal workflow regression coverage pass. | `EVID-01` | - -## Execution Risks - -| Risk ID | Risk | Impact | Mitigation | Trigger | -| --- | --- | --- | --- | --- | -| `ER-01` | Update mode reuses issue-workflow prerequisites and becomes unusable outside git repos. | Direct violation of issue #13. | Keep update flow separate from repo/issue planning. | Update code reads git context before mode dispatch. | -| `ER-02` | Version lookup compares mismatched formats such as `1.12.0` versus `v1.12.0`. | False updates or false no-op decisions. | Normalize version strings before comparison and test both states. | Output says update needed when versions are semantically equal. | -| `ER-03` | Installer logic diverges between `install.sh` and self-update. | Two incompatible installation contracts emerge. | Share or mirror the same release/checksum/install behavior deliberately. | One path verifies checksum or target mode differently. | +- `CP-01`: focused Go/parity tests cover all update branches and preserve the ordinary workflow. +- `CP-02`: `make test` passes and canonical docs have no stale active legacy owner. -## Stop Conditions / Fallback +## Execution Risks / Stop Conditions -| Stop ID | Related refs | Trigger | Immediate action | Safe fallback state | -| --- | --- | --- | --- | --- | -| `STOP-01` | `CON-04`, `REQ-07`, `FM-01` | Adding update mode regresses the existing issue workflow. | Stop expanding update behavior and repair compatibility first. | Existing issue workflow remains intact even if update mode scope is temporarily reduced. | -| `STOP-02` | `DL-01`, `FM-04` | Update behavior cannot stay consistent with the release-backed installer contract. | Stop and re-open the decision instead of shipping a second install path. | Existing release installation remains the only supported path. | +- `ER-01`: A documentation claim diverges from the Go implementation; stop and update the canonical owner before proceeding. +- `ER-02`: A test requires live GitHub or an installed user binary; stop and replace it with a deterministic fixture. +- `STOP-01`: If current implementation and issue acceptance materially conflict, stop at the owner document and reopen the decision log rather than expanding scope. ## Plan-local Evidence -| Evidence ID | Artifact | Producer | Path contract | Reused by checkpoints | -| --- | --- | --- | --- | --- | -| `EVID-13` | Feature-flow working-contract summary | implementer | Final response summary | `CP-01`, `CP-02` | - -## Execution Status - -- `STEP-01` completed on 2026-05-24 by creating the FT-013 feature package and decision log. -- `STEP-02` - `STEP-06` not started in this document-only review pass. +- `EVID-01` `cmd/start-issue/main_test.go` and + `cmd/start-issue/parity_integration_test.go`; `make test` passed on 2026-08-04. +- `EVID-02` `README.md`, `README.ru.md`, `doc/spec.md`, and the successful + memory-bank link audit and `git diff --check` within `make test` on + 2026-08-04. +- `EVID-03` Review-improve cycle results stored in + `feature-review-report.md`. -## Ready For Acceptance +## Acceptance Result -- The feature package is ready to drive implementation once the review-improve cycle closes without `critical` or `important` document issues. -- Final acceptance remains owned by `feature.md`. +All canonical checks passed, the current Go runtime and public documentation +satisfy `SC-01` through `SC-07`, the simplify review found no required runtime +change, and `brief.md` records the delivery as done. diff --git a/memory-bank/features/FT-013/solution.md b/memory-bank/features/FT-013/solution.md index 89e9ed6..6324aa4 100644 --- a/memory-bank/features/FT-013/solution.md +++ b/memory-bank/features/FT-013/solution.md @@ -1,118 +1,15 @@ --- -title: "FT-013: Solution" +title: "FT-013: Legacy solution redirect" doc_kind: feature -doc_function: canonical -purpose: "Canonical solution document for FT-013. Defines the selected self-update design without redefining feature scope or acceptance criteria." +doc_function: legacy +purpose: "Archived migration redirect to the canonical FT-013 design." derived_from: - - feature.md - - decision-log.md -status: active + - design.md +status: archived audience: humans_and_agents -must_not_define: - - ft_013_scope - - ft_013_acceptance_criteria - - ft_013_delivery_status - - implementation_sequence --- -# FT-013: Solution +# Legacy redirect -## Selected Design - -- `SOL-01` Add a dedicated update mode that can be entered either by the `update` subcommand or the `--update` flag and normalize both forms into one workflow. -- `SOL-02` Resolve the latest published release from GitHub Release assets for `dapi/start-issue`, not from the current checkout or branch. -- `SOL-03` Determine the installed version and target path from the currently running executable, so the command updates the same installation the user invoked. -- `SOL-03A` Normalize version strings before comparison so equivalent forms such as `1.11.1` and `v1.11.1` are treated as the same release. -- `SOL-03B` Treat an installed version newer than the latest published release as a successful no-op rather than a downgrade trigger. -- `SOL-04` Reuse the project's existing release-backed install contract: download the release asset plus checksum, verify integrity, and install with executable permissions preserved. -- `SOL-05` Keep the update workflow independent of git-repository detection and ordinary issue-starting orchestration. -- `SOL-06` Keep the ordinary `start-issue ISSUE` path behaviorally unchanged. -- `SOL-07` Document the command forms, update states, and installer relationship consistently across `README.md`, `README.ru.md`, and `doc/spec.md`. - -## Requirement Mapping - -| Requirement ID | Solution / architecture refs | Notes | -| --- | --- | --- | -| `REQ-01` | `SOL-01`, `CTR-01` | Both entry forms converge into one mode. | -| `REQ-02` | `SOL-02`, `CTR-02`, `DL-05` | Latest release is resolved from GitHub Releases. | -| `REQ-03` | `SOL-03`, `SOL-03A`, `DL-02`, `DL-04` | The running executable defines both current version source and safe update target. | -| `REQ-04` | `SOL-02`, `SOL-03`, `SOL-03A`, `SOL-03B`, `CTR-03`, `DL-04`, `DL-06` | Normalized version comparison drives the no-op success path. | -| `REQ-05` | `SOL-04`, `DL-01`, `DL-02` | Update reuses the release-backed installer contract and preserves mode. | -| `REQ-06` | `SOL-02`, `SOL-04`, `CTR-02`, `CTR-03` | Lookup/download/checksum/install failures stay explicit. | -| `REQ-07` | `SOL-05`, `SOL-06` | Update mode is isolated from the issue workflow. | -| `REQ-08` | `SOL-07` | Docs are part of the delivery surface. | - -## To-Be Flow - -1. Parse CLI input and normalize `update` and `--update` into update mode. -2. Resolve the executable path and current installed version from the running `start-issue`. -3. Resolve the latest published release metadata from GitHub Releases for `dapi/start-issue`, including the canonical release tag and asset URLs. -4. Normalize the installed version and release tag into the same comparison form before deciding whether an update is needed. -5. If already current, print a success message and exit `0`. -6. If the installed version is newer than the latest published release, print a success no-op message and exit `0` without downgrading. -7. If a newer release exists, download the release asset and checksum, verify integrity, install to the current executable path with executable permissions preserved, and print the resulting version. -8. If any release lookup, download, checksum, or install step fails, print a clear actionable error and exit non-zero. - -## Contracts - -| Contract ID | Related refs | Input / Output | Producer / Consumer | Notes | -| --- | --- | --- | --- | --- | -| `CTR-01` | `SOL-01`, `REQ-01` | Input: raw CLI args; output: normalized update-mode state. | CLI parser / orchestration | `update` and `--update` are equivalent entry points. | -| `CTR-02` | `SOL-02`, `SOL-04`, `REQ-02`, `REQ-05`, `REQ-06` | Input: repository id `dapi/start-issue`; output: latest release tag plus asset and checksum URLs. | update workflow / GitHub lookup helper | Lookup owns release metadata resolution only. | -| `CTR-03` | `SOL-03`, `SOL-03A`, `SOL-03B`, `REQ-03`, `REQ-04`, `REQ-06` | Input: running executable path plus latest release tag; output: current version, normalized comparison result, and install/no-op decision. | update workflow / user-facing output | The running executable is the source of truth for the local installation being updated. | -| `CTR-04` | `SOL-04`, `REQ-05`, `REQ-06` | Input: resolved release asset and checksum URLs plus target executable path; output: verified installed executable or explicit install failure. | installer helpers / update workflow | Download, checksum verification, and install remain aligned with `install.sh`. | - -## Target Architecture - -### Architecture Invariants - -- Update mode never requires git-repository discovery. -- Release-backed installation behavior stays aligned with `install.sh`. -- Version equality is semantic for this workflow and ignores an optional leading `v`. -- Update mode never downgrades an installation that is already ahead of the latest published release. -- Update mode changes only the invoked installation by default. -- Existing issue-starting behavior remains isolated from update logic. - -### Target Shape - -| Layer / responsibility | To-be role | Boundary / non-owner | Related refs | -| --- | --- | --- | --- | -| CLI parsing | Recognize `update` and `--update`, normalize them into update mode, and keep existing issue parsing intact. | Does not perform release I/O directly. | `SOL-01`, `SOL-06` | -| Update workflow | Resolve executable path, current version, latest release tag, normalize versions, compare, and drive install/no-op/failure output. | Does not require repo/base-branch/issue context. | `SOL-02`, `SOL-03`, `SOL-03A`, `SOL-05` | -| Installer helpers | Download release asset and checksum, verify integrity, and install with executable mode preserved. | Do not own CLI mode detection or version comparison. | `SOL-04` | -| Existing issue pipeline | Continue handling `start-issue ISSUE` unchanged. | Does not branch into update-specific behavior. | `SOL-05`, `SOL-06` | - -## Accepted Local Decisions - -- `SD-01` Use the current one-liner installer contract as the canonical update source, but implement update as an in-process CLI workflow rather than invoking `curl ... | bash`. -- `SD-02` Treat the resolved executable path for the current invocation as the update target, which is safer than guessing across multiple `PATH` entries. -- `SD-03` Prefer release-backed metadata plus checksummed assets over inferring "latest" from repository state or local `VERSION`. -- `SD-03A` Normalize versions by stripping a single leading `v` before comparison, because the current CLI version string and release tags need not use the same surface format. -- `SD-03B` If the installed version is already ahead of the latest published release, treat that state as a no-op success and leave the executable untouched. -- `SD-04` Keep update behavior available outside git repositories by avoiding repo-root, worktree, and issue-fetch prerequisites. - -## Change Surface - -| Ref | Surface | Type | Why it changes | -| --- | --- | --- | --- | -| `SOL-01` - `SOL-06` | `scripts/start-issue`, `scripts/lib/start_issue/*.sh` | code | Add update mode parsing and execution without regressing the ordinary workflow. | -| `SOL-04` | `install.sh` or shared installer logic | code | Keep release-backed install behavior aligned across install and update paths. | -| `SOL-01` - `SOL-06` | `test/start_issue.bats`, `test/helpers/fake-bin/gh` | test | Cover both update entry forms, no-op path, failure path, and outside-git behavior. | -| `SOL-07` | `README.md`, `README.ru.md`, `doc/spec.md`, `memory-bank/features/FT-013/*` | doc | Document the new workflow and its relation to existing install paths. | - -## Failure Modes - -- `FM-01` Update mode accidentally requires a git repository and fails outside one. -- `FM-02` Version comparison uses the wrong executable instance when multiple `start-issue` copies exist. -- `FM-03` Release lookup/download/checksum errors collapse into a generic failure that users cannot act on. -- `FM-04` The update path drifts from `install.sh` and creates two incompatible release-install contracts. -- `FM-05` Version comparison treats `1.11.1` and `v1.11.1` as different releases and triggers a false update. - -## Rollout / Backout - -- `RB-01` Roll out by landing the update mode behind explicit `update` / `--update` entry points and documenting it as part of the install story. -- `RB-02` Back out by reverting the update-mode patch set; the existing install methods remain intact. - -## ADR Dependencies - -None. +The active solution-space owner is [design.md](design.md). This file is +retained only so links from the pre-feature-flow package remain recoverable. diff --git a/memory-bank/features/missing.md b/memory-bank/features/missing.md index fa8896f..1d65d9c 100644 --- a/memory-bank/features/missing.md +++ b/memory-bank/features/missing.md @@ -22,7 +22,7 @@ replacement for a feature `brief.md`. | Issue | Current state | Memory-bank state | Gap / recommended action | | --- | --- | --- | --- | -| [#35](https://github.com/dapi/start-issue/issues/35) | Open; duplicates the already delivered #13 contract | FT-013 documents and implements the release-backed self-update, but does not reference #35. | Do not create a second package. Reconcile #35 with FT-013: add the issue as provenance or close the duplicate after verifying the acceptance criteria against current tests. | +| [#35](https://github.com/dapi/start-issue/issues/35) | Open; reconciled to the existing delivery slice | FT-013 is the single owner and now references #35 as provenance; current Go implementation and tests cover the contract. | Keep one package; close or update the GitHub issue separately after acceptance verification. | ## Closed issues without a dedicated package