Skip to content

docs: ADRs 0001-0003 + spec amendments + 2 new tracks (hook-sync, spring-ask-skill)#8

Merged
amondnet merged 9 commits intomainfrom
amondnet/parser-comparison
Apr 29, 2026
Merged

docs: ADRs 0001-0003 + spec amendments + 2 new tracks (hook-sync, spring-ask-skill)#8
amondnet merged 9 commits intomainfrom
amondnet/parser-comparison

Conversation

@amondnet
Copy link
Copy Markdown
Contributor

@amondnet amondnet commented Apr 29, 2026

Summary

This PR adds the project's first three Architecture Decision Records (ADRs), applies the spec amendment proposed by ADR-0003 to the existing build-file-detect-20260428 track, creates two new tracks implementing ADR-0001/0002, and amends arch-md-v2-20260428 to absorb the hook-driven model.

All changes are documentation/planning artifacts. No application code changes.

Commits

SHA Description
822c8ff docs(adr): ADRs 0001-0003 (lazy loading + 3-tier detection + extended coverage)
96318e6 docs(spec): build-file-detect FR-1217 + T011T016 amendment
7535e15 feat(track): hook-sync-20260429 track (sync.ts + 3 hooks)
889debc feat(track): spring-ask-skill-20260429 track (thin delegating skill)
34931d8 docs(spec): arch-md-v2 amendment (absorb hook model + ADR refs)

ADRs Introduced (commit 822c8ff)

  • ADR-0001 — Lazy Skill Loading via Hooks: Replaces upfront /spring:install with a thin spring-ask skill plus Claude Code hooks (SessionStart, FileChanged, CwdChanged) delegating to @pleaseai/ask.
  • ADR-0002 — Three-Tier Spring Boot Version Detection: Bun static parsing (Tier 1, ~95%) → opt-in build-tool CLI fallback (Tier 2, ~5%, consent-gated) → --boot user override (Tier 3).
  • ADR-0003 — Extended Static Parser Coverage and Local Build-Tool Cache Lookup: Extends Tier 1 to gradle/libs.versions.toml, gradle.properties, settings.gradle pluginManagement, and ~/.m2/~/.gradle cache lookup.

Spec Amendment: build-file-detect-20260428 (commit 96318e6)

Applies ADR-0003's proposed FR-12 through FR-17 to the affected track. Tasks T011~T016 added to the plan, AC-1 fixture matrix expanded with 8 new rows, References updated with ADR links.

New Tracks

hook-sync-20260429 (commit 7535e15)

Implements ADR-0001's hook-driven version sync. Defines scripts/sync.ts, three Claude Code hook configurations, the per-project cache schema (~/.cache/pleaseai-spring/projects/<hash>.json), atomic write semantics, flock coordination, and asyncRewake: true exit-code-2 contract for surfacing version changes to Claude.

  • 14 functional requirements (FR-1~14), 3 NFRs, 7 acceptance criteria.
  • 9 implementation tasks (T001~T009) with parallel scheduling.

spring-ask-skill-20260429 (commit 889debc)

Implements the consumer side of ADR-0001 — a single thin skill at skills/spring-ask/SKILL.md plus a referenced library-mapping table. The skill reads the cache populated by hook-sync-20260429 and delegates to @pleaseai/ask with the library identifier and version pinned. Refuses to silently answer in non-Spring projects to preserve version correctness.

  • 10 functional requirements (FR-1~10), 3 NFRs, 6 acceptance criteria.
  • 10 implementation tasks (T001~T010) with parallel scheduling.

arch-md-v2 Amendment (commit 34931d8)

Updates arch-md-v2-20260428 spec to require coverage of the hook-driven model (per ADR-0001) and the three-tier detection strategy (per ADR-0002) in the new § Install Model (v2) section. Replaces the deferred ADR work with explicit references to the now-landed ADRs. Adds new sibling track and ADR references.

tracks.jsonl updated to register the two new tracks under section: active.

Track Registry State

After merge:

Track Status Type
plugin-scaffold-20260428 review chore
build-file-detect-20260428 planned (amended) feature
arch-md-v2-20260428 planned (amended) chore
hook-sync-20260429 planned (new) feature
spring-ask-skill-20260429 planned (new) feature

Notes

  • Documentation only: This PR contains no application code changes. Implementation of the new tracks happens in follow-up PRs.
  • Proposed ADRs: All three ADRs are in Proposed state. Status moves to Accepted upon merge.
  • Spec amendments are contract changes: Merging commits the project to FR-12~17 in build-file-detect and the new track scopes.
  • /spring:install not removed: It survives as an opt-in --pre-warm mode for offline/CI scenarios, per ADR-0001.

Checklist

  • ADR-0001: Lazy skill loading via hooks
  • ADR-0002: Three-tier version detection strategy
  • ADR-0003: Extended static parser coverage and cache lookup
  • decisions/index.md registers all three ADRs
  • build-file-detect-20260428/spec.md + plan.md amended (FR-1217, T011T016, AC matrix, References)
  • hook-sync-20260429 track created (spec + plan + metadata)
  • spring-ask-skill-20260429 track created (spec + plan + metadata)
  • arch-md-v2-20260428/spec.md amended (hook model coverage, ADR refs, scope updates)
  • tracks.jsonl registers both new tracks

…ction

- ADR-0001: Lazy skill loading via Claude Code hooks (SessionStart,
  FileChanged, CwdChanged) with thin spring-ask skill delegating to
  @pleaseai/ask. Replaces upfront /spring:install with on-demand
  resolution and zero-friction install.
- ADR-0002: Three-tier version detection strategy: Bun static parsing
  (95%) -> opt-in build-tool fallback (~5%, consent-gated) -> --boot
  user override. Preserves library-layer I/O-free invariant; CLI used
  only as effective-pom expander, not evaluator.
- ADR-0003: Extends Tier 1 to libs.versions.toml, gradle.properties,
  settings.gradle pluginManagement, and ~/.m2/~/.gradle cache lookup.
  Proposes spec amendments FR-12 through FR-17 for the
  build-file-detect-20260428 track.
…0003

Extends the build-file-detect-20260428 track to cover the additional static
parsing sources proposed in ADR-0003:

- FR-12: Gradle version catalog (libs.versions.toml) + gradle.properties
  variable substitution.
- FR-13: settings.gradle(.kts) pluginManagement { plugins { ... } } block
  as an additional version source ordered before per-module walk.
- FR-14: Maven external parent POM lookup via ~/.m2/repository cache;
  falls back to unsupported with cache-miss reason if not present.
- FR-15: --boot override persistence at
  ~/.cache/pleaseai-spring/overrides.json keyed by sha256(project_dir).
  Adds --boot and --clear-override CLI flags.
- FR-16: Published Gradle version catalog (from("g:a:v")) resolution
  via cache-first lookup (~/.m2, ~/.gradle, ~/.cache), routing network
  fetch through resolve.ts to preserve single-network-boundary invariant.
- FR-17: requires-build-tool reason taxonomy distinguishing patterns
  needing JVM evaluation (buildSrc/, settings plugins, ${revision}) from
  merely-unrecognized static patterns. Suggestion message includes both
  the build-tool fallback consent flow (per ADR-0002) and --boot override.

Out-of-scope updates remove the now-in-scope items (libs.versions.toml,
pluginManagement) and clarify that build-tool evaluation execution is
owned by the Tier-2 follow-up track per ADR-0002.

Plan adds tasks T011–T016 implementing the new FRs, expanded dependency
graph, updated AC verification mapping, and a Decision Log entry citing
all three ADRs.
@amondnet amondnet changed the title docs(adr): lazy skill loading and three-tier version detection docs: ADRs 0001-0003 + spec amendment for build-file-detect (FR-12~17) Apr 29, 2026
@amondnet amondnet marked this pull request as ready for review April 29, 2026 08:40
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

5 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".please/docs/tracks/active/build-file-detect-20260428/plan.md">

<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/plan.md:114">
P2: Batch 4 incorrectly lists T016 as parallel with T013, but T016 depends on T013. This can mis-sequence implementation work.</violation>
</file>

<file name=".please/docs/tracks/active/build-file-detect-20260428/spec.md">

<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:50">
P2: FR-15 conflicts with the `DetectSource.file` contract by returning `overrides.json` for a global cache file that is outside the project root.</violation>

<violation number="2" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:51">
P2: FR-16 describes an incorrect path shape for `~/.gradle/caches/modules-2/files-2.1`; Gradle cache entries include a hash directory, so Maven-layout-only lookup will fail for cached catalogs.</violation>
</file>

<file name=".please/docs/decisions/0003-extended-static-parser-coverage.md">

<violation number="1" location=".please/docs/decisions/0003-extended-static-parser-coverage.md:144">
P3: Incorrect requirement reference (`FR-7`) makes the ADR internally inconsistent with the defined FR-12..FR-17 set.</violation>
</file>

<file name=".please/docs/decisions/0002-three-tier-version-detection.md">

<violation number="1" location=".please/docs/decisions/0002-three-tier-version-detection.md:60">
P2: Avoid a fixed `/tmp/effective.xml` output path for Tier-2 Maven fallback; it can cause race conditions and stale/cross-project reads under concurrent detections.</violation>
</file>
Architecture diagram
sequenceDiagram
    participant Claude as Claude Code (Hooks)
    participant Sync as sync.ts (Orchestrator)
    participant Detect as detect.ts (Static Parser)
    participant FS as Local Filesystem & Cache
    participant Tools as Build Tools (Mvn/Gradle)
    participant Ask as @pleaseai/ask (External API)

    Note over Claude, Ask: NEW: ADR-0001/0002 Runtime Sync & Detection Flow

    Claude->>Sync: NEW: Trigger via Hook (SessionStart / FileChanged)
    
    Sync->>FS: NEW: Check ~/.cache/.../overrides.json (Tier 3)
    FS-->>Sync: Return manual --boot override (if exists)

    opt No Override Found
        Sync->>Detect: NEW: Start Tier 1 Static Detection
        Detect->>FS: CHANGED: Read build files + libs.versions.toml + gradle.properties
        
        Note over Detect, FS: NEW: ADR-0003 External Cache Lookup
        Detect->>FS: FR-14/16: Lookup ~/.m2/repository or ~/.gradle/caches
        
        alt Static Match Found
            Detect-->>Sync: Return version (Source: Static)
        else Requires JVM (e.g., buildSrc, interpolation)
            Detect-->>Sync: Return kind: 'unsupported' (requires-build-tool)
        end
    end

    alt NEW: Tier 2 Escalation (ADR-0002)
        Sync->>FS: Check for project-level consent
        opt Consent Granted
            Sync->>Tools: Exec 'mvn help:effective-pom' or Gradle init script
            Tools-->>Sync: Return resolved build model
            Sync->>Detect: Parse expanded tool output
            Detect-->>Sync: Return version (Source: Build Tool)
        end
    end

    Sync->>FS: NEW: Atomic write to ~/.cache/.../projects/<hash>.json
    Sync-->>Claude: Hook complete (asyncRewake)

    Note over Claude, Ask: NEW: ADR-0001 Lazy Delegation (at Query Time)

    Claude->>FS: Read pinned version from project cache
    Claude->>Ask: NEW: Fetch docs for @pleaseai/spring (version pinned)
    Ask-->>Claude: Return relevant documentation snippets
Loading

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

Comment thread .please/docs/tracks/active/build-file-detect-20260428/plan.md Outdated
Comment thread .please/docs/tracks/active/build-file-detect-20260428/spec.md Outdated
Comment thread .please/docs/tracks/active/build-file-detect-20260428/spec.md Outdated
Comment thread .please/docs/decisions/0002-three-tier-version-detection.md Outdated
Comment thread .please/docs/decisions/0003-extended-static-parser-coverage.md Outdated
Implements ADR-0001's hook-driven version sync model. New track defines
`scripts/sync.ts` plus three Claude Code hooks (SessionStart,
FileChanged, CwdChanged) that populate a per-project version cache at
~/.cache/pleaseai-spring/projects/<sha256(project_dir)>.json.

The cache schema (FR-4) carries the resolved Boot version, component
versions, source provenance, tier (1/2/3 per ADR-0002), and a
needs_consent flag for Tier-2 escalation. Atomic temp+rename writes
plus flock coordination handle concurrent invocations.

asyncRewake: true is used exclusively to surface version *changes* to
Claude (exit 2 with stdout summary). Same-version invocations exit 0
silently to avoid context pollution during edit-heavy sessions.

Out of scope: the cache consumer (spring-ask-skill-20260429), Tier-2
build-tool execution (build-file-detect FR-17 / a follow-up track),
override store CRUD (build-file-detect FR-15).
Implements the thin delegating skill side of ADR-0001's lazy-loading
model. New track defines a single always-loaded skill at
skills/spring-ask/SKILL.md plus a referenced library-mapping table.

The skill: (a) detects Spring-related questions via its description
matcher, (b) reads the per-project version cache produced by
hook-sync-20260429, (c) maps question keywords to a Spring library
identifier (Framework, Boot, Security, Data/JPA, Cloud, Batch,
Integration, WebFlux, Reactor), and (d) delegates to @pleaseai/ask
with the library identifier and version pinned from the cache.

Refuses to silently answer in non-Spring projects (FR-7) — version
correctness is preserved by reporting 'not a Spring project' rather
than degrading to training-data knowledge. Cold-cache and stale-cache
paths run sync.ts synchronously before delegating (FR-3, FR-8). The
consent flow for Tier-2 (requires-build-tool) and Tier-3 (--boot
override) is in the skill instructions rather than a separate command.

Out of scope: the cache producer (hook-sync-20260429), @pleaseai/ask
internals, per-component skill files, custom slash commands.
Updates the arch-md-v2-20260428 track to incorporate the lazy-loading
direction concretized by ADR-0001/0002/0003 and the two new sibling
tracks (hook-sync, spring-ask-skill).

Spec changes:
- § Sections to add: § Install Model (v2) must now cover the
  hook-driven sync model (SessionStart, FileChanged, CwdChanged ->
  scripts/sync.ts -> per-project cache); /spring:install becomes an
  opt-in pre-warmer rather than the default install path.
- § Sections to add: optional § Three-Tier Detection subsection
  summarizing ADR-0002.
- SC-5 expanded to require coverage of: thin spring-ask skill, hook
  model, three-tier detection, and the pre-warmer relationship.
- Out of Scope: ADR creation now superseded by 2026-04-29 — ADRs
  0001-0003 are landed and this track references them as
  authoritative input rather than producing new ADRs.
- References: added ADR-0001/0002/0003 paths, hook-sync-20260429 and
  spring-ask-skill-20260429 sibling specs, and the Claude Code hooks
  documentation URL.

Track registry:
- tracks.jsonl: register hook-sync-20260429 and spring-ask-skill-20260429
  under section: active. PRs both reference #8 (this PR) since they
  ship in the same review unit as the ADRs they implement.
@amondnet amondnet changed the title docs: ADRs 0001-0003 + spec amendment for build-file-detect (FR-12~17) docs: ADRs 0001-0003 + spec amendments + 2 new tracks (hook-sync, spring-ask-skill) Apr 29, 2026
@amondnet amondnet self-assigned this Apr 29, 2026
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4 issues found across 8 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".please/docs/tracks/active/hook-sync-20260429/spec.md">

<violation number="1" location=".please/docs/tracks/active/hook-sync-20260429/spec.md:23">
P2: Cache contract is internally inconsistent: FR-4 omits the `unsupported` shape required by FR-5/AC-5.</violation>
</file>

<file name=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md">

<violation number="1" location=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md:46">
P2: T008 is described as optional, but Verification requires it unconditionally, which makes completion criteria ambiguous.</violation>
</file>

<file name=".please/docs/tracks/active/arch-md-v2-20260428/spec.md">

<violation number="1" location=".please/docs/tracks/active/arch-md-v2-20260428/spec.md:25">
P2: Use one consistent pre-warm command contract (`/spring:install --pre-warm` vs `/spring:install`) across the spec.</violation>
</file>

<file name=".please/docs/tracks.jsonl">

<violation number="1" location=".please/docs/tracks.jsonl:4">
P2: Issue is required by project config, but this track entry stores it as an empty string.</violation>
</file>

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

Comment thread .please/docs/tracks/active/hook-sync-20260429/spec.md Outdated
Comment thread .please/docs/tracks/active/spring-ask-skill-20260429/plan.md
Comment thread .please/docs/tracks/active/arch-md-v2-20260428/spec.md Outdated
Comment thread .please/docs/tracks.jsonl Outdated
Addresses 5 cubic-dev-ai bot review comments on PR #8 (all P2/P3
correctness and consistency issues):

- plan.md (build-file-detect) Batch 4 dependency: T016 depends on T013,
  so it cannot run in parallel with T013. Re-phrased Batch 4 to: 'T012,
  T013, T015 in parallel; T016 starts after T011 + T013 land.'
- spec.md (build-file-detect) FR-8 DetectSource.file contract: clarify
  that 'file' may be an absolute path for out-of-project sources
  (~/.m2 cache, ~/.gradle cache, ~/.cache/pleaseai-spring/*). Resolves
  inconsistency where FR-15's overrides.json source was outside the
  project root but the contract said 'relative path from project root'.
- spec.md (build-file-detect) FR-15 source.file: use the full path
  '~/.cache/pleaseai-spring/overrides.json' rather than just
  'overrides.json' to align with the clarified contract.
- spec.md (build-file-detect) FR-16: Gradle cache layout actually
  includes a sha1-hash directory (...<version>/<hash>/<artifact>...),
  not the bare Maven layout. Updated the fixture description.
- ADR-0002 Tier-2 Maven path: replace fixed '/tmp/effective.xml' with
  mktemp(1) (or per-project ~/.cache/pleaseai-spring/tier2/<hash>.xml)
  to avoid race conditions and cross-project reads under the lazy
  hook-driven invocation model from ADR-0001.
- ADR-0003 line 144: incorrect requirement reference 'FR-7' corrected
  to 'FR-14 and FR-16' (the actual cache-layout-dependent requirements).

All 5 are markdown documentation fixes; no code changes.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".please/docs/tracks/active/build-file-detect-20260428/spec.md">

<violation number="1" location=".please/docs/tracks/active/build-file-detect-20260428/spec.md:39">
P2: The spec now conflates `~`-prefixed paths with absolute paths; this makes the `DetectSource.file` contract ambiguous for out-of-project sources.</violation>
</file>

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

Comment thread .please/docs/tracks/active/build-file-detect-20260428/spec.md Outdated
Addresses 5 cubic-dev-ai bot review comments from the second review
cycle (all P2 correctness/consistency issues):

- hook-sync FR-4: extend cache schema to a tagged union covering all
  three DetectResult kinds (detected, unsupported, not-found) so the
  schema matches FR-5 and AC-5 requirements. Previously only the
  detected variant was shown despite FR-5/AC-5 referencing the
  unsupported shape.
- spring-ask-skill plan T008/Verification: clarify that the eval-suite
  automated test is conditional (mirroring T008's 'optional if eval
  suite is not yet wired' qualification). Removes the contradiction
  where the verification was unconditional.
- arch-md-v2 spec L25: align pre-warm command name to
  '/spring:install --pre-warm' for consistency with the immediately
  preceding paragraph in the same bullet.
- tracks.jsonl + metadata.json: register issues #9 (hook-sync) and
  #10 (spring-ask-skill) created via gh issue create — config.yml
  declares 'issue_required: true', so empty 'issue' fields violated
  the project policy. Issue bodies link back to the originating ADRs
  and PR.
- build-file-detect FR-8 DetectSource.file: remove ambiguity by
  specifying that '~/' prefix is readability shorthand only; the
  stored value is always a POSIX absolute path with $HOME expanded
  (e.g., '/Users/alice/.m2/...'). The literal '~/' never appears in
  the stored string.

Two new GitHub issues created: #9, #10. All 5 cubic threads addressed.
Addresses 6 issues identified by /review:code-review (1 Critical + 5
Important; all P2/P3 documentation correctness/consistency issues).
Iteration 2 review confirmed zero remaining issues.

- build-file-detect spec.md FR-15: source.file example was using literal
  '~/.cache/...', contradicting FR-8's 'expand ~/ before storing'
  contract. Changed to expanded path '/home/<user>/.cache/...' with
  explicit illustration disclaimer and FR-8 cross-reference.
- decisions/0003 ADR FR-14 description: was narrower than spec FR-14
  (missing 'omits <relativePath>' trigger). Now matches spec text.
- hook-sync-20260429 plan Overview: 'Issue: TBD' -> 'Issue: #9'.
- spring-ask-skill-20260429 plan Overview: 'Issue: TBD' -> 'Issue: #10'.
- hook-sync-20260429 spec Out-of-Scope: removed wrong attribution of
  Tier-2 execution to build-file-detect FR-17. Now coherent with
  build-file-detect's own OoS — both point to a follow-up track per
  ADR-0002.
- spring-ask-skill plan Verification: added explicit Automated Tests
  bullets for FR-9 (no direct network) and FR-10 (no user-file writes)
  negative invariants.
- hook-sync-20260429 plan Verification: added explicit Automated Tests
  bullet for FR-3 (atomic temp+rename write).

7 surgical text fixes; no semantic changes to the architecture.
Internal /review:code-review iteration 2 confirmed clean.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md">

<violation number="1" location=".please/docs/tracks/active/spring-ask-skill-20260429/plan.md:76">
P2: FR-9 verification is mapped to T006, but T006 only validates false-positive matching and does not check for direct network-call directives.</violation>
</file>

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

Comment thread .please/docs/tracks/active/spring-ask-skill-20260429/plan.md Outdated
Addresses 1 cubic-dev-ai bot review comment (P2, confidence 8):

- spring-ask-skill-20260429/plan.md FR-9 verification bullet:
  the prior fix mapped FR-9 verification to T006, but T006 only
  validates false-positive description matching and does not check
  for direct network-call directives. Re-mapped to T001 (skill
  authoring) + T010 (documentation review), which actually own the
  network-invariant assertion.

REVIEW_CUBIC_ENABLED=false; cubic local review skipped (cubic runs
as a GitHub bot on push).
@amondnet amondnet merged commit 56550e1 into main Apr 29, 2026
2 checks passed
@amondnet amondnet deleted the amondnet/parser-comparison branch April 29, 2026 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant