amsd-pipeline-shared 0.5.0 → 0.5.2

package/orchestrations/scripts/lib/codeline-packages.js

@@ -0,0 +1,67 @@
+'use strict';
+/**
+ * WHAT EACH CODELINE OF A STORY PROVIDES, AND WHICH RANGE EACH DECLARES FOR WHAT ITS SIBLINGS PROVIDE.
+ *
+ * Live 2026-10-02, AMSD-2974: whether a site's declared range takes a shared library's change was
+ * left to the library lane's detective choosing to report the version; twice it did not, and one
+ * site then assumed its ^7 range would take an 8.x change. These are facts on disk. Each manifest is
+ * read by the ecosystem provider that owns it (ecosystems/*.js, through lib/ecosystem-registry.js):
+ * describe() for name and version, depRanges() for declared ranges. A codeline whose folder or
+ * manifest cannot be read is reported with nothing known, never guessed. What the facts MEAN — does
+ * this range take that change — is the detective's judgement, not this module's.
+ */
+const fs = require('fs');
+const path = require('path');
+const { allManifests } = require('./ecosystem-registry.js');
+
+function readManifest(root) {
+  if (!root) return null;
+  for (const eco of allManifests()) {
+    const file = path.join(root, eco.file);
+    if (!fs.existsSync(file)) continue;
+    try { return { eco, text: fs.readFileSync(file, 'utf8') }; } catch { return null; }
+  }
+  return null;
+}
+
+/**
+ * @param {object}   prd        the lane's PRD (project.outputDirs: [{codeline, path}])
+ * @param {string[]} codelines  the story's codelines
+ * @returns {Array<{codeline, provides: {name, version}|null, declares: object}>}
+ */
+function codelinePackages(prd, codelines) {
+  const dirs = (prd && prd.project && Array.isArray(prd.project.outputDirs)) ? prd.project.outputDirs : [];
+  const rootOf = (cl) => (dirs.find((d) => d && d.codeline === cl) || {}).path || '';
+  const read = (codelines || []).map((cl) => {
+    const m = readManifest(rootOf(cl));
+    let provides = null;
+    let ranges = {};
+    if (m) {
+      try {
+        const d = typeof m.eco.describe === 'function' ? m.eco.describe(m.text) : null;
+        if (d && d.packageName) provides = { name: d.packageName, version: d.version || '' };
+      } catch { provides = null; }
+      try { ranges = (typeof m.eco.depRanges === 'function' && m.eco.depRanges(m.text)) || {}; } catch { ranges = {}; }
+    }
+    // ITS RELEASES, from its own history: a consumer locked to an older line receives a change only if
+    // the provider ships it there too, and the base of that line is the newest release on it (2026-10-06).
+    let releases = [];
+    if (provides) {
+      try {
+        releases = require('child_process').execFileSync('git', ['-C', rootOf(cl), 'tag', '--sort=-v:refname'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+          .split('\n').map((t) => t.trim()).filter(Boolean);
+      } catch { releases = []; }
+    }
+    return { codeline: cl, provides, ranges, releases };
+  });
+  return read.map((r) => {
+    const declares = {};
+    for (const o of read) {
+      if (!o.provides) continue;
+      if (Object.prototype.hasOwnProperty.call(r.ranges, o.provides.name)) declares[o.provides.name] = String(r.ranges[o.provides.name]);
+    }
+    return { codeline: r.codeline, provides: r.provides, declares, releases: r.releases };
+  });
+}
+
+module.exports = { codelinePackages };

package/orchestrations/scripts/lib/codeline-write-perimeter.sh

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+# codeline-write-perimeter.sh — OS-level write perimeter for client codelines.
+#
+# THE HOLE THIS CLOSES
+# --------------------
+# WriteFile.ts has a scope guard that blocks writes outside a story's declared
+# files. Bash.ts has nothing: no cwd restriction, no command filtering, no deny
+# list. It takes an arbitrary cwd and runs anything. Six agents hold `bash`
+# against the client repo — code-graph-detective, team-lead-review,
+# failure-analyst, prd-change-reviewer, plan-reviewer, lint-fix — and
+# AI_GATE_ALLOW_TOOLS=1 also sets EPAM_DANGEROUS_SKIP_APPROVAL=1, so nothing
+# prompts. Any of them can overwrite client source, and one did: run
+# 20260806T113101Z lost ~1050 lines across five files during the spec pass,
+# before the writer had run at all.
+#
+# A tool-level fix cannot hold — it has to be re-applied to every tool anyone
+# adds. This enforces at the filesystem, where no tool can reach around it.
+# Same reasoning, and the same mechanism, as _vendor_lock() in claude.sh, whose
+# own comment says it exists because "an agent can reach for Bash and bypass it".
+#
+# THE RULE
+#   baseline branch in the main checkout  -> READ-ONLY. Agents never write here.
+#   a git worktree, or a story branch     -> writable. Edits land here.
+#   .git                                  -> always writable (commits, resets,
+#                                            git ls-files, index updates).
+#
+# Locking is decided by asking git where we are, not by a path list — so a new
+# codeline is covered the moment discovery finds it, with no configuration.
+#
+# Usage:
+#   . lib/codeline-write-perimeter.sh
+#   perimeter_apply <repo>          # lock iff repo is on the baseline branch
+#   perimeter_seal <repo>           # RUN START: lock whatever branch it is on
+#   perimeter_unlock <repo>         # reopen (writer step, teardown, reset)
+#   perimeter_is_write_allowed <repo>   # exit 0 if writes are permitted here
+
+# NO `set -uo pipefail` here. This file is SOURCED, so any shell option it sets
+# leaks into every caller — git-ops.sh is itself sourced by claude.sh,
+# run-agent-orchestration.sh and codemie-claude.sh, so a stray `set -u` here
+# changes the behaviour of three top-level scripts and broke a commit path the
+# first time this was written. A library configures nothing about its host.
+
+_perim_log()  { echo "[write-perimeter] $*"; }
+
+# The branch this project treats as its integration line. Configured per project
+# (JIRA_BASELINE_BRANCH); no branch name is hardcoded here.
+_perimeter_baseline_branch() {
+    echo "${JIRA_BASELINE_BRANCH:-${EPAM_BASELINE_BRANCH:-main}}"
+}
+
+# A linked worktree has .git as a FILE (a gitdir pointer); a main checkout has
+# it as a directory. That is git's own distinction, so it needs no path list.
+perimeter_is_worktree() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -f "$repo/.git" ]
+}
+
+# Writes are allowed in a worktree, or on any branch that is not the baseline.
+# Detached HEAD counts as "not a story branch" and stays locked — nothing should
+# be authored there.
+perimeter_is_write_allowed() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -e "$repo/.git" ] || return 0   # not a repo: not ours to lock
+    perimeter_is_worktree "$repo" && return 0
+    local branch
+    branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)"
+    [ "$branch" = "HEAD" ] && return 1                  # detached: locked
+    [ "$branch" = "$(_perimeter_baseline_branch)" ] && return 1
+    return 0
+}
+
+# WHAT GETS LOCKED: the client's own tracked source, and nothing else.
+#
+# `git ls-files` is the source of truth, so this assumes nothing about the
+# project's language, build directory or vendor convention — and it already
+# excludes .git, node_modules, .venv, dist and anything else the repo ignores,
+# because none of those are tracked.
+#
+# ENGINE-INTERNAL PATHS ARE NEVER LOCKED. The pipeline writes its own state
+# inside the codeline while a run is in flight — .epam/ (settings.json,
+# codeline-facts.json, dependency-check.json, the vendor-lock and
+# write-perimeter markers) and .codegraph/ (the index, rebuilt on commit).
+# Those are engine artefacts, not client source; locking them would break the
+# run rather than protect anything. They are normally untracked and so absent
+# from ls-files anyway — filtered explicitly so that a project which happens to
+# commit one of them cannot silently freeze the engine's own scratch space.
+# Extendable per project via EPAM_PERIMETER_EXCLUDE (comma-separated prefixes).
+_perimeter_targets() {
+    local repo="$1"
+    local extra="${EPAM_PERIMETER_EXCLUDE:-}"
+    git -C "$repo" ls-files -z 2>/dev/null | while IFS= read -r -d '' f; do
+        case "$f" in
+            .epam/*|.codegraph/*|.epam|.codegraph) continue ;;
+        esac
+        local skip=0 pfx
+        if [ -n "$extra" ]; then
+            IFS=',' read -ra _pfxs <<< "$extra"
+            for pfx in "${_pfxs[@]}"; do
+                pfx="$(echo "$pfx" | tr -d '[:space:]')"
+                [ -n "$pfx" ] && case "$f" in "$pfx"*) skip=1 ;; esac
+            done
+        fi
+        [ "$skip" -eq 1 ] && continue
+        printf '%s\0' "$f"
+    done
+}
+
+perimeter_lock() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -d "$repo" ] || return 0
+    local n=0
+    while IFS= read -r -d '' f; do
+        [ -f "$repo/$f" ] || continue
+        chmod a-w "$repo/$f" 2>/dev/null && n=$((n + 1))
+    done < <(_perimeter_targets "$repo")
+    if [ "$n" -gt 0 ]; then
+        mkdir -p "$repo/.epam" 2>/dev/null || true
+        date -u +%Y-%m-%dT%H:%M:%SZ > "$repo/.epam/.write-perimeter-lock" 2>/dev/null || true
+        _perim_log "LOCKED $n tracked file(s) read-only in $repo (on baseline branch — agents may not write here)"
+    fi
+    return 0
+}
+
+perimeter_unlock() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -d "$repo" ] || return 0
+    local n=0
+    while IFS= read -r -d '' f; do
+        [ -f "$repo/$f" ] || continue
+        chmod u+w "$repo/$f" 2>/dev/null && n=$((n + 1))
+    done < <(_perimeter_targets "$repo")
+    rm -f "$repo/.epam/.write-perimeter-lock" 2>/dev/null || true
+    [ "$n" -gt 0 ] && _perim_log "unlocked $n tracked file(s) in $repo"
+    return 0
+}
+
+# WHICH AGENTS MAY AUTHOR CODE AT ALL.
+#
+# Being on a story branch says WHERE writes may land; this says WHO may make
+# them. Only agents whose job is to author files are listed. Everything else —
+# code-graph-detective, team-lead-review, failure-analyst, prd-change-reviewer,
+# plan-reviewer, the spec agents — reads code to form a judgement and has no
+# reason to modify it. All six of those hold `bash` today, which is how ~1050
+# lines of client source were rewritten during a spec pass with no writer
+# running.
+#
+# The reviewer is deliberately NOT here: it reads the diff and the repo to
+# decide, and returns a verdict. If a reviewer needs to change code, that is a
+# writer re-implementation cycle, which is exactly what Step 3.6 already does.
+#
+# Configurable per project, never hardcoded to one pipeline's role names.
+#
+# This list USED TO name them: "writer,typescript-engineer,test-engineer,repro-test-writer,
+# lint-fix". Two of those five are epam-cli's own agents, carried from its first commit, and a
+# role minted for some other project was in none of them. It would be proposed, briefed, wired,
+# given inputs and tools, assigned a story — and then be unable to write a byte, because this
+# gate is enforced with chmod below the tool layer. Every attempt fails, the ladder climbs, the
+# budget exhausts, and nothing in the logs says the agent was never allowed to write.
+#
+# What remains here is the AUTHORING SEAMS: pipeline stages that write, which are not roster
+# roles at all. Project roles are derived from the roster instead (see below), so a role minted
+# tomorrow is covered without editing this file.
+_PERIMETER_AUTHORING_SEAMS="writer,repro-test-writer,lint-fix"
+
+# _perimeter_project_roles — this project's implementation roles, from the mint's registry.
+#
+# NOT derived as "the roster minus the canonical core". That was tried and it is wrong: of 38
+# non-canonical roles in a live roster, only about nine implement anything — the rest is engine
+# machinery (doc-*, failure-analyst, the vocabulary agents, code-graph-detective). Deriving from
+# that set handed write access to the DETECTIVE, the exact agent whose lack of it is why this
+# perimeter exists. The existing perimeter suite caught it.
+#
+# So the roster states what each agent IS, and this reads the `kind` field. One fact, one place:
+# authorship is a property of an agent, not a separate registry that can disagree with it.
+#
+# THE ENGINE-LEVEL FALLBACK IS GONE. The previous resolver tried EPAM_PROJECT_ROLES_FILE, then the
+# project's own project-roles.json, then agents/project-roles.json — so a client codeline whose
+# project registry was missing inherited THIS repository's implementation roles.
+#
+# Fails CLOSED. No roster, unreadable roster, no project declared → contributes nothing, and only
+# the authoring seams may write. A perimeter that fails open is not a perimeter; one that fails
+# open quietly is worse, so the refusal is stated on stderr.
+_perimeter_project_roles() {
+    if [ -n "${_PERIM_PROJECT_ROLES_CACHE+x}" ]; then
+        printf '%s' "$_PERIM_PROJECT_ROLES_CACHE"
+        return 0
+    fi
+    local _lib_dir _out
+    _lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+    _out=""
+    if [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ]; then
+        # Through the library, so "which agents may author" has ONE definition — the same one the
+        # producer validates against. A jq reimplementation here is a second answer to the
+        # question, and the two drift the first time the roster's shape moves.
+        _out=$("${NODE_BIN:-node}" -e '
+          const m = require(process.argv[1]);
+          try { process.stdout.write(m.agentsOfKind("implementer", process.argv[2]).join(",")); }
+          catch (e) { process.stderr.write("[perimeter] " + (e && e.message) + "\n"); process.exit(1); }
+        ' "${_lib_dir}/project-roster.js" "$EPAM_PROJECT_CONFIG_DIR" 2>/dev/null) || _out=""
+    else
+        echo "[perimeter] no project declared — no agent may author, only the authoring seams." >&2
+    fi
+    _PERIM_PROJECT_ROLES_CACHE="$_out"
+    printf '%s' "$_out"
+}
+
+perimeter_role_may_write() {
+    local role="${1:-${EPAM_AGENT_NAME:-}}"
+    [ -n "$role" ] || return 1                    # unknown caller: no writes
+    local allowed
+    if [ -n "${EPAM_PERIMETER_WRITE_ROLES:-}" ]; then
+        # An explicit operator override replaces the rule entirely — it is the escape hatch,
+        # so it must not be silently unioned with anything derived.
+        allowed="$EPAM_PERIMETER_WRITE_ROLES"
+    else
+        allowed="${_PERIMETER_AUTHORING_SEAMS},$(_perimeter_project_roles)"
+    fi
+    local r
+    IFS=',' read -ra _roles <<< "$allowed"
+    for r in "${_roles[@]}"; do
+        r="$(echo "$r" | tr -d '[:space:]')"
+        [ -n "$r" ] && [ "${role%%:*}" = "$r" ] && return 0   # strip any ":plan" suffix
+    done
+    return 1
+}
+
+# Lock or leave open according to the rule. Safe to call repeatedly.
+perimeter_apply() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -d "$repo" ] || return 0
+    if perimeter_is_write_allowed "$repo"; then
+        _perim_log "$repo is a worktree or story branch — writes permitted, not locking"
+        perimeter_unlock "$repo" >/dev/null
+    else
+        perimeter_lock "$repo"
+    fi
+    return 0
+}
+
+# perimeter_seal <repo>
+#
+# THE RUN-START OPERATION. Locks a real checkout whatever branch it is on.
+#
+# perimeter_apply answers a different question — "is this repo in its write window?" — and
+# unlocks whenever the checkout is on a branch other than the baseline, because that is how
+# ensure_story_branch opens the window after resetting and creating the story branch. Calling
+# it at RUN START reads a LEFTOVER branch as authorisation, and at run start no branch this run
+# created can exist yet.
+#
+# Live 2026-08-09: next.metrolinx.com sat on a story branch left by a killed run, which
+# survived the preflight reset. Run start logged "writes permitted, not locking", the repo
+# stayed writable for the entire run, and a client source file was rewritten into an
+# incompatible component during the SPEC PASS — in a run that paused before the writer and
+# never started one. The two codelines on the baseline were sealed and untouched.
+#
+# The writer is unaffected: ensure_story_branch still calls perimeter_apply after it creates
+# the branch, and that reopens the repo exactly as before.
+#
+# A linked worktree is exempt in both, because git's own structure makes it per-story rather
+# than a name anyone can leave lying around.
+perimeter_seal() {
+    local repo="${1:-}"
+    [ -n "$repo" ] && [ -d "$repo" ] || return 0
+    [ -e "$repo/.git" ] || return 0                     # not a repo: not ours to lock
+    if perimeter_is_worktree "$repo"; then
+        _perim_log "$repo is a linked worktree — per-story by construction, not sealing"
+        return 0
+    fi
+    perimeter_lock "$repo"
+}
+
+# perimeter_seal_all <codeline-root>
+#
+# Seal every repository under the root. The MIRROR of perimeter_release_all, and the reason
+# this exists as a function at all: sealing used to be an inline loop in one launcher while
+# releasing was generic in the engine, so seven of eight projects ran with no perimeter and
+# nothing said so — releasing a repo that was never locked logs nothing.
+#
+# The defect that split cost: live 2026-08-17 run 20260817T231306Z, mock-a's src/fares.ts and
+# test/fares.test.ts were rewritten during the SPEC PASS, before the writer stage was reached,
+# on a project whose launcher never sealed. The same thing had already been recorded on the
+# client estate — ~1050 lines across five files, same stage, which is why this library exists.
+#
+# Idempotent, and never fails the caller: a locked repo re-locks to the same state.
+perimeter_seal_all() {
+    local root="${1:-}"
+    [ -n "$root" ] && [ -d "$root" ] || return 0
+    local _n=0 _cl
+    for _cl in "$root"/*/; do
+        [ -e "${_cl}.git" ] || continue
+        perimeter_seal "${_cl%/}" && _n=$((_n + 1))
+    done
+    [ "$_n" -gt 0 ] && _perim_log "sealed $_n codeline(s) — agents may not write until a story branch exists"
+    return 0
+}
+
+# perimeter_release_all <codeline-root>
+#
+# Give every repository under the root back to the operator. Called when the RUN ends —
+# including the successful ending, which for these runs is the pause before the writer.
+#
+# Nothing did this. perimeter_apply locked at run start, ensure_story_branch reopened a repo
+# that reached a story branch, and the rest stayed read-only forever. Observed twice on
+# 2026-08-06: after a run paused, 23 of the operator's repositories were still locked and
+# nothing said so. The kill path has the same gap.
+#
+# Idempotent, and never fails the caller: it restores permission, it does not touch content.
+perimeter_release_all() {
+    local root="${1:-}"
+    [ -n "$root" ] && [ -d "$root" ] || return 0
+    local _n=0 _cl
+    for _cl in "$root"/*/; do
+        [ -e "${_cl}.git" ] || continue
+        perimeter_unlock "${_cl%/}" >/dev/null 2>&1 && _n=$((_n + 1))
+    done
+    [ "$_n" -gt 0 ] && _perim_log "released $_n codeline(s) — repositories are writable again"
+    return 0
+}

package/orchestrations/scripts/lib/common.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# common.sh — moved verbatim out of claude.sh by tools/split-main-into-modules.py
+# (6 functions). Sourced by claude.sh; SCRIPT_DIR and the globals it sets
+# are in scope exactly as they were. A move, not an edit: every body is byte-identical to
+# the golden recorded at the move (see the identity test).
+
+# KB IS KEYED BY CODELINE, NOT BY AGENT ROLE.
+#
+# The roster is ephemeral by design — regenerated every run, no aggregation — and the mint
+# invents a new NAME each run for what is essentially the same agent. KB-<role>.md therefore
+# named an address that changed every run: 32 files accumulated, each holding what one run
+# learned, none reachable by any later run. The store persisted; the key did not.
+#
+# A codeline is stable, discovered rather than invented, already the investigator key, and the
+# subject of most durable learning — where the SDK is initialised here, how this repository
+# names its tests. Project-wide lessons that belong to no codeline go to the shared file.
+# _resolved_baseline_ref [repo] — the ref every diff in this file compares against.
+#
+# NINE SITES SPELLED THIS `origin/${JIRA_BASELINE_BRANCH:-develop}`. "develop" is a fact of some
+# projects and not of others, so on a codeline whose trunk is named anything else every one of
+# those diffs resolved nothing — and a diff against a ref that does not exist is empty, which
+# reads downstream exactly like "this story changed nothing".
+#
+# The project declares it; otherwise take the repository's OWN checked-out branch, which is at
+# least true. Prefer origin/<branch> when that ref exists, because these are baseline comparisons
+# and the remote is the shared baseline; fall back to the local branch when there is no remote.
+# Prints nothing when nothing resolves, so a caller can refuse rather than diff against a name.
+_resolved_baseline_ref() {
+    local _repo="${1:-${PROJECT_ROOT:-.}}"
+    local _branch="${JIRA_BASELINE_BRANCH:-}"
+    if [ -z "$_branch" ]; then
+        _branch="$(git -C "$_repo" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+        [ "$_branch" = "HEAD" ] && _branch=""
+    fi
+    [ -n "$_branch" ] || return 0
+    if git -C "$_repo" rev-parse --verify --quiet "origin/${_branch}" >/dev/null 2>&1; then
+        printf 'origin/%s' "$_branch"
+    else
+        printf '%s' "$_branch"
+    fi
+}
+
+# Logging functions
+log() {
+    echo -e "${BLUE}[$(date +'%Y-%m-%d %H:%M:%S')]${NC} $1" >&2
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" >> "$PROGRESS_LOG"
+}
+
+error() {
+    echo -e "${RED}[ERROR]${NC} $1" >&2
+    echo "[ERROR] [$(date +'%Y-%m-%d %H:%M:%S')] $1" >> "$PROGRESS_LOG"
+}
+
+success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1" >&2
+    echo "[SUCCESS] [$(date +'%Y-%m-%d %H:%M:%S')] $1" >> "$PROGRESS_LOG"
+}
+
+warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1" >&2
+    echo "[WARNING] [$(date +'%Y-%m-%d %H:%M:%S')] $1" >> "$PROGRESS_LOG"
+}
+
+info() {
+    echo -e "${CYAN}[INFO]${NC} $1" >&2
+}