@rasensio/aidlc-content 1.36.1 → 1.37.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
 export { loadRules } from './rules.js';
+export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
 export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -5,5 +5,6 @@ export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
 export { loadRules } from './rules.js';
+export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/recipes.d.ts

@@ -0,0 +1,12 @@
+/** Where the board workflow ships, inside the published package. */
+export declare const BOARD_WORKFLOW_PATH: string;
+/**
+ * The GitHub Actions workflow that drives a Project board's Status field from the
+ * `aidlc:<status>` labels `aidlc roadmap sync` writes (project-board-recipe).
+ *
+ * Shipped as a file and printed on demand, never installed: the user creates the
+ * `project: write` token and owns the CI. This repository runs the same file from
+ * `.github/workflows/`, and a test keeps the two identical.
+ */
+export declare function loadBoardWorkflow(): string;
+//# sourceMappingURL=recipes.d.ts.map

package/dist/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAMA,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,QAAsE,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/recipes.js

@@ -0,0 +1,18 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+/** Where the board workflow ships, inside the published package. */
+export const BOARD_WORKFLOW_PATH = resolve(CONTENT_ROOT, 'resources', 'recipes', 'project-status.yml');
+/**
+ * The GitHub Actions workflow that drives a Project board's Status field from the
+ * `aidlc:<status>` labels `aidlc roadmap sync` writes (project-board-recipe).
+ *
+ * Shipped as a file and printed on demand, never installed: the user creates the
+ * `project: write` token and owns the CI. This repository runs the same file from
+ * `.github/workflows/`, and a test keeps the two identical.
+ */
+export function loadBoardWorkflow() {
+    return readFileSync(BOARD_WORKFLOW_PATH, 'utf8');
+}
+//# sourceMappingURL=recipes.js.map

package/dist/recipes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.js","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAE5E,oEAAoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;AAEvG;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,YAAY,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.36.1",
+  "version": "1.37.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/resources/recipes/project-status.yml

@@ -0,0 +1,220 @@
+# Drives a GitHub Project's Status field from the `aidlc:<status>` labels that
+# `aidlc roadmap sync` maintains.
+#
+# Get this file with:  aidlc roadmap board-workflow > .github/workflows/aidlc-project-status.yml
+#
+# The projection deliberately stops at issues and labels. Writing a Projects v2
+# field needs a token with `project: write`, and the workflow-provided
+# `GITHUB_TOKEN` cannot do it at any permission level — so the tool cannot move
+# the board itself without every project first creating and storing a token.
+# This workflow is the opt-in other half. The tool prints it and never installs
+# it: the token is yours to create, and the CI is yours to own.
+#
+# The discovery label (`aidlc`) and the `aidlc:<status>` labels are a supported
+# interface. Renaming or removing one is a breaking change in aidlc, announced as
+# such, so binding automation to them is safe.
+#
+# Convergence over replay. A single roadmap move produces two events — the old
+# status label removed, the new one added — and `aidlc roadmap sync` can relabel
+# dozens of issues in one run. So this reads the issue's CURRENT labels at run
+# time instead of trusting the event payload, and the concurrency group collapses
+# a burst per issue to its last event. Ordering then cannot matter: whatever runs
+# last reads the settled state. That is the same property the projection itself
+# has, for the same reason.
+#
+# Not configured reads as inert; half-configured fails loudly. With no
+# `AIDLC_PROJECT_NUMBER` variable the job is skipped entirely, so a fork or a
+# clone never sees a red X for an integration it did not ask for. But if the
+# number IS set and the token is missing, that is somebody's half-finished setup
+# and it says so — the alternative is a workflow that runs green while writing
+# nothing, which is how an automation comes to be believed.
+#
+# Setup:
+#   1. Create the Status options in your Project, named to match STATUS_MAP below
+#      (or edit STATUS_MAP to match the columns you already have).
+#   2. Create a token with `project: write` and store it as the repository secret
+#      AIDLC_PROJECT_TOKEN. A classic token needs the `project` scope; a
+#      fine-grained token can only reach projects owned by an organisation.
+#   3. Set the repository variable AIDLC_PROJECT_NUMBER to the project's number
+#      (the digits in its URL). Optionally set AIDLC_PROJECT_OWNER if the project
+#      belongs to a different user or org than this repository, and
+#      AIDLC_DISCOVERY_LABEL if `roadmap.sync.label` renames the `aidlc` label.
+#
+# Needs gh 2.97.0 or later on the runner, for `gh project item-edit --url`. The
+# workflow checks, and says so if the runner's is older.
+
+name: Project status from AIDLC labels
+
+on:
+  issues:
+    types: [opened, reopened, closed, labeled, unlabeled]
+
+# Read the repository only. The Projects write travels on AIDLC_PROJECT_TOKEN,
+# never on GITHUB_TOKEN, which cannot perform it regardless of what is granted.
+permissions:
+  contents: read
+  issues: read
+
+# One run per issue, latest wins. A sync that relabels thirty issues produces
+# thirty independent groups, so they still proceed in parallel.
+concurrency:
+  group: project-status-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  set-status:
+    # Unset variable = this repository has not opted in. Skip silently.
+    if: vars.AIDLC_PROJECT_NUMBER != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the token is present
+        # Half-configured is an error, not a skip. See the header.
+        #
+        # The secret arrives through `env`, never interpolated into the script
+        # body: a `${{ secrets.* }}` inside `run:` is substituted before bash
+        # parses the line, so a token containing a quote or a backtick would
+        # either break the script or execute as part of it.
+        env:
+          TOKEN: ${{ secrets.AIDLC_PROJECT_TOKEN }}
+        run: |
+          if [ -z "${TOKEN:-}" ]; then
+            echo "::error::AIDLC_PROJECT_NUMBER is set but the AIDLC_PROJECT_TOKEN secret is missing." \
+                 "Projects v2 writes need a token with 'project: write'; GITHUB_TOKEN cannot do it."
+            exit 1
+          fi
+
+      - name: Read the issue's current labels
+        id: labels
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ISSUE: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}
+          # Must match roadmap.sync.label. Without this a renamed label makes every
+          # run skip, green, having written nothing.
+          DISCOVERY: ${{ vars.AIDLC_DISCOVERY_LABEL || 'aidlc' }}
+        run: |
+          set -euo pipefail
+          # Read fresh rather than using github.event.issue.labels: a burst of
+          # relabels must converge on the settled state, not replay snapshots.
+          labels="$(gh issue view "$ISSUE" --repo "$REPO" --json labels --jq '.labels[].name')"
+
+          if ! grep -qxF "$DISCOVERY" <<<"$labels"; then
+            echo "Issue #$ISSUE does not carry the discovery label '$DISCOVERY' — not a projected item."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          status_labels="$(grep '^aidlc:' <<<"$labels" || true)"
+          count="$(grep -c . <<<"$status_labels" || true)"
+
+          if [ "$status_labels" = "" ]; then
+            # Reachable between the two events of a relabel. The run for the
+            # other event settles it; nothing to do here.
+            echo "Issue #$ISSUE carries no aidlc:<status> label yet — nothing to set."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ "$count" -ne 1 ]; then
+            echo "::error::Issue #$ISSUE carries $count aidlc:<status> labels: $(tr '\n' ' ' <<<"$status_labels")." \
+                 "The projection maintains exactly one. Fix the labels before the board can follow them."
+            exit 1
+          fi
+
+          echo "Issue #$ISSUE is $status_labels"
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+          echo "label=$status_labels" >> "$GITHUB_OUTPUT"
+
+      - name: Map the label to a Status option
+        id: map
+        if: steps.labels.outputs.skip == 'false'
+        env:
+          LABEL: ${{ steps.labels.outputs.label }}
+          # The one place the vocabularies are joined. Edit here if your columns
+          # are named differently.
+          STATUS_MAP: >-
+            {"aidlc:inbox":"Inbox",
+             "aidlc:backlog":"Backlog",
+             "aidlc:in-progress":"In Progress",
+             "aidlc:done":"Done",
+             "aidlc:hold":"On Hold"}
+        run: |
+          set -euo pipefail
+          value="$(jq -er --arg k "$LABEL" '.[$k]' <<<"$STATUS_MAP")" || {
+            echo "::error::No STATUS_MAP entry for $LABEL. Add one to this workflow." \
+                 "A new roadmap status was added to aidlc and this map was not updated."
+            exit 1
+          }
+          echo "Target Status: $value"
+          echo "value=$value" >> "$GITHUB_OUTPUT"
+
+      - name: Check the runner's gh can edit an item by URL
+        if: steps.labels.outputs.skip == 'false'
+        run: |
+          # A feature probe, not a version compare: it tests the flag the write
+          # below uses. Without it an older runner image fails there with an
+          # unknown-flag error that names nothing useful.
+          if ! gh project item-edit --help 2>&1 | grep -q -- '--url'; then
+            echo "::error::gh $(gh --version | head -1 | awk '{print $3}') cannot edit a project item by URL." \
+                 "This workflow needs gh 2.97.0 or later."
+            exit 1
+          fi
+
+      - name: Check the Status option exists on the project
+        id: verify
+        if: steps.labels.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.AIDLC_PROJECT_TOKEN }}
+          NUMBER: ${{ vars.AIDLC_PROJECT_NUMBER }}
+          OWNER: ${{ vars.AIDLC_PROJECT_OWNER || github.repository_owner }}
+          WANT: ${{ steps.map.outputs.value }}
+        run: |
+          set -euo pipefail
+          # Checked before the write, so a missing column names itself and the
+          # available options instead of surfacing as an opaque gh failure.
+          fields="$(gh project field-list "$NUMBER" --owner "$OWNER" --format json --limit 100)"
+          options="$(jq -r '.fields[] | select(.name == "Status") | .options[].name' <<<"$fields")"
+
+          if [ "$options" = "" ]; then
+            echo "::error::Project $OWNER/$NUMBER has no single-select field named 'Status'." \
+                 "Fields present: $(jq -r '[.fields[].name] | join(", ")' <<<"$fields")"
+            exit 1
+          fi
+
+          if ! grep -qxF "$WANT" <<<"$options"; then
+            echo "::error::Project $OWNER/$NUMBER has no Status option named '$WANT'." \
+                 "Options present: $(tr '\n' '|' <<<"$options" | sed 's/|$//; s/|/, /g')." \
+                 "Create it, or change STATUS_MAP in this workflow to match your column names."
+            exit 1
+          fi
+
+      - name: Put the issue on the board
+        if: steps.labels.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.AIDLC_PROJECT_TOKEN }}
+          NUMBER: ${{ vars.AIDLC_PROJECT_NUMBER }}
+          OWNER: ${{ vars.AIDLC_PROJECT_OWNER || github.repository_owner }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+        run: |
+          # Deliberately not fatal, and deliberately not silenced. An issue
+          # already on the board is the ordinary case and reports as a failure
+          # here; a genuinely broken token fails at the write below, where one
+          # loud failure is more use than two.
+          if ! out="$(gh project item-add "$NUMBER" --owner "$OWNER" --url "$ISSUE_URL" 2>&1)"; then
+            echo "item-add did not add the issue (already present, or the write below will fail):"
+            echo "$out"
+          fi
+
+      - name: Set the Status field
+        if: steps.labels.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.AIDLC_PROJECT_TOKEN }}
+          NUMBER: ${{ vars.AIDLC_PROJECT_NUMBER }}
+          OWNER: ${{ vars.AIDLC_PROJECT_OWNER || github.repository_owner }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          VALUE: ${{ steps.map.outputs.value }}
+        run: |
+          set -euo pipefail
+          gh project item-edit "$NUMBER" --owner "$OWNER" --url "$ISSUE_URL" \
+            --field Status --value "$VALUE"
+          echo "Set $ISSUE_URL to Status='$VALUE' on project $OWNER/$NUMBER."

package/skills/04-roadmap.md

@@ -189,4 +189,6 @@ Four things to know before you offer it:
 
 Editing an item's body is therefore a publishing act on a repo with `roadmap.sync` configured. That is not a reason to hesitate, but it is a reason not to paste anything into an item you would not put on the tracker. Item prose is sanitized on the way out — HTML comments removed, `@name` and `#123` made inert — so no sync notifies anybody; secrets are not sanitized, and never were. If a user's braindump contains credentials, the existing hard rule applies: flag it and leave them out of the file.
 
+**When the user's Project board does not move**, that is expected: the projection stops at issues and labels, because moving a board needs a `project: write` token that `GITHUB_TOKEN` cannot have. Offer `aidlc roadmap board-workflow > .github/workflows/aidlc-project-status.yml`, which prints a GitHub Actions workflow that sets each issue's Status column from its status label; its header lists the three setup steps (Status columns, the `AIDLC_PROJECT_TOKEN` secret, the `AIDLC_PROJECT_NUMBER` variable). Writing that file is the user's decision — show the command, do not run the redirect unasked. Do not offer to build board writes into `sync` instead.
+
 `aidlc roadmap import <issue-url>` is the opposite direction, and it is one-shot: it writes one `inbox/` item with the issue linked and its executive summary left as `Not yet decided.`, which is then a normal triage. Nothing reconciles afterwards.