codeskine
diff --git a/‎README.md‎
Lines changed: 40 additions & 73 deletions b/‎README.md‎
Lines changed: 40 additions & 73 deletions
diff --git a/‎examples/README.md‎
Lines changed: 32 additions & 0 deletions b/‎examples/README.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎examples/issues/conc-004-shutdown-sync-once.md‎
Lines changed: 108 additions & 0 deletions b/‎examples/issues/conc-004-shutdown-sync-once.md‎
Lines changed: 108 additions & 0 deletions
diff --git a/‎examples/issues/err-001-abort-tracer-init-failure.md‎
Lines changed: 79 additions & 0 deletions b/‎examples/issues/err-001-abort-tracer-init-failure.md‎
Lines changed: 79 additions & 0 deletions
@@ -28,75 +28,22 @@ does it publish to GitLab.
 Artifacts are language-agnostic: section headings and prose follow your active language at
 runtime. No language is hardcoded.
 
-## Workflow overview
-
-The five skills cover the full GitLab development lifecycle from sprint planning to merge:
-
-```mermaid
-sequenceDiagram
-    actor Dev as Developer
-    participant A as AI Agent
-    participant GL as GitLab
-
-    Dev->>A: "Plan sprint 3: auth migration"
-    A->>GL: glab milestone create
-    GL-->>A: milestone/3
-    A-->>Dev: ✓ Milestone #3 created
-
-    Dev->>A: "Create a story for the auth migration"
-    A->>GL: glab label list + milestone list
-    A-->>Dev: Draft story — approve?
-    Dev->>A: yes
-    A->>GL: glab issue create (kind::story)
-    GL-->>A: issue #10
-    A-->>Dev: ✓ Story #10 created
-
-    Dev->>A: "Add issues #11 #12 as children of #10"
-    A->>GL: glab issue view #11 / #12
-    A->>GL: glab issue link #11 --target-id #10
-    A->>GL: glab issue link #12 --target-id #10
-    A-->>Dev: Updated children table — approve?
-    Dev->>A: yes
-    A->>GL: glab issue update #10
-    A-->>Dev: ✓ Children linked
-
-    Dev->>A: "Start working on issue #11"
-    A->>GL: glab issue edit #11 (workflow::in dev)
-    A-->>Dev: ✓ Branch fix/11-oauth-handler created
-
-    Note over Dev,GL: ... development ...
-
-    Dev->>A: "Commit staged changes"
-    A-->>Dev: fix(#11): handle OAuth token expiry — approve?
-    Dev->>A: yes
-    A->>A: git commit
-    A-->>Dev: ✓ Committed abc1234
-
-    Dev->>A: "Create MR for this branch and close #11"
-    A->>GL: glab label list + diff analysis
-    A-->>Dev: Draft MR — approve?
-    Dev->>A: yes
-    A->>GL: glab mr create
-    GL-->>A: MR !5
-    A-->>Dev: ✓ MR !5 created
-
-    Dev->>A: "Link MR !5 to story #10"
-    A->>GL: glab mr view !5 + commits
-    A-->>Dev: Updated parent issue — approve?
-    Dev->>A: yes
-    A->>GL: glab issue update #10
-    A-->>Dev: ✓ Story #10 updated with MR reference
-
-    Dev->>A: "Sync story #10 children status"
-    A->>GL: glab issue view #11 + #12
-    A-->>Dev: Before/after table diff — approve?
-    Dev->>A: yes
-    A->>GL: glab issue update #10
-    A-->>Dev: ✓ Children table synced
-```
-
 ## Skills
 
+### `gitlab-init` — Project label initializer
+
+**Trigger phrases:** "Setup GitLab", "Initialize the project labels", "Configure labels",
+"Init GitLab project"
+
+**What it produces:**
+
+- The labels the workflow relies on (`workflow::*`, `type::*`, `kind::*`), created in the current project
+- Idempotent — labels already present are skipped, so it is safe to re-run any number of times
+
+**Boundary:** one-time project bootstrap. Not for issue creation (→ `gitlab-track`) or milestones (→ `gitlab-plan`).
+
+---
+
 ### `gitlab-plan` — Milestone author
 
 **Trigger phrases:** "Create a milestone", "Plan sprint 5", "Start release v2.1",
@@ -110,11 +57,11 @@ sequenceDiagram
 
 **Modes:**
 
-| Mode           | Command                         | When to use                                 |
-| -------------- | ------------------------------- | ------------------------------------------- |
-| Create         | `glab milestone create`         | New sprint or release                       |
-| Update         | `glab milestone edit`           | Extend deadline, rename, update description |
-| Close / Reopen | `glab milestone close / reopen` | End of sprint; re-open if work resumes      |
+| Mode           | Command                                        | When to use                                 |
+| -------------- | ---------------------------------------------- | ------------------------------------------- |
+| Create         | `glab milestone create`                        | New sprint or release                       |
+| Update         | `glab milestone edit`                          | Extend deadline, rename, update description |
+| Close / Reopen | `glab milestone edit --state close / activate` | End of sprint; re-open if work resumes      |
 
 **Context extracted silently:** recent git log, active branches, existing milestones, open issues.
 
@@ -242,7 +189,8 @@ markdown children table tracking all child issues:
 | [#12](…) | Add refresh token rotation | `type::feature` | `workflow::ready` | — |
 ```
 
-Child issues are linked to the parent via `glab issue link --link-type relates_to`.
+Child issues are linked to the parent via the Issue Links REST API
+(`glab api --method POST "projects/:id/issues/<iid>/links"`, `link_type=relates_to`).
 
 **Modes:**
 
@@ -268,6 +216,24 @@ No GitLab Premium required. Hierarchy state is persisted entirely in the parent
 
 ---
 
+## Commands
+
+### `/gitlab-doctor` — Environment health check
+
+A slash command (not a skill) that verifies your setup before running the workflow skills:
+
+- Confirms the `glab` CLI is installed
+- Confirms you are authenticated (`glab auth status`)
+- Prints install/login guidance and exits non-zero when something is missing
+
+```
+/gitlab-doctor              # check gitlab.com
+/gitlab-doctor <hostname>   # check a self-managed instance
+/gitlab-doctor help         # usage
+```
+
+---
+
 ## Installation
 
 ### Claude Code
@@ -332,6 +298,7 @@ mkdir -p .codex/skills && cp -r /tmp/gitlab-workflow/skills/. .codex/skills/
 ### Full sprint cycle (sequence)
 
 ```
+0. "Setup the project labels"                           → gitlab-init
 1. "Create milestone Sprint 3"                          → gitlab-plan
 2. "Create a story for OAuth migration"                 → gitlab-story (Create)
 3. "Add issues #11 #12 as children of story #10"       → gitlab-story (Add-Child)
 
@@ -0,0 +1,32 @@
+# Examples
+
+Real-world artifacts produced by the `gitlab-workflow` skills, **genericized**: every internal
+host/path has been replaced with `gitlab.example.com/acme/platform-scraper`. They illustrate the
+structure each skill generates — YAML frontmatter, sections, fenced code snippets with
+`path/file.ext line N` citations, Mermaid diagrams, and `Closes #N` / `Related to #N` footers.
+
+## Milestones — produced by `gitlab-plan`
+
+| File                                                                                   | Highlights                                                                              |
+| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [v1.4.0 — platform-scraper hardening](milestones/v1.4.0-platform-scraper-hardening.md) | objective, deliverables, linked epics, completion criteria (from `assets/milestone.md`) |
+
+## Issues — produced by `gitlab-track`
+
+| File                                                                                   | Type                   | Highlights                      |
+| -------------------------------------------------------------------------------------- | ---------------------- | ------------------------------- |
+| [ERR-001 — abort on tracer init failure](issues/err-001-abort-tracer-init-failure.md)  | `type::bug`            | repro steps, snippet, impact    |
+| [CONC-004 — idempotent Shutdown with sync.Once](issues/conc-004-shutdown-sync-once.md) | `type::technical-debt` | Mermaid sequence, tasks         |
+| [SEC-003 — enforce TLS 1.2 on the HTTP client](issues/sec-003-tls-minversion-http.md)  | `type::bug`            | security, DREAD score, Mermaid  |
+| [PERF-001 — reuse a single http.Client](issues/perf-001-single-http-client.md)         | `type::technical-debt` | before/after code, pprof impact |
+
+## Merge requests — produced by `gitlab-review`
+
+| File                                                                                                               | Type   | Highlights                                  |
+| ------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------- |
+| [feat: apiclient with TCP pool & retry](merge-requests/feat-apiclient-pool-retry.md)                               | `feat` | multi-issue close, snippets, reviewer notes |
+| [fix: error-handling consistency (OTel v2, fatal startup)](merge-requests/error-handling-otel-v2-fatal-startup.md) | `fix`  | closes 3 issues, ADR refs, reviewer notes   |
+
+> These are illustrative outputs. The Mermaid diagrams are part of what the skills generate when
+> the policy calls for them; section headings follow the user's active language at runtime (here,
+> English).
@@ -0,0 +1,108 @@
+---
+kind: issue
+type: technical-debt
+title: "[CONC-004] Ensure Shutdown runs at most once with sync.Once"
+labels: "type::technical-debt,concurrency,workflow::ready,component: platform-scraper,Priority Low"
+milestone: "v1.4.0"
+status: published
+gitlab_url: https://gitlab.example.com/acme/platform-scraper/-/issues/42
+published_at: 2026-06-03
+created_at: 2026-06-03
+---
+
+## Description
+
+### 1. `Shutdown` called from two goroutines without protection
+
+`scraperManager.Shutdown` can be invoked concurrently from both the signal goroutine (line 76)
+and the execute goroutine (line 93):
+
+```go
+// main.go line 76-78 — signal goroutine
+if err := scraperManager.Shutdown(ctx); err != nil {
+    log.Error().Err(err).Msg("Main: scraper shutdown failed")
+}
+
+// main.go line 93-95 — execute goroutine
+if err := scraperManager.Shutdown(ctx); err != nil {
+    log.Error().Err(err).Msg("Main: scraper shutdown failed")
+}
+```
+
+The current `Shutdown` implementation is a no-op:
+
+```go
+// app/scraper/scraperController.go line 104-107
+func (sc *Manager) Shutdown(ctx context.Context) error {
+    log.Debug().Msgf("ScraperManager::Shutdown shutdown scraper controller")
+    return nil
+}
+```
+
+Any future change to `Shutdown` that reads or mutates internal `Manager` state will introduce a
+data race detectable by `go test -race`.
+
+### 2. Concurrent Shutdown calls
+
+```mermaid
+sequenceDiagram
+    participant GS as signal-goroutine
+    participant GE as execute-goroutine
+    participant SM as Manager.Shutdown
+
+    GS->>SM: Shutdown(ctx) — from signal
+    GE->>SM: Shutdown(ctx) — from execute
+    Note over SM: Two concurrent calls without sync
+    Note over SM: Data race on any future state
+```
+
+---
+
+## Steps to reproduce
+
+1. Add any mutable field touched by `Manager.Shutdown`.
+2. Run `go test -race ./...` with a test that simulates SIGTERM during Execute.
+3. The race detector reports the data race.
+
+---
+
+## Expected behavior
+
+Concurrent calls to `Shutdown` are safe: the shutdown logic runs at most once thanks to
+`sync.Once`.
+
+---
+
+## Actual behavior
+
+Two concurrent `Shutdown` calls access shared `Manager` state without synchronization.
+
+---
+
+## Impact
+
+Any future evolution of `Shutdown` that writes to `Manager` fields introduces a data race that is
+not immediately visible. The `Shutdown` contract does not guarantee concurrent idempotency.
+
+---
+
+## Related issues
+
+- Epic: [#39 — CONC Concurrency Safety](https://gitlab.example.com/acme/platform-scraper/-/issues/39)
+- Related to CONC-001, CONC-002
+
+---
+
+## Affected files
+
+- `main.go` — lines 76–78, 93–95
+- `app/scraper/scraperController.go` — lines 104–107
+
+---
+
+## Tasks
+
+- [ ] Add a `shutdownOnce sync.Once` field to `Manager`
+- [ ] Wrap the `Shutdown` logic with `sc.shutdownOnce.Do(func() { ... })`
+- [ ] `go test -race ./...` with no shutdown-related data-race report
+- [ ] `golangci-lint run` with no additional errors
@@ -0,0 +1,79 @@
+---
+kind: issue
+type: bug
+title: "[ERR-001] Abort startup when tracer initialization fails"
+labels: "type::bug,error-handling,workflow::ready,component: platform-scraper,Priority High"
+milestone: "v1.4.0"
+status: published
+gitlab_url: https://gitlab.example.com/acme/platform-scraper/-/issues/77
+published_at: 2026-06-03
+created_at: 2026-06-03
+---
+
+## Description
+
+### `initTracer` error ignored — execution continues with a broken tracer
+
+`main.go` logs the `initTracer` error but keeps running:
+
+```go
+// main.go line 50-53
+tracerShutdown, err := initTracer(ctx)
+if err != nil {
+    log.Error().Err(err).Msg("Main: Error in initializing tracer")
+    // missing os.Exit(1) — execution continues
+}
+```
+
+The code below checks `tracerShutdown != nil` before calling it (line 71), but `tracerShutdown`
+is nil when `initTracer` fails: the whole scrape session emits empty/disconnected spans to the
+OTel collector for the entire run.
+
+---
+
+## Steps to reproduce
+
+1. Configure an unreachable or invalid OTel endpoint.
+2. Start `platform-scraper`.
+3. Observe: the process starts, scrapes data, and publishes it with no traces.
+
+---
+
+## Expected behavior
+
+`initTracer` fails → log the error wrapped with context → `os.Exit(1)`.
+
+---
+
+## Actual behavior
+
+The process starts normally with tracing broken, producing an entire untraced scrape cycle with
+no operational signal.
+
+---
+
+## Impact
+
+The operator gets no signal that tracing is broken: the OTel dashboard shows trace gaps with no
+alert. The problem can go unnoticed for several cycles.
+
+---
+
+## Related issues
+
+- Epic: [#66 — ERR Error Handling Consistency](https://gitlab.example.com/acme/platform-scraper/-/issues/66)
+
+---
+
+## Affected files
+
+- `main.go` — lines 50–53
+
+---
+
+## Tasks
+
+- [ ] Add `os.Exit(1)` after the error log in the `initTracer` failure branch
+- [ ] Wrap the error with `fmt.Errorf("initializing tracer: %w", err)` before logging
+- [ ] Remove the nil-check on `tracerShutdown` (line 71): after the fix, `tracerShutdown` is always valid if execution reaches that point
+- [ ] `golangci-lint run` with no additional errors