GIT-869c63k1e: enforce ClickUp branch/PR/commit linking guardrails

[TonyCasey]

Summary

• add PR workflow checks for ClickUp task ID in branch + PR metadata
• enforce ClickUp task ID in commit messages via git-mem commit-msg hook
• add PR template with ClickUp task fields
• update workflow docs naming example

ClickUp Task

Task ID: GIT-869c63k1e
Task Link: https://app.clickup.com/t/869c63k1e
Raw Task ID: 869c63k1e

Validation

• npm run type-check
• node --import tsx --test tests/unit/hooks/commit-msg.test.ts

Summary by CodeRabbit

• New Features

  • Session runtime tracking persisted across sessions with automatic activation/deactivation and environment-based agent/model detection.
  • Runtime persistence service to store short-lived session metadata.

• Documentation

  • Updated branch naming guidance to use ClickUp task IDs.
  • Added a PR template with validation checklists.

• Process Improvements

  • Enforced ClickUp task linking and commit-message ClickUp ID validation (hook version bumped).
  • CI checks enforcing Sonar quality gates and review/reply/resolution rules.

• Tests

  • Added comprehensive tests for runtime persistence and session lifecycle handling.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[TonyCasey]

Addressed Sonar duplication feedback by refactoring runtime service tests to remove repeated setup/cleanup blocks and reducing duplicated new code. Also updated runtime service imports to node:* style in the same area.\n\nRelated task: GIT-869c63k1e

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a runtime session persistence feature (IRuntimeService + RuntimeService) with activation on session start and deactivation on session stop, DI wiring for runtime support and agent/model detection fallback, ClickUp task validation in hooks/workflows, PR governance workflows, tests, and a PR template.

Changes

Cohort / File(s)	Summary
GitHub config \.github/pull_request_template.md, \.github/workflows/clickup-linking.yml, \.github/workflows/pr-governance.yml	Add PR template; add ClickUp linking workflow enforcing branch→task ID consistency and PR inclusion; add PR governance workflow enforcing Sonar quality gate and inline-review/replies checks.
Domain contract src/domain/interfaces/IRuntimeService.ts	Add IRuntimeData and IRuntimeService interfaces (activate/deactivate/read) describing runtime.json shape, TTL semantics, and no-throw expectations.
Runtime implementation & tests src/infrastructure/services/RuntimeService.ts, tests/unit/infrastructure/services/RuntimeService.test.ts	New RuntimeService implementing persistence to .git-mem/runtime.json with activate/deactivate/read (timestamp/TTL validation, 1-min skew, safe-fail); comprehensive unit tests for activation, deactivation, and read edge cases.
Agent resolution src/infrastructure/services/AgentResolver.ts	AgentResolver now accepts optional runtimeService and cwd, lazily caches runtime data, prefers env detection then falls back to runtime.json for agent/model.
Session handlers & tests src/application/handlers/SessionStartHandler.ts, src/application/handlers/SessionStopHandler.ts, tests/unit/application/handlers/SessionStartHandler.test.ts, tests/unit/application/handlers/SessionStopHandler.test.ts	SessionStartHandler accepts runtimeService and detectAgent/detectModel to activate runtime.json (safe, non-throwing); SessionStopHandler accepts runtimeService and always calls deactivate in a finally block; tests added/extended to cover activation/deactivation and error-tolerant behavior.
DI wiring & types src/infrastructure/di/container.ts, src/infrastructure/di/types.ts	Register runtimeService in DI cradle, expose it on ICradle, convert agentResolver to factory wired with runtimeService/cwd, and pass runtimeService/detectors into session handlers.
Git hooks & tests src/hooks/commit-msg.ts, tests/unit/hooks/commit-msg.test.ts	Bump commit-msg hook fingerprint v6→v7 and add pre-check requiring ClickUp/GIT- in commit messages; tests updated to expect new version and validation message.
Docs CLAUDE.md	Update branch naming guidance to require ClickUp task-based branch names and add PR/Sonar review requirements.

Sequence Diagram

sequenceDiagram
    rect rgba(200,200,255,0.5)
    actor Dev
    participant SessionStart as SessionStartHandler
    participant Detect as detectAgent/detectModel
    participant Runtime as RuntimeService
    participant FS as .git-mem/runtime.json
    end

    Dev->>SessionStart: start(sessionId)
    SessionStart->>Detect: detectAgent(), detectModel()
    Detect-->>SessionStart: agent, model
    SessionStart->>Runtime: activate({sessionId, agent, model, timestamp, source})
    Runtime->>FS: write runtime.json
    FS-->>Runtime: write success
    Runtime-->>SessionStart: success (no-throw)
    SessionStart-->>Dev: started

    rect rgba(200,255,200,0.5)
    participant AgentResolver as AgentResolver
    Dev->>AgentResolver: resolveAgent()/resolveModel()
    AgentResolver->>Runtime: read(ttl)
    Runtime-->>AgentResolver: runtime data (if fresh)
    AgentResolver-->>Dev: agent/model (env or fallback)
    end

    rect rgba(255,200,200,0.5)
    actor Dev2
    participant SessionStop as SessionStopHandler
    Dev2->>SessionStop: stop(sessionId)
    SessionStop->>Runtime: deactivate()
    Runtime->>FS: delete runtime.json
    FS-->>Runtime: delete success
    Runtime-->>SessionStop: success (no-throw)
    SessionStop-->>Dev2: stopped
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat: session-start hook and init-hooks CLI (Phase 2) #21 — touches session lifecycle and DI wiring relevant to SessionStart/SessionStop changes and runtime wiring.
• feat: auto-detect agent/model and rework init prompts (GIT-73) #48 — related changes to agent/model detection utilities used by detectAgent/detectModel and AgentResolver.
• fix: handle circular error references in logger and handlers (GIT-109) #75 — modifies the same handler files (SessionStartHandler/SessionStopHandler) and may overlap with error/flow changes introduced here.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly reflects the main objective: enforcing ClickUp branch/PR/commit linking guardrails via task ID validation across workflows, PR templates, and commit hooks.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/GIT-869c63k1e_clickup-linking-guardrails

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR enforces ClickUp task ID linking across GitHub branches, PRs, and commit messages to improve project tracking and integration between GitHub and ClickUp.

Changes:

• Added GitHub workflow to validate ClickUp task IDs in branch names and PR metadata
• Added commit-msg hook validation requiring ClickUp task IDs in all commits
• Implemented RuntimeService for persisting AI agent/model detection across hook invocations

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.github/workflows/clickup-linking.yml	New workflow enforcing ClickUp task ID presence in branch names and PR title/body
.github/pull_request_template.md	New PR template with ClickUp task ID fields
CLAUDE.md	Updated workflow documentation from Linear to ClickUp task naming
src/hooks/commit-msg.ts	Added validation requiring ClickUp task ID in commit messages (v7)
tests/unit/hooks/commit-msg.test.ts	Updated tests for v7 hook fingerprint and new validation
src/domain/interfaces/IRuntimeService.ts	New interface for runtime session data persistence
src/infrastructure/services/RuntimeService.ts	New service implementing runtime.json read/write with TTL validation
src/infrastructure/services/AgentResolver.ts	Enhanced with runtime.json fallback for agent/model detection
src/application/handlers/SessionStartHandler.ts	Added runtime.json activation on session start
src/application/handlers/SessionStopHandler.ts	Added runtime.json deactivation on session stop
src/infrastructure/di/container.ts	Registered RuntimeService and updated AgentResolver dependencies
src/infrastructure/di/types.ts	Added runtimeService to dependency injection types
tests/unit/infrastructure/services/RuntimeService.test.ts	Comprehensive test coverage for RuntimeService
tests/unit/application/handlers/SessionStartHandler.test.ts	Added tests for runtime activation behavior
tests/unit/application/handlers/SessionStopHandler.test.ts	Added tests for runtime deactivation behavior

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TonyCasey]

Addressed both open Copilot review threads in commit 3d90836:

1. Thread PRRT_kwDORJMSCs5vFZQM (RuntimeService.ts)

• Replaced magic number with CLOCK_SKEW_ALLOWANCE_MS and used it in the skew check.

2. Thread PRRT_kwDORJMSCs5vFZQx (SessionStopHandler.ts)

• Refactored handle to return directly from try/catch while preserving finally runtime deactivation, removing the uninitialized handlerResult state.

Validated with:

• node --import tsx --test tests/unit/application/handlers/SessionStopHandler.test.ts
• node --import tsx --test tests/unit/infrastructure/services/RuntimeService.test.ts
• npm run type-check

[coderabbitai]

🧹 Nitpick comments (1)

src/infrastructure/services/RuntimeService.ts (1)

62-67: Incomplete runtime data validation may return malformed objects.

The type assertion as IRuntimeData at line 62 bypasses TypeScript's type safety. The validation only checks timestamp, but IRuntimeData requires sessionId, agent, model, and source fields. Callers may receive an object missing required fields.

Consider validating the complete structure:

♻️ Proposed validation enhancement

       const content = readFileSync(filePath, 'utf8');
-      const data = JSON.parse(content) as IRuntimeData;
+      const parsed = JSON.parse(content) as Record<string, unknown>;

       // Validate structure
-      if (!data || typeof data.timestamp !== 'string') {
+      if (
+        !parsed ||
+        typeof parsed.sessionId !== 'string' ||
+        typeof parsed.timestamp !== 'string' ||
+        typeof parsed.source !== 'string'
+      ) {
         return undefined;
       }
+
+      const data = parsed as IRuntimeData;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/infrastructure/services/RuntimeService.ts` around lines 62 - 67, The
current parsing in RuntimeService.ts casts JSON to IRuntimeData then only checks
timestamp, which can return malformed objects; update the parsing/validation
around the const data variable so you parse into an unknown, remove the unsafe
"as IRuntimeData" cast, and explicitly validate that sessionId, agent, model,
source and timestamp exist and are strings (or other required shapes) before
returning — if any are missing/invalid return undefined; reference the parsed
variable "data" and the IRuntimeData type to locate where to add these checks.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/infrastructure/services/RuntimeService.ts`:
- Around line 62-67: The current parsing in RuntimeService.ts casts JSON to
IRuntimeData then only checks timestamp, which can return malformed objects;
update the parsing/validation around the const data variable so you parse into
an unknown, remove the unsafe "as IRuntimeData" cast, and explicitly validate
that sessionId, agent, model, source and timestamp exist and are strings (or
other required shapes) before returning — if any are missing/invalid return
undefined; reference the parsed variable "data" and the IRuntimeData type to
locate where to add these checks.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/pr-governance.yml:
- Around line 63-99: The GraphQL query is paginated (reviewThreads(first:100)
and comments(first:100)) which can miss threads/comments; update the workflow to
detect and handle pagination by requesting pageInfo (endCursor, hasNextPage) for
reviewThreads and comments in the query and then either iterate using the
endCursor to fetch all pages (loop the gh api graphql call until hasNextPage is
false) or fail the check when pageInfo.hasNextPage is true so the run is
considered incomplete; adjust the variables and jq logic that compute pr_author,
unresolved_count and missing_inline_reply_count to aggregate across all pages
(or short-circuit with a failing message) rather than relying only on the first
100 items.
- Around line 16-51: The SonarCloud API calls use curl in the for-loop and when
building issues_response without authentication or the organization parameter;
update both curl invocations to use Basic auth via -u "${SONAR_TOKEN}:" and
append the organization query param using SONAR_ORGANIZATION (e.g. add
&organization=${SONAR_ORGANIZATION}) so the requests target the correct org, and
ensure SONAR_PROJECT_KEY usage (the variable referenced as SONAR_PROJECT_KEY)
remains the project key only while organization is passed separately; preserve
existing variables PR_NUMBER, quality_status and issues_response logic but
modify the curl invocations accordingly and ensure SONAR_TOKEN and
SONAR_ORGANIZATION are required env inputs.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.1% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/pr-governance.yml:
- Around line 19-20: The workflow uses an invalid GitHub Actions expression
replace(...) for SONAR_PROJECT_KEY causing a syntax error; remove the replace
fallback and instead set SONAR_PROJECT_KEY to a safe default (e.g., use
github.repository directly) in the job/env and compute the sanitized value in
the shell step that runs (sanitize by replacing '/' with '_' in the script), or
use available expression helpers like format() if suitable; update the
SONAR_PROJECT_KEY reference and any steps that rely on it to use the computed
sanitized value (look for SONAR_PROJECT_KEY and the erroneous replace(...) usage
to locate the code).

In `@src/infrastructure/services/AgentResolver.ts`:
- Around line 54-60: In getRuntimeData(), replace the nullish coalescing
assignment on cachedRuntimeData with a plain assignment since runtimeDataLoaded
is false only when cachedRuntimeData is undefined; specifically set
this.cachedRuntimeData = this.runtimeService?.read(this.cwd) (still guarded by
runtimeService) and keep the runtimeDataLoaded flag behavior in the same method
to simplify the logic.