@aisdlc/core 3.4.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -53,7 +53,7 @@ function canonicalSort(a, b) {
53
53
  function normalizePath(p) {
54
54
  return p.normalize("NFC").replace(/\\/g, "/");
55
55
  }
56
- function walkMdFiles(dir, fileList = [], excludeDirs = [
56
+ var DEFAULT_EXCLUDE_DIRS = [
57
57
  "node_modules",
58
58
  ".git",
59
59
  "dist",
@@ -77,7 +77,8 @@ function walkMdFiles(dir, fileList = [], excludeDirs = [
77
77
  ".vscode",
78
78
  ".vs",
79
79
  ".idea"
80
- ]) {
80
+ ];
81
+ function walkMdFiles(dir, fileList = [], excludeDirs = DEFAULT_EXCLUDE_DIRS) {
81
82
  try {
82
83
  if (!fs9__namespace.existsSync(dir)) return fileList;
83
84
  const files = fs9__namespace.readdirSync(dir).sort(canonicalSort);
@@ -10654,48 +10655,69 @@ function ensureBranchInCascade(branch, parentBranch, rootDir) {
10654
10655
  }
10655
10656
  return true;
10656
10657
  }
10658
+ function switchBranch(branch, rootDir) {
10659
+ child_process.execFileSync("git", ["checkout", branch], { cwd: rootDir, stdio: ["pipe", "pipe", "pipe"] });
10660
+ }
10661
+ function cascadeBranchCheckout(hierarchy, rootDir, created, streamlined) {
10662
+ if (streamlined) {
10663
+ if (ensureBranchInCascade(hierarchy.featureBranch, hierarchy.baseBranch, rootDir)) created.push(hierarchy.featureBranch);
10664
+ switchBranch(hierarchy.featureBranch, rootDir);
10665
+ return hierarchy.featureBranch;
10666
+ }
10667
+ if (ensureBranchInCascade(hierarchy.releaseBranch, hierarchy.baseBranch, rootDir)) created.push(hierarchy.releaseBranch);
10668
+ if (ensureBranchInCascade(hierarchy.featureBranch, hierarchy.releaseBranch, rootDir)) created.push(hierarchy.featureBranch);
10669
+ if (ensureBranchInCascade(hierarchy.taskBranch, hierarchy.featureBranch, rootDir)) created.push(hierarchy.taskBranch);
10670
+ switchBranch(hierarchy.taskBranch, rootDir);
10671
+ return hierarchy.taskBranch;
10672
+ }
10673
+ function buildCheckoutErrorResult(match, hierarchy, created, err) {
10674
+ const message = err instanceof Error ? err.message : String(err);
10675
+ return {
10676
+ success: false,
10677
+ taskId: match.taskId,
10678
+ changeId: match.changeId,
10679
+ releaseBranch: hierarchy.releaseBranch,
10680
+ featureBranch: hierarchy.featureBranch,
10681
+ taskBranch: hierarchy.taskBranch,
10682
+ createdBranches: created,
10683
+ error: `Error durante la creaci\xF3n o checkout de ramas Git: ${message}`
10684
+ };
10685
+ }
10686
+ function buildLocateFailureResult(taskId, locateRes) {
10687
+ return {
10688
+ success: false,
10689
+ taskId,
10690
+ createdBranches: [],
10691
+ error: locateRes.error,
10692
+ availableTasks: locateRes.availableTasks
10693
+ };
10694
+ }
10695
+ function buildCheckoutSuccessResult(match, hierarchy, created, switchedBranch, streamlined) {
10696
+ return {
10697
+ success: true,
10698
+ taskId: match.taskId,
10699
+ changeId: match.changeId,
10700
+ releaseBranch: hierarchy.releaseBranch,
10701
+ featureBranch: hierarchy.featureBranch,
10702
+ taskBranch: streamlined ? void 0 : hierarchy.taskBranch,
10703
+ createdBranches: created,
10704
+ switchedBranch
10705
+ };
10706
+ }
10657
10707
  function checkoutTaskBranch(taskId, options = {}) {
10658
10708
  const rootDir = options.rootDir || process.cwd();
10659
10709
  const locateRes = locateTaskInActiveChanges(taskId, rootDir);
10660
10710
  if (!locateRes.found || !locateRes.match) {
10661
- return {
10662
- success: false,
10663
- taskId,
10664
- createdBranches: [],
10665
- error: locateRes.error,
10666
- availableTasks: locateRes.availableTasks
10667
- };
10711
+ return buildLocateFailureResult(taskId, locateRes);
10668
10712
  }
10669
10713
  const match = locateRes.match;
10670
- const { baseBranch, releaseBranch, featureBranch, taskBranch } = resolveBranchHierarchy(match, rootDir);
10671
- const createdBranches = [];
10714
+ const hierarchy = resolveBranchHierarchy(match, rootDir);
10715
+ const created = [];
10672
10716
  try {
10673
- if (ensureBranchInCascade(releaseBranch, baseBranch, rootDir)) createdBranches.push(releaseBranch);
10674
- if (ensureBranchInCascade(featureBranch, releaseBranch, rootDir)) createdBranches.push(featureBranch);
10675
- if (ensureBranchInCascade(taskBranch, featureBranch, rootDir)) createdBranches.push(taskBranch);
10676
- child_process.execFileSync("git", ["checkout", taskBranch], { cwd: rootDir, stdio: ["pipe", "pipe", "pipe"] });
10677
- return {
10678
- success: true,
10679
- taskId: match.taskId,
10680
- changeId: match.changeId,
10681
- releaseBranch,
10682
- featureBranch,
10683
- taskBranch,
10684
- createdBranches,
10685
- switchedBranch: taskBranch
10686
- };
10717
+ const switched = cascadeBranchCheckout(hierarchy, rootDir, created, options.streamlined);
10718
+ return buildCheckoutSuccessResult(match, hierarchy, created, switched, options.streamlined);
10687
10719
  } catch (err) {
10688
- const message = err instanceof Error ? err.message : String(err);
10689
- return {
10690
- success: false,
10691
- taskId: match.taskId,
10692
- changeId: match.changeId,
10693
- releaseBranch,
10694
- featureBranch,
10695
- taskBranch,
10696
- createdBranches,
10697
- error: `Error durante la creaci\xF3n o checkout de ramas Git: ${message}`
10698
- };
10720
+ return buildCheckoutErrorResult(match, hierarchy, created, err);
10699
10721
  }
10700
10722
  }
10701
10723
  var TRAILER_REGEXES = {
@@ -10721,18 +10743,21 @@ function resolveAuthorType(authorTypeMatch, aiModelMatch) {
10721
10743
  }
10722
10744
  return "human";
10723
10745
  }
10746
+ function resolveTrailerOrScope(match, text, fallbackRegex) {
10747
+ if (match) return match[1].trim();
10748
+ const subMatch = text.match(fallbackRegex);
10749
+ return subMatch ? subMatch[1].toUpperCase() : void 0;
10750
+ }
10724
10751
  function parseCommitTrailers(rawMessage) {
10725
10752
  const text = rawMessage || "";
10726
- const taskIdMatch = text.match(TRAILER_REGEXES.taskId);
10727
- const parentRefMatch = text.match(TRAILER_REGEXES.parentRef);
10728
10753
  const authorTypeMatch = text.match(TRAILER_REGEXES.authorType);
10729
10754
  const aiModelMatch = text.match(TRAILER_REGEXES.aiModel);
10730
10755
  const authorType = resolveAuthorType(authorTypeMatch, aiModelMatch);
10731
10756
  const rawModel = aiModelMatch ? aiModelMatch[1].trim() : void 0;
10732
10757
  const aiModel = rawModel && rawModel !== "n/a" ? rawModel : void 0;
10733
10758
  return {
10734
- taskId: taskIdMatch ? taskIdMatch[1].trim() : void 0,
10735
- parentRef: parentRefMatch ? parentRefMatch[1].trim() : void 0,
10759
+ taskId: resolveTrailerOrScope(text.match(TRAILER_REGEXES.taskId), text, /\b(TSK-[0-9A-Za-z_-]+)\b/i),
10760
+ parentRef: resolveTrailerOrScope(text.match(TRAILER_REGEXES.parentRef), text, /\b((?:CHG|FEAT|BUG|FIX|PATCH)-[0-9A-Za-z_-]+)\b/i),
10736
10761
  authorType,
10737
10762
  aiModel,
10738
10763
  promptTokens: parseTrailerInt(text.match(TRAILER_REGEXES.promptTokens)),
@@ -11135,7 +11160,17 @@ fi
11135
11160
  # Extract Task-ID and Parent-Ref from 4-tier branch hierarchy
11136
11161
  # Patterns: task/<PARENT-ID>/<TSK-ID>-slug | feat/<FEAT-ID>-slug | bug/<BUG-ID>-slug
11137
11162
  TASK_ID=$(echo "$CURRENT_BRANCH" | grep -oE "TSK-[0-9A-Za-z-]+" || echo "")
11163
+ if [ -z "$TASK_ID" ]; then
11164
+ TASK_ID=$(head -n 1 "$COMMIT_MSG_FILE" 2>/dev/null | grep -oE "TSK-[0-9A-Za-z_-]+" | head -n 1 || echo "")
11165
+ fi
11166
+ if [ -z "$TASK_ID" ] && [ -f "$TELEMETRY_FILE" ]; then
11167
+ TASK_ID=$(grep -oE '"taskId"s*:s*"[^"]+"' "$TELEMETRY_FILE" 2>/dev/null | sed -E 's/.*"taskId"s*:s*"([^"]+)".*/\\1/' || echo "")
11168
+ fi
11169
+
11138
11170
  PARENT_REF=$(echo "$CURRENT_BRANCH" | grep -oE "(CHG|FEAT|BUG|FIX|PATCH)-[0-9A-Za-z-]+" | head -n 1 || echo "")
11171
+ if [ -z "$PARENT_REF" ]; then
11172
+ PARENT_REF=$(head -n 1 "$COMMIT_MSG_FILE" 2>/dev/null | grep -oE "(CHG|FEAT|BUG|FIX|PATCH)-[0-9A-Za-z_-]+" | head -n 1 || echo "")
11173
+ fi
11139
11174
 
11140
11175
  TELEMETRY_FILE=".ai-sdlc/session-telemetry.json"
11141
11176
  AUTHOR_TYPE="human"
@@ -11275,51 +11310,105 @@ function accumulateRecord(target, record) {
11275
11310
  target.completionTokens += record.trailers.completionTokens;
11276
11311
  target.estimatedCostUsd = calculateEstimatedCost(target.promptTokens, target.completionTokens);
11277
11312
  }
11278
- function aggregateCommitKpiRecords(records, baseRef = "main", headRef = "HEAD") {
11279
- const humanSummary = createEmptySummary();
11280
- const byModel = {};
11281
- let totalLinesAdded = 0;
11282
- let totalLinesDeleted = 0;
11283
- let totalActiveTime = 0;
11284
- let totalPrompt = 0;
11285
- let totalCompletion = 0;
11313
+ function accumulateAuthorSummaries(records, humanSummary, byModel) {
11314
+ let linesAdded = 0;
11315
+ let linesDeleted = 0;
11316
+ let activeTime = 0;
11317
+ let prompt = 0;
11318
+ let completion = 0;
11286
11319
  let isBugPr = false;
11287
11320
  for (const record of records) {
11288
- totalLinesAdded += record.linesAdded;
11289
- totalLinesDeleted += record.linesDeleted;
11290
- totalActiveTime += record.trailers.activeTimeSeconds;
11291
- totalPrompt += record.trailers.promptTokens;
11292
- totalCompletion += record.trailers.completionTokens;
11321
+ linesAdded += record.linesAdded;
11322
+ linesDeleted += record.linesDeleted;
11323
+ activeTime += record.trailers.activeTimeSeconds;
11324
+ prompt += record.trailers.promptTokens;
11325
+ completion += record.trailers.completionTokens;
11293
11326
  if (record.isBugFix) isBugPr = true;
11294
11327
  if (record.trailers.authorType === "agent") {
11295
11328
  const modelName = record.trailers.aiModel || "agent-generic";
11296
- if (!byModel[modelName]) {
11297
- byModel[modelName] = createEmptySummary();
11298
- }
11329
+ if (!byModel[modelName]) byModel[modelName] = createEmptySummary();
11299
11330
  accumulateRecord(byModel[modelName], record);
11300
11331
  } else {
11301
11332
  accumulateRecord(humanSummary, record);
11302
11333
  }
11303
11334
  }
11304
- const totalTokens = totalPrompt + totalCompletion;
11305
- const estimatedCostUsd = calculateEstimatedCost(totalPrompt, totalCompletion);
11335
+ return { linesAdded, linesDeleted, activeTime, prompt, completion, isBugPr };
11336
+ }
11337
+ function initTaskKpi(taskId) {
11338
+ return {
11339
+ taskId,
11340
+ commits: 0,
11341
+ fixCommits: 0,
11342
+ linesAdded: 0,
11343
+ linesDeleted: 0,
11344
+ codeChurnPercent: 0,
11345
+ totalTokens: 0,
11346
+ activeTimeSeconds: 0,
11347
+ reworkTokens: 0,
11348
+ reworkTokensPercent: 0,
11349
+ reworkTimeSeconds: 0,
11350
+ reworkTimePercent: 0,
11351
+ isFirstTimeRight: true
11352
+ };
11353
+ }
11354
+ function processTaskCommit(tStat, record) {
11355
+ const recTokens = record.trailers.promptTokens + record.trailers.completionTokens;
11356
+ tStat.commits += 1;
11357
+ tStat.linesAdded += record.linesAdded;
11358
+ tStat.linesDeleted += record.linesDeleted;
11359
+ tStat.totalTokens += recTokens;
11360
+ tStat.activeTimeSeconds += record.trailers.activeTimeSeconds;
11361
+ const isRework = record.isBugFix || /^(fix|bug|remediate|refactor)(([^)]+))?:/i.test((record.subject || "").trim());
11362
+ if (isRework) {
11363
+ tStat.fixCommits += 1;
11364
+ tStat.reworkTokens += recTokens;
11365
+ tStat.reworkTimeSeconds += record.trailers.activeTimeSeconds;
11366
+ }
11367
+ }
11368
+ function accumulateTaskSummaries(records) {
11369
+ const byTask = {};
11370
+ for (const record of records) {
11371
+ const tid = record.trailers.taskId || record.subject.match(/\b(TSK-[0-9A-Za-z_-]+)\b/i)?.[1]?.toUpperCase();
11372
+ if (!tid) continue;
11373
+ if (!byTask[tid]) byTask[tid] = initTaskKpi(tid);
11374
+ processTaskCommit(byTask[tid], record);
11375
+ }
11376
+ for (const t of Object.values(byTask)) {
11377
+ const churn = t.linesAdded > 0 ? t.linesDeleted / t.linesAdded * 100 : 0;
11378
+ t.codeChurnPercent = Math.round(Math.min(churn, 100) * 10) / 10;
11379
+ t.reworkTokensPercent = t.totalTokens > 0 ? Math.round(t.reworkTokens / t.totalTokens * 1e3) / 10 : 0;
11380
+ t.reworkTimePercent = t.activeTimeSeconds > 0 ? Math.round(t.reworkTimeSeconds / t.activeTimeSeconds * 1e3) / 10 : 0;
11381
+ t.isFirstTimeRight = t.fixCommits === 0 && t.codeChurnPercent < 25;
11382
+ }
11383
+ return byTask;
11384
+ }
11385
+ function assemblePrKpiAggregation(baseRef, headRef, records, totals, humanSummary, byModel, byTask) {
11386
+ const totalTokens = totals.prompt + totals.completion;
11306
11387
  return {
11307
11388
  baseRef,
11308
11389
  headRef,
11309
11390
  totalCommits: records.length,
11310
- linesAdded: totalLinesAdded,
11311
- linesDeleted: totalLinesDeleted,
11312
- totalActiveTimeSeconds: totalActiveTime,
11313
- totalPromptTokens: totalPrompt,
11314
- totalCompletionTokens: totalCompletion,
11391
+ linesAdded: totals.linesAdded,
11392
+ linesDeleted: totals.linesDeleted,
11393
+ totalActiveTimeSeconds: totals.activeTime,
11394
+ totalPromptTokens: totals.prompt,
11395
+ totalCompletionTokens: totals.completion,
11315
11396
  totalTokens,
11316
- estimatedCostUsd,
11397
+ estimatedCostUsd: calculateEstimatedCost(totals.prompt, totals.completion),
11317
11398
  humanSummary,
11318
11399
  byModel,
11319
- isBugPr,
11320
- commitRecords: records
11400
+ isBugPr: totals.isBugPr,
11401
+ commitRecords: records,
11402
+ byTask
11321
11403
  };
11322
11404
  }
11405
+ function aggregateCommitKpiRecords(records, baseRef = "main", headRef = "HEAD") {
11406
+ const humanSummary = createEmptySummary();
11407
+ const byModel = {};
11408
+ const totals = accumulateAuthorSummaries(records, humanSummary, byModel);
11409
+ const byTask = accumulateTaskSummaries(records);
11410
+ return assemblePrKpiAggregation(baseRef, headRef, records, totals, humanSummary, byModel, byTask);
11411
+ }
11323
11412
  function aggregatePrKpis(baseRef, headRef = "HEAD", options = {}) {
11324
11413
  const records = extractCommitKpisFromRange(baseRef, headRef, options);
11325
11414
  return aggregateCommitKpiRecords(records, baseRef, headRef);
@@ -11328,12 +11417,7 @@ function formatMinutes(seconds) {
11328
11417
  const mins = Math.round(seconds / 60);
11329
11418
  return mins > 0 ? `${mins} min` : `${seconds}s`;
11330
11419
  }
11331
- function formatPrKpiMarkdown(kpi) {
11332
- const models = Object.keys(kpi.byModel);
11333
- const modelHeaders = models.map((m) => `Agent (${m})`).join(" | ");
11334
- const modelSeparator = models.map(() => ":---:").join(" | ");
11335
- const headers = `| Metric | Human |${models.length > 0 ? ` ${modelHeaders} |` : ""} Total PR |`;
11336
- const sep2 = `| :--- | :---: |${models.length > 0 ? ` ${modelSeparator} |` : ""} :---: |`;
11420
+ function buildPrKpiRows(kpi, models) {
11337
11421
  const human = kpi.humanSummary;
11338
11422
  const commitCols = models.map((m) => kpi.byModel[m].commits).join(" | ");
11339
11423
  const linesCols = models.map((m) => `+${kpi.byModel[m].linesAdded} / -${kpi.byModel[m].linesDeleted}`).join(" | ");
@@ -11344,13 +11428,41 @@ function formatPrKpiMarkdown(kpi) {
11344
11428
  const totalTime = formatMinutes(kpi.totalActiveTimeSeconds);
11345
11429
  const totalTokensStr = `${kpi.totalTokens.toLocaleString("en-US")} tokens`;
11346
11430
  const totalCostStr = `$${kpi.estimatedCostUsd.toFixed(2)} USD`;
11347
- const rows = [
11431
+ return [
11348
11432
  `| **Commits** | ${human.commits} |${models.length > 0 ? ` ${commitCols} |` : ""} **${kpi.totalCommits}** |`,
11349
11433
  `| **Lines Added / Deleted** | +${human.linesAdded} / -${human.linesDeleted} |${models.length > 0 ? ` ${linesCols} |` : ""} **${totalLines}** |`,
11350
11434
  `| **Active Development Time** | ${formatMinutes(human.activeTimeSeconds)} |${models.length > 0 ? ` ${timeCols} |` : ""} **${totalTime}** |`,
11351
11435
  `| **Tokens Consumed (In+Out)** | 0 |${models.length > 0 ? ` ${tokenCols} |` : ""} **${totalTokensStr}** |`,
11352
11436
  `| **Estimated Cost (USD)** | \u2014 (Human labor) |${models.length > 0 ? ` ${costCols} |` : ""} **${totalCostStr}** |`
11353
11437
  ];
11438
+ }
11439
+ function formatTaskKpiRows(byTask) {
11440
+ const taskIds = Object.keys(byTask || {});
11441
+ if (taskIds.length === 0) return [];
11442
+ const rows = [
11443
+ "",
11444
+ "#### \u{1F4CB} Task-Level Rework & Code Churn Breakdown",
11445
+ "",
11446
+ "| Task ID | Commits (Total / Fix) | Lines (+ / -) | Code Churn % | Rework Tokens % | Rework Time % | Status |",
11447
+ "| :--- | :---: | :---: | :---: | :---: | :---: | :---: |"
11448
+ ];
11449
+ for (const tid of taskIds) {
11450
+ const t = byTask[tid];
11451
+ const statusLabel = t.isFirstTimeRight ? "\u2714 First-Time-Right" : `\u26A0 ${t.fixCommits} rework commit${t.fixCommits === 1 ? "" : "s"}`;
11452
+ rows.push(
11453
+ `| \`${t.taskId}\` | ${t.commits} (${t.fixCommits} fix) | +${t.linesAdded} / -${t.linesDeleted} | ${t.codeChurnPercent}% | ${t.reworkTokensPercent}% | ${t.reworkTimePercent}% | ${statusLabel} |`
11454
+ );
11455
+ }
11456
+ return rows;
11457
+ }
11458
+ function formatPrKpiMarkdown(kpi) {
11459
+ const models = Object.keys(kpi.byModel);
11460
+ const modelHeaders = models.map((m) => `Agent (${m})`).join(" | ");
11461
+ const modelSeparator = models.map(() => ":---:").join(" | ");
11462
+ const headers = `| Metric | Human |${models.length > 0 ? ` ${modelHeaders} |` : ""} Total PR |`;
11463
+ const sep2 = `| :--- | :---: |${models.length > 0 ? ` ${modelSeparator} |` : ""} :---: |`;
11464
+ const rows = buildPrKpiRows(kpi, models);
11465
+ const taskRowsList = formatTaskKpiRows(kpi.byTask);
11354
11466
  return [
11355
11467
  KPI_SUMMARY_START_TAG,
11356
11468
  "### \u{1F4CA} AI-SDLC: Aggregated PR KPI Summary",
@@ -11358,6 +11470,7 @@ function formatPrKpiMarkdown(kpi) {
11358
11470
  headers,
11359
11471
  sep2,
11360
11472
  ...rows,
11473
+ ...taskRowsList,
11361
11474
  "",
11362
11475
  `> **Branch Attribution:** ${kpi.isBugPr ? "\u{1F6A8} *Defect Fix / Bugfix*" : "\u2728 *New Feature*"} (Range: \`${kpi.baseRef}..${kpi.headRef}\`)`,
11363
11476
  KPI_SUMMARY_END_TAG
@@ -11486,6 +11599,31 @@ function resolveReleaseBaseBranch(release, explicitBase, options = {}) {
11486
11599
  }
11487
11600
  return release;
11488
11601
  }
11602
+ function assembleReleaseReport(refs, totals, costs, stats) {
11603
+ return {
11604
+ releaseBranch: refs.release,
11605
+ baseBranch: refs.base,
11606
+ generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
11607
+ totalCommits: refs.commitCount,
11608
+ totalLinesAdded: totals.linesAdded,
11609
+ totalLinesDeleted: totals.linesDeleted,
11610
+ totalKloc: stats.totalKloc,
11611
+ totalBugs: stats.bugList.length,
11612
+ globalDefectDensity: stats.globalDefectDensity,
11613
+ totalTimeSeconds: totals.time,
11614
+ totalTokens: totals.tokens,
11615
+ totalCostUsd: costs.totalCost,
11616
+ reworkTimeSeconds: totals.reworkTime,
11617
+ reworkTokens: totals.reworkTokens,
11618
+ reworkCostUsd: costs.reworkCost,
11619
+ reworkTimePercent: costs.ratios.timePercent,
11620
+ reworkTokensPercent: costs.ratios.tokensPercent,
11621
+ reworkCostPercent: costs.ratios.costPercent,
11622
+ authorStats: stats.authorStats,
11623
+ bugList: stats.bugList,
11624
+ taskReworkStats: Object.values(stats.taskMap)
11625
+ };
11626
+ }
11489
11627
  function aggregateReleaseKpis(releaseBranch, baseBranch, options = {}) {
11490
11628
  const cwd = options.cwd || process.cwd();
11491
11629
  const effectiveBase = resolveReleaseBaseBranch(releaseBranch, baseBranch, { cwd });
@@ -11500,38 +11638,48 @@ function aggregateReleaseKpis(releaseBranch, baseBranch, options = {}) {
11500
11638
  }
11501
11639
  const authorStats = finalizeAuthorStats(statsMap);
11502
11640
  const totalKloc = Math.round((totals.linesAdded + totals.linesDeleted) / 1e3 * 100) / 100;
11503
- const totalBugs = bugList.length;
11504
- const globalDefectDensity = totalKloc > 0 ? Math.round(totalBugs / totalKloc * 100) / 100 : totalBugs;
11505
- const totalCostUsd = calculateCost(totals.tokens * 0.8, totals.tokens * 0.2);
11506
- const reworkCostUsd = calculateCost(totals.reworkTokens * 0.8, totals.reworkTokens * 0.2);
11507
- const ratios = computeReworkRatios(totals.time, totals.tokens, totalCostUsd, totals.reworkTime, totals.reworkTokens, reworkCostUsd);
11508
- return {
11509
- releaseBranch: resolvedRelease,
11510
- baseBranch: resolvedBase,
11511
- generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
11512
- totalCommits: records.length,
11513
- totalLinesAdded: totals.linesAdded,
11514
- totalLinesDeleted: totals.linesDeleted,
11515
- totalKloc,
11516
- totalBugs,
11517
- globalDefectDensity,
11518
- totalTimeSeconds: totals.time,
11519
- totalTokens: totals.tokens,
11520
- totalCostUsd,
11521
- reworkTimeSeconds: totals.reworkTime,
11522
- reworkTokens: totals.reworkTokens,
11523
- reworkCostUsd,
11524
- reworkTimePercent: ratios.timePercent,
11525
- reworkTokensPercent: ratios.tokensPercent,
11526
- reworkCostPercent: ratios.costPercent,
11527
- authorStats,
11528
- bugList
11529
- };
11641
+ const globalDefectDensity = totalKloc > 0 ? Math.round(bugList.length / totalKloc * 100) / 100 : bugList.length;
11642
+ const totalCost = calculateCost(totals.tokens * 0.8, totals.tokens * 0.2);
11643
+ const reworkCost = calculateCost(totals.reworkTokens * 0.8, totals.reworkTokens * 0.2);
11644
+ const ratios = computeReworkRatios(totals.time, totals.tokens, totalCost, totals.reworkTime, totals.reworkTokens, reworkCost);
11645
+ const taskMap = accumulateTaskSummaries(records);
11646
+ return assembleReleaseReport(
11647
+ { release: resolvedRelease, base: resolvedBase, commitCount: records.length },
11648
+ totals,
11649
+ { totalCost, reworkCost, ratios },
11650
+ { authorStats, bugList, taskMap, totalKloc, globalDefectDensity }
11651
+ );
11530
11652
  }
11531
11653
  function formatHours(seconds) {
11532
11654
  const hours = (seconds / 3600).toFixed(1);
11533
11655
  return `${hours}h (${Math.round(seconds / 60)} min)`;
11534
11656
  }
11657
+ function buildTaskReworkSection(taskReworkStats) {
11658
+ if (!taskReworkStats || taskReworkStats.length === 0) return [];
11659
+ const rows = taskReworkStats.map((t) => {
11660
+ const status = t.isFirstTimeRight ? "\u2714 First-Time-Right" : `\u26A0 ${t.fixCommits} fix commit${t.fixCommits === 1 ? "" : "s"}`;
11661
+ return `| \`${t.taskId}\` | ${t.commits} (${t.fixCommits} fix) | +${t.linesAdded} / -${t.linesDeleted} | ${t.codeChurnPercent}% | ${t.reworkTokensPercent}% | ${t.reworkTimePercent}% | ${status} |`;
11662
+ });
11663
+ return [
11664
+ "",
11665
+ "## 4. Granular Rework & Code Churn Breakdown per Task (TSK-*)",
11666
+ "",
11667
+ "| Task ID | Commits (Total / Fix) | Lines (+ / -) | Code Churn % | Rework Tokens % | Rework Time % | Status |",
11668
+ "| :--- | :---: | :---: | :---: | :---: | :---: | :---: |",
11669
+ ...rows
11670
+ ];
11671
+ }
11672
+ function buildReworkMetricsSection(report) {
11673
+ return [
11674
+ "## 3. Rework Metrics & Cost of Defect Remediation",
11675
+ "",
11676
+ "| Rework Dimension | Absolute Rework | Total Release Value | Rework Ratio (%) |",
11677
+ "| :--- | :---: | :---: | :---: |",
11678
+ `| **Rework Engineering Time** | ${formatHours(report.reworkTimeSeconds)} | ${formatHours(report.totalTimeSeconds)} | **${report.reworkTimePercent}%** |`,
11679
+ `| **Rework Token Consumption** | ${report.reworkTokens.toLocaleString("en-US")} tokens | ${report.totalTokens.toLocaleString("en-US")} tokens | **${report.reworkTokensPercent}%** |`,
11680
+ `| **Estimated Rework Cost (USD)** | $${report.reworkCostUsd.toFixed(2)} | $${report.totalCostUsd.toFixed(2)} | **${report.reworkCostPercent}%** |`
11681
+ ];
11682
+ }
11535
11683
  function formatReleaseKpiMarkdown(report) {
11536
11684
  const authorRows = report.authorStats.map((stat) => {
11537
11685
  return `| **${stat.authorOrModel}** | ${stat.commits} | ${stat.klocProduced} | ${stat.bugsInjected} | **${stat.defectInjectionRate}** | ${formatHours(stat.totalTimeSeconds)} | ${stat.totalTokens.toLocaleString("en-US")} | $${stat.estimatedCostUsd.toFixed(2)} |`;
@@ -11554,23 +11702,17 @@ function formatReleaseKpiMarkdown(report) {
11554
11702
  ...authorRows,
11555
11703
  `| **TOTAL RELEASE** | **${report.totalCommits}** | **${report.totalKloc}** | **${report.totalBugs}** | **${report.globalDefectDensity}** | **${formatHours(report.totalTimeSeconds)}** | **${report.totalTokens.toLocaleString("en-US")}** | **$${report.totalCostUsd.toFixed(2)} USD** |`,
11556
11704
  "",
11557
- "---",
11705
+ "## 2. Injected Defects Catalog & Root Cause Traceability",
11558
11706
  "",
11559
- "## 2. Bug Rework Cost vs. Total Release Cost",
11707
+ "| Commit SHA | Defect Subject / Description | Injected By | Parent Feature | Remediation Time | Rework Tokens |",
11708
+ "| :--- | :--- | :---: | :---: | :---: | :---: |",
11709
+ ...bugRows,
11560
11710
  "",
11561
- "| Cost Dimension | Total Release Investment | Invested in Bug Fixes | Rework Cost Ratio | Observational Status |",
11562
- "| :--- | :---: | :---: | :---: | :---: |",
11563
- `| **Cycle Time** | ${formatHours(report.totalTimeSeconds)} | ${formatHours(report.reworkTimeSeconds)} | **${report.reworkTimePercent}%** | ${report.reworkTimePercent <= 10 ? "\u{1F7E2} OPTIMAL (\u226410%)" : "\u{1F7E1} ALERT (>10%)"} |`,
11564
- `| **AI Tokens** | ${report.totalTokens.toLocaleString("en-US")} tokens | ${report.reworkTokens.toLocaleString("en-US")} tokens | **${report.reworkTokensPercent}%** | ${report.reworkTokensPercent <= 10 ? "\u{1F7E2} OPTIMAL (\u226410%)" : "\u{1F7E1} ALERT (>10%)"} |`,
11565
- `| **Computational Cost ($)** | $${report.totalCostUsd.toFixed(2)} USD | $${report.reworkCostUsd.toFixed(2)} USD | **${report.reworkCostPercent}%** | ${report.reworkCostPercent <= 10 ? "\u{1F7E2} OPTIMAL (\u226410%)" : "\u{1F7E1} ALERT (>10%)"} |`,
11711
+ ...buildReworkMetricsSection(report),
11712
+ ...buildTaskReworkSection(report.taskReworkStats),
11566
11713
  "",
11567
11714
  "---",
11568
- "",
11569
- "## 3. Defects and Fix Commits Breakdown",
11570
- "",
11571
- "| Commit SHA | Description | Attribution | Reference | Fix Time | Fix Tokens |",
11572
- "| :--- | :--- | :--- | :--- | :---: | :---: |",
11573
- ...bugRows
11715
+ "*Report dynamically generated by AI-SDLC KPI & Release Governance Engine.*"
11574
11716
  ].join("\n");
11575
11717
  }
11576
11718
  function writeReleaseKpiReport(report, options = {}) {
@@ -14859,233 +15001,26 @@ var LIFECYCLE_SKILL_TEMPLATES = [
14859
15001
  {
14860
15002
  id: "aisdlc-greenfield",
14861
15003
  title: "Greenfield Project Inception & Delivery Playbook",
14862
- description: "Orchestrate end-to-end AI-SDLC onboarding and Phase 0 Inception for brand-new (Greenfield) projects, from repository initialization (aisdlc init) and NAF v4 Vision (ARCH-INTRO-*) through ProductShape, STRIDE Threat Modeling, arc42 Architecture, transversal auditor/adversary verification loops, and initial SDD increment delivery.",
15004
+ description: "Orchestrate end-to-end AI-SDLC onboarding and Phase 0 Inception for brand-new (Greenfield) projects, from repository initialization (aisdlc init) and NAF v4 Vision (ARCH-INTRO-*) through ProductShape, STRIDE Threat Modeling, arc42 Architecture, 2-checkpoint transversal auditor/adversary verification, and topological wave SDD delivery.",
14863
15005
  references: "[`process/02_product_definition.md`](../../process/02_product_definition.md), [`process/04b_data_protection_and_privacy.md`](../../process/04b_data_protection_and_privacy.md), [`process/05_architecture_arc42_nafv4.md`](../../process/05_architecture_arc42_nafv4.md), [`process/06_spec_driven_development.md`](../../process/06_spec_driven_development.md), and [`process/09_agent_protocols.md`](../../process/09_agent_protocols.md).",
14864
15006
  globs: "product/**, specs/product/**, architecture/**, templates/**",
14865
- body: `## Purpose & Trigger
14866
- Use this skill when starting a **brand-new software project from scratch (Greenfield)** or when \`specs/product/\` has no canonical baseline yet. It coordinates the sequential execution of AI-SDLC MCP/CLI tools and specialized role agents so no code is written before product vision, security enclaves, privacy-by-design controls, and architecture contracts exist.
14867
-
14868
- ## Mandatory Transversal Quality & Adversarial Protocol
14869
- Every authoring agent deliverable across Phase 0 and Inception undergoes mandatory quality auditing and adversarial stress-testing before downstream progression:
14870
- - **Concurrent Inspection**: Immediately following the execution of any authoring agent (\`agent-product-analyst\`, \`agent-threat-modeler\`, \`agent-privacy-officer\`, \`agent-system-architect\`), invoke [\`agent-auditor\`](../agent-auditor/SKILL.md) (evaluating YAGNI, structural debt, and simplification) and [\`agent-adversary\`](../agent-adversary/SKILL.md) (stress-testing logic traps, SPOFs, attack vectors, or broken invariants) **concurrently** in clean, isolated context windows.
14871
- - **Non-Invasive Review**: Neither auditor nor adversary modifies deliverables directly; both deliver structured reports citing canonical IDs and SHA-256 digests.
14872
- - **Consolidated Remediation Re-Execution**: Consolidate findings and emit the Workflow Handoff back to the authoring agent, who is re-executed to resolve blocking defects and apply simplifications.
14873
- - **Anti-Ping-Pong Guardrail (Max 2 Rounds)**: Bounded strictly to a maximum of **2 correction rounds** per phase/deliverable. If non-blocking advisories remain after round 2, proceed to the downstream phase; if blocking defects persist after round 2, escalate immediately to the Human Tech Lead.
14874
- - **Exclusion of Downstream Review & Validation Roles**: Review and validation agents (\`agent-expert-user\`, \`agent-code-reviewer\`, \`agent-security-auditor\`, \`agent-compliance-checker\`) evaluate finished deliverables and are excluded from being audited by this loop.
14875
-
14876
- ## End-to-End Execution Playbook
14877
-
14878
- ### Step 1: Repository Turnkey Initialization
14879
- 1. If the workspace has not been initialized with AI-SDLC schemas, policies, and templates, run MCP tool \`new\` (or CLI \`npx @aisdlc/cli init\`).
14880
- 2. Install the Git telemetry hook via \`npx aisdlc git hook install\` (\`pnpm run git:hook:install\`).
14881
- 3. Verify \`quality-policy.yaml\`, \`license-policy.yaml\`, and \`privacy-policy.yaml\` are present in the repository root.
14882
-
14883
- ### Step 2: Phase 0 Product Inception (\`agent-product-analyst\`)
14884
- 1. Delegate to or adopt [\`agent-product-analyst\`](../agent-product-analyst/SKILL.md).
14885
- 2. **Iterative Discovery Interview (Up to 15 Questions or Until Product Scope is 100% Clear)**: Before generating artifacts, clarify with the human Product Owner in rounds of 3\u20135 questions (up to **15 questions maximum**, stopping earlier as soon as the product is clear):
14886
- - Core mission statement and business problem.
14887
- - Primary actors (\`ACT-*\`) and external systems.
14888
- - **Target Interaction & Presentation Modality (\`CON-*\` / \`ARCH-INTRO-001\`)**: Explicitly define at inception how human actors will interact with the MVP (e.g., **Web UI**, **Desktop GUI**, **Interactive Console/TUI/CLI**, **Mobile App**, or **Headless API/SDK** if actors are exclusively external systems). Never assume a headless C#/TS class library when human actors exist.
14889
- - **User Journeys (\`JRN-*\`) to Generate (Plain-Language Elicitation)**: Ask in simple, everyday language which end-to-end user journeys to model, explicitly indicating the 5 pieces of information needed to build each journey properly: (1) protagonist user (\`persona\` / \`ACT-*\`) and their main goal, (2) step-by-step stages from start to finish (\`stages\`), (3) interaction screens/channels at each stage (\`touchpoints\`), (4) current obstacles or pain points (\`pain-points\`), and (5) concrete system capabilities/use cases (\`related-use-cases\` / \`UC-*\`).
14890
- - Essential MVP capabilities (\`UC-*\`) vs. future roadmap, ensuring **foundational entity CRUD / master data workflows** (creating/managing core domain entities before executing transactions on them) are explicitly included in the MVP.
14891
- - Top 3\u20135 quality goals (\`QR-*\`) and regulatory/technical constraints (\`CON-*\`).
14892
- 3. **Enterprise & Capability Vision**: Create \`specs/architecture/ARCH-INTRO-001.md\` (\`status: draft\`, \`naf-perspective: "Enterprise & Capability"\`) using \`templates/architecture/introduction-and-goals.template.md\`, explicitly recording the chosen presentation/UI modality.
14893
- 4. **ProductShape Baseline**: Derive initial draft artifacts in \`specs/product/\`:
14894
- - Actors (\`ACT-*\`), User Journeys (\`JRN-*\`), Use Cases (\`UC-*\`), Business Rules (\`BR-*\`), Functional Requirements (\`FR-*\` with mandatory \`@nominal\`, \`@boundary\`, \`@invalid\` Gherkin blocks), and Quality Requirements (\`QR-*\`).
14895
- - **Vertical Slice Completeness Rule**: Every human-triggered \`UC-*\` in the MVP must specify observable user interaction through the agreed presentation modality (Web screens/forms, Desktop views, or Console commands/menus) and state persistence\u2014never stop at internal library/service method calls.
14896
- 5. Validate schemas and duplicates via MCP tools \`verify_schemas\` and \`verify_duplicates\` (or \`npx aisdlc check --fix\`).
14897
- 6. **Mandatory Upstream UX & MVP Boundary Gate (\`agent-expert-user\`)**: Invoke [\`agent-expert-user\`](../agent-expert-user/SKILL.md) in **Design Mode** to stress-test the proposed workflows, enforce strict MVP boundaries, reject any headless/library-only MVP when human actors exist, verify master-data CRUD prerequisites, and separate core MVP \`UC-*\` from future roadmap backlog (\`templates/product/user-design-feedback.template.md\`).
14898
- 7. **Transversal Quality & Adversarial Loop (\`agent-product-analyst\`)**:
14899
- - Concurrently invoke \`agent-auditor\` and \`agent-adversary\` on the draft product artifacts in isolated context windows.
14900
- - Consolidate findings and hand off back to \`agent-product-analyst\` to re-execute and remediate issues (max 2 correction rounds).
14901
-
14902
- ### Step 3: Shift-Left Cybersecurity & Privacy-by-Design (\`agent-threat-modeler\` \u2794 \`agent-privacy-officer\`)
14903
- 1. Delegate to or adopt [\`agent-threat-modeler\`](../agent-threat-modeler/SKILL.md).
14904
- 2. Analyze every \`UC-*\` and \`FR-*\` using STRIDE and OWASP ASVS to create in \`specs/security/\`:
14905
- - Threat Actors (\`ACT-THREAT-*\`)
14906
- - Abuse Cases (\`ABUSE-*\` targeting \`UC-*\`)
14907
- - Security Requirements (\`SEC-REQ-*\` with \`@security @mitigation\` negative Gherkin scenarios and \`SEC-ENC-*\` Zero Trust enclave bindings).
14908
- 3. **Transversal Quality & Adversarial Loop (\`agent-threat-modeler\`)**:
14909
- - Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over the security threat models.
14910
- - Consolidate findings and return handoff to \`agent-threat-modeler\` to re-execute and remediate (max 2 correction rounds).
14911
- 4. Hand off to [\`agent-privacy-officer\`](../agent-privacy-officer/SKILL.md) to apply LINDDUN and GDPR/LOPDGDD/ISO 27701 in \`specs/privacy/\`:
14912
- - Personal Data Assets (\`DATA-ASSET-*\`), GDPR Art. 30 Records of Processing (\`PRIV-ROPA-*\`), and Privacy Requirements (\`PRIV-REQ-*\` with \`@privacy @gdpr\` Gherkin scenarios).
14913
- 5. **Transversal Quality & Adversarial Loop (\`agent-privacy-officer\`)**:
14914
- - Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over the privacy records and requirements.
14915
- - Consolidate findings and return handoff to \`agent-privacy-officer\` to re-execute and remediate (max 2 correction rounds).
14916
- 6. Run \`verify_schemas\` and \`verify_privacy\` (\`npx aisdlc verify privacy\`).
14917
-
14918
- ### Step 4: Modular Systems Architecture (\`agent-system-architect\`)
14919
- 1. Delegate to or adopt [\`agent-system-architect\`](../agent-system-architect/SKILL.md).
14920
- 2. Define building blocks (\`CMP-*\`) and Architectural Decision Records (\`ADR-*\`) in \`specs/architecture/\` using \`templates/architecture/\`, ensuring every \`CMP-*\` cites \`implements-use-cases\` (\`UC-*\`) and \`satisfies-requirements\` (\`FR-*\`, \`QR-*\`, \`SEC-REQ-*\`, \`PRIV-REQ-*\`).
14921
- 3. Inspect third-party stack choices against \`license-policy.yaml\` via \`verify_licenses\` and subprocessors against \`privacy-policy.yaml\` via \`verify_privacy\`.
14922
- 4. **Technical Security & Privacy Feedback Loop**: If new infrastructure, persistence, LLM, or auth decisions introduce attack vectors or PII flows, return to \`agent-threat-modeler\` \u2794 \`agent-privacy-officer\` to add technical \`SEC-REQ-*\` and \`PRIV-REQ-*\` mitigations before coding.
14923
- 5. **Transversal Quality & Adversarial Loop (\`agent-system-architect\`)**:
14924
- - Concurrently invoke \`agent-auditor\` (evaluating YAGNI, architecture bloat, Ports & Adapters interfaces) and \`agent-adversary\` (simulating SPOFs, race conditions, cascading outages) in isolated context windows.
14925
- - Consolidate findings and return handoff to \`agent-system-architect\` to re-execute and remediate (max 2 correction rounds).
14926
-
14927
- ### Step 5: Release Milestone & Topological Wave SDD Plan (\`1 UC-* = 1 CHG-*\`)
14928
- 1. **Open Release Milestone (\`Tier 2: release/v1.0.0\`)**: Group the approved MVP Use Cases (\`UC-001\`, \`UC-002\`, ...) under the initial release milestone (\`release/v1.0.0\`) and visualize the branch hierarchy via \`npx aisdlc git plan\`.
14929
- 2. **Decompose into Topological Waves (DAG Parallelism)**:
14930
- - **Wave 0 \u2014 Foundational Core & Executable Presentation Host (Sequential)**: Identify the foundational \`UC-*\` (core domain entities, shared contracts, auth/config, **plus the runnable application host/shell for the agreed UI modality**\u2014e.g., Web server + layout, Desktop shell, or CLI entrypoint + DB bootstrap) and deliver it first as \`CHG-001\` via [\`aisdlc-increment\`](../aisdlc-increment/SKILL.md) so the product is immediately executable and downstream agents share locked interfaces.
14931
- - **Waves 1..N \u2014 Orthogonal End-to-End Vertical Slices (Parallel Multi-Agent)**: Once Wave 0 contracts and host shell are merged into \`release/v1.0.0\`, scaffold independent \`CHG-*\` increments (\`1 UC-* = 1 CHG-*\`) and execute them **in parallel** across isolated branches/worktrees (\`feat/CHG-002\`, \`feat/CHG-003\`, ...) whenever they target distinct components (\`CMP-*\`) or bounded contexts (\`BC-*\`). Every \`CHG-*\` implementing a human \`UC-*\` must deliver its complete vertical slice (Domain + Persistence + UI/CLI presentation view/command + E2E test).
14932
- 3. **Release Consolidation (\`release/v1.0.0\` \u2794 \`main\`)**: Once all MVP \`CHG-*\` increments are integrated (\`sdd_integrate\`), run \`verify\` (\`npx aisdlc verify all\`), generate SBOM (\`npx aisdlc verify licenses --sbom reports/sbom.cdx.json --notices THIRD_PARTY_NOTICES.md\`), compute release KPIs (\`kpi_release\`), and open the Release PR into \`main\` for human Product Owner & Release Manager sign-off.
14933
-
14934
- ## Non-Negotiable Guardrails
14935
- - **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles in the same conversation context window. In subagent-capable IDEs (Antigravity \`invoke_subagent\`, Claude Code \`Task\` / \`.claude/agents/\`, GitHub Copilot \`@agent-*\`), always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk (\`specs/\`, \`handoff.yaml\`, \`get_active_handoff\`). In chat-based IDEs (Cursor, Windsurf, Aider), persist all artifacts to disk, emit the Workflow Handoff block, and instruct the user to open a **New Chat** (or \`/clear\`) before running the next specialist.
14936
- - **Mandatory Transversal Quality & Adversarial Loop**: Every authoring agent deliverable must undergo concurrent inspection by \`agent-auditor\` and \`agent-adversary\` in isolated context windows, followed by a re-execution of the authoring agent to remediate findings. To prevent infinite cycles, enforce the **Anti-Ping-Pong Guardrail**: maximum 2 correction rounds per phase; if unresolved blocking defects persist after round 2, escalate to the Human Tech Lead.
14937
- - **FORBIDDEN Library-Only MVP for Human-Facing Products**: Whenever a product defines human actors (\`ACT-*\`), no agent may scope the MVP (\`release/v1.0.0\`) as headless class libraries or in-memory-only modules without an executable presentation host. The target interaction modality (Web UI, Desktop GUI, Console/TUI/CLI, or Mobile) must be explicitly agreed with the user during Phase 0 Inception and delivered as a runnable end-to-end application across the MVP waves.
14938
- - **FORBIDDEN Greenfield Monolith (\`1 UC-* = 1 CHG-*\`)**: Never bundle the entire product or multiple \`UC-*\` into a single SDD change (\`CHG-001\`). Deterministic Gate 3 (\`verify_governance\`) blocks any \`handoff.yaml\` containing $> 1$ Use Case (\`Greenfield monolith detected\`). Parallelism is achieved by running **multiple bounded \`CHG-*\` concurrently** on separate branches/worktrees, never by stuffing multiple \`UC-*\` into one \`CHG-*\`.
14939
- - Never invoke \`sdd_change_new\` or write application code in \`src/\` on a Greenfield project before \`ARCH-INTRO-001\`, \`agent-expert-user\` MVP validation, and at least one \`UC-*\` and \`FR-*\` exist.
14940
- - All newly drafted specifications must start with \`status: draft\`.
14941
- - Respect the Workflow Handoff Protocol (\`templates/workflow/agent-handoff.template.md\`) whenever task autonomy is $\\ge$ \`HUMAN_REVIEW_PLAN\`.`
15007
+ body: '## Purpose & Trigger\nUse this skill when starting a **brand-new software project from scratch (Greenfield)** or when `specs/product/` has no canonical baseline yet. It coordinates the sequential execution of AI-SDLC MCP/CLI tools and specialized role agents so no code is written before product vision, security enclaves, privacy-by-design controls, and architecture contracts exist.\n\n## Consolidated Inception Quality & Adversarial Checkpoint\nAcross Phase 0 and Inception, quality auditing and adversarial stress-testing are concentrated at the completion of Inception design (or after product shaping):\n- **Concurrent Inspection**: Concurrently invoke [`agent-auditor`](../agent-auditor/SKILL.md) (evaluating YAGNI, structural debt, and simplification) and [`agent-adversary`](../agent-adversary/SKILL.md) (stress-testing logic traps, SPOFs, attack vectors, or broken invariants) in clean, isolated context windows.\n- **Non-Invasive Review**: Neither auditor nor adversary modifies deliverables directly; both deliver structured reports citing canonical IDs and SHA-256 digests.\n- **Consolidated Remediation**: Consolidate findings and emit the Workflow Handoff back to authoring agents to resolve blocking defects and apply simplifications (max 2 correction rounds).\n- **Anti-Ping-Pong Guardrail**: Bounded strictly to maximum **1 correction round**. If non-blocking advisories remain, proceed to the downstream phase; if blocking defects persist, escalate immediately to the Human Tech Lead.\n\n## End-to-End Execution Playbook\n\n### Step 1: Repository Turnkey Initialization\n1. If the workspace has not been initialized with AI-SDLC schemas, policies, and templates, run MCP tool `new` (or CLI `npx @aisdlc/cli init`).\n2. Install the Git telemetry hook via `npx aisdlc git hook install` (`pnpm run git:hook:install`).\n3. Verify `quality-policy.yaml`, `license-policy.yaml`, and `privacy-policy.yaml` are present in the repository root.\n\n### Step 2: Phase 0 Product Inception (`agent-product-analyst`)\n1. Delegate to or adopt [`agent-product-analyst`](../agent-product-analyst/SKILL.md).\n2. **Iterative Discovery Interview (Up to 15 Questions or Until Product Scope is 100% Clear)**: Before generating artifacts, clarify with the human Product Owner in rounds of 3\u20135 questions:\n - Core mission statement and business problem.\n - Primary actors (`ACT-*`) and external systems.\n - **Target Interaction & Presentation Modality (`CON-*` / `ARCH-INTRO-001`)**: Explicitly define at inception how human actors will interact with the MVP (e.g., **Web UI**, **Desktop GUI**, **Interactive Console/TUI/CLI**, **Mobile App**, or **Headless API/SDK** if actors are exclusively external systems). Never assume a headless class library when human actors exist.\n - **User Journeys (`JRN-*`) to Generate (Plain-Language Elicitation)**: Ask in simple, everyday language which end-to-end user journeys to model, explicitly indicating the 5 pieces of information needed to build each journey properly: (1) protagonist user (`persona` / `ACT-*`) and their main goal, (2) step-by-step stages from start to finish (`stages`), (3) interaction screens/channels at each stage (`touchpoints`), (4) current obstacles or pain points (`pain-points`), and (5) concrete system capabilities/use cases (`related-use-cases` / `UC-*`).\n - Essential MVP capabilities (`UC-*`) vs. future roadmap, ensuring **foundational entity CRUD / master data workflows** are explicitly included in the MVP.\n - Top 3\u20135 quality goals (`QR-*`) and regulatory/technical constraints (`CON-*`).\n3. **Enterprise & Capability Vision**: Create `specs/architecture/ARCH-INTRO-001.md` (`status: draft`, `naf-perspective: "Enterprise & Capability"`) using `templates/architecture/introduction-and-goals.template.md`, explicitly recording the chosen presentation/UI modality.\n4. **ProductShape Baseline**: Derive initial draft artifacts in `specs/product/`:\n - Actors (`ACT-*`), User Journeys (`JRN-*`), Use Cases (`UC-*`), Business Rules (`BR-*`), Functional Requirements (`FR-*` with mandatory `@nominal`, `@boundary`, `@invalid` Gherkin blocks), and Quality Requirements (`QR-*`).\n - **Vertical Slice Completeness Rule**: Every human-triggered `UC-*` in the MVP must specify observable user interaction through the agreed presentation modality and state persistence.\n5. Validate schemas and duplicates via MCP tools `verify_schemas` and `verify_duplicates` (or `npx aisdlc check --fix`).\n6. **Mandatory Upstream UX & MVP Boundary Gate (`agent-expert-user`)**: Invoke [`agent-expert-user`](../agent-expert-user/SKILL.md) in **Design Mode** to stress-test the proposed workflows, enforce strict MVP boundaries, reject any headless/library-only MVP when human actors exist, verify master-data CRUD prerequisites, and separate core MVP `UC-*` from future roadmap backlog.\n\n### Step 3: Shift-Left Cybersecurity & Privacy-by-Design (`agent-threat-modeler` \u2794 `agent-privacy-officer`)\n1. Delegate to or adopt [`agent-threat-modeler`](../agent-threat-modeler/SKILL.md).\n2. Analyze every `UC-*` and `FR-*` using STRIDE and OWASP ASVS to create in `specs/security/`:\n - Threat Actors (`ACT-THREAT-*`), Abuse Cases (`ABUSE-*` targeting `UC-*`), and Security Requirements (`SEC-REQ-*` with `@security @mitigation` negative Gherkin scenarios and `SEC-ENC-*` Zero Trust enclave bindings).\n3. Hand off to [`agent-privacy-officer`](../agent-privacy-officer/SKILL.md) to apply LINDDUN and GDPR/LOPDGDD/ISO 27701 in `specs/privacy/`:\n - Personal Data Assets (`DATA-ASSET-*`), GDPR Art. 30 Records of Processing (`PRIV-ROPA-*`), and Privacy Requirements (`PRIV-REQ-*` with `@privacy @gdpr` Gherkin scenarios).\n4. Run `verify_schemas` and `verify_privacy` (`npx aisdlc verify privacy`).\n\n### Step 4: Modular Systems Architecture (`agent-system-architect`)\n1. Delegate to or adopt [`agent-system-architect`](../agent-system-architect/SKILL.md).\n2. Define building blocks (`CMP-*`) and Architectural Decision Records (`ADR-*`) in `specs/architecture/` using `templates/architecture/`, ensuring every `CMP-*` cites `implements-use-cases` (`UC-*`) and `satisfies-requirements` (`FR-*`, `QR-*`, `SEC-REQ-*`, `PRIV-REQ-*`).\n3. Inspect third-party stack choices against `license-policy.yaml` via `verify_licenses` and subprocessors against `privacy-policy.yaml` via `verify_privacy`.\n4. **Technical Security & Privacy Feedback Loop**: If new infrastructure, persistence, LLM, or auth decisions introduce attack vectors or PII flows, return to `agent-threat-modeler` \u2794 `agent-privacy-officer` to add technical mitigations before coding.\n\n### Checkpoint 1 (Inception Design Checkpoint): `agent-auditor` $\\parallel$ `agent-adversary`\n1. Concurrently invoke `agent-auditor` (evaluating YAGNI, architecture bloat, interface contracts) and `agent-adversary` (simulating SPOFs, race conditions, unhandled threat scenarios) in isolated context windows over all Phase 0 deliverables.\n2. Consolidate findings and remediate in authoring agents (max 2 correction rounds).\n3. **Human Approval Gate**: Present the comprehensive Inception model for Human PO & Tech Lead sign-off.\n\n### Step 5: Release Milestone & Topological Wave SDD Plan (`1 UC-* = 1 CHG-*`)\n1. **Open Release Milestone (`Tier 2: release/v1.0.0` or Streamlined `main`)**: Group approved MVP Use Cases (`UC-001`, `UC-002`, ...) and visualize execution plan.\n2. **Decompose into Topological Waves (DAG Parallelism)**:\n - **Wave 0 \u2014 Foundational Core & Executable Presentation Host (Sequential)**: Scaffold `CHG-001` via [`aisdlc-increment`](../aisdlc-increment/SKILL.md) to establish domain core, shared contracts, auth/config, and the runnable presentation host.\n - **Waves 1..N \u2014 Orthogonal End-to-End Vertical Slices (Parallel Multi-Agent)**: Once Wave 0 contracts are merged, execute independent `CHG-*` increments (`1 UC-* = 1 CHG-*`) in parallel across isolated branches/worktrees (`feat/CHG-002`, `feat/CHG-003`, ...).\n3. **Release Consolidation**: Once all MVP increments are integrated (`sdd_integrate`), run `verify` (`npx aisdlc verify all`), generate SBOM, compute release KPIs (`kpi_release`), and open the Release PR for final human approval and SemVer tagging (`v1.0.0`).\n\n## Non-Negotiable Guardrails\n- **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles in the same conversation context window. Always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk.\n- **2-Checkpoint Quality & Adversarial Protocol**: Quality auditing and adversarial testing are concentrated at the completion of Inception design and Pre-PR implementation, avoiding micro-step overhead.\n- **FORBIDDEN Library-Only MVP for Human-Facing Products**: Whenever a product defines human actors (`ACT-*`), no agent may scope the MVP as headless class libraries without an executable presentation host.\n- **FORBIDDEN Greenfield Monolith (`1 UC-* = 1 CHG-*`)**: Never bundle the entire product or multiple `UC-*` into a single SDD change (`CHG-001`). Parallelism is achieved by running **multiple bounded `CHG-*` concurrently** on separate branches/worktrees.\n- Never invoke `sdd_change_new` or write application code in `src/` on a Greenfield project before `ARCH-INTRO-001`, `agent-expert-user` MVP validation, and at least one `UC-*` and `FR-*` exist.\n- All newly drafted specifications must start with `status: draft`.'
14942
15008
  },
14943
15009
  {
14944
15010
  id: "aisdlc-legacy-onboarding",
14945
15011
  title: "Legacy / Brownfield Retro-Inception Playbook",
14946
- description: "Orchestrate progressive AI-SDLC adoption and Brownfield retro-inception on existing or legacy repositories without breaking production code, reverse-engineering architecture (ARCH-INTRO-*, CMP-*), transversal auditor/adversary verification loops, and establishing baseline quality, security, and license audits before new SDD increments.",
14947
- references: "[`process/02_product_definition.md`](../../process/02_product_definition.md), [`process/04_open_source_license_compliance.md`](../../process/04_open_source_license_compliance.md), [`process/04b_data_protection_and_privacy.md`](../../process/04b_data_protection_and_privacy.md), [`process/05_architecture_arc42_nafv4.md`](../../process/05_architecture_arc42_nafv4.md), [`process/10_quality_management_and_release_gates.md`](../../process/10_quality_management_and_release_gates.md), and [`process/09_agent_protocols.md`](../../process/09_agent_protocols.md).",
15012
+ description: "Orchestrate progressive AI-SDLC adoption and Brownfield retro-inception on existing or legacy repositories without breaking production code, reverse-engineering architecture (ARCH-INTRO-*, CMP-*), 2-checkpoint auditor/adversary verification, and establishing baseline quality, security, and license audits before new SDD increments.",
15013
+ references: "[`process/02_product_definition.md`](../../process/02_product_definition.md), [`process/05_architecture_arc42_nafv4.md`](../../process/05_architecture_arc42_nafv4.md), [`process/06_spec_driven_development.md`](../../process/06_spec_driven_development.md), [`process/10_quality_management_and_release_gates.md`](../../process/10_quality_management_and_release_gates.md), and [`process/09_agent_protocols.md`](../../process/09_agent_protocols.md).",
14948
15014
  globs: "architecture/**, specs/**, src/**, packages/**",
14949
- body: `## Purpose & Trigger
14950
- Use this skill when **adopting AI-SDLC in an existing or legacy codebase (Brownfield)** that already has production source code (\`src/\`, \`packages/\`, etc.) but lacks canonical PDaC specifications, arc42 architecture views, or deterministic quality/license/privacy gates.
14951
-
14952
- ## Mandatory Transversal Quality & Adversarial Protocol
14953
- Every authoring agent deliverable during Brownfield retro-inception undergoes mandatory quality auditing and adversarial stress-testing before downstream progression:
14954
- - **Concurrent Inspection**: Immediately following the execution of any authoring agent (\`agent-product-analyst\`, \`agent-system-architect\`, \`agent-threat-modeler\`, \`agent-privacy-officer\`), invoke [\`agent-auditor\`](../agent-auditor/SKILL.md) (evaluating YAGNI, over-specification, and structural clarity) and [\`agent-adversary\`](../agent-adversary/SKILL.md) (uncovering hidden assumptions, boundary breaks, and contradictory legacy rules) **concurrently** in clean, isolated context windows.
14955
- - **Non-Invasive Review**: Neither auditor nor adversary modifies deliverables directly; both deliver structured reports citing canonical IDs and SHA-256 digests.
14956
- - **Consolidated Remediation Re-Execution**: Consolidate findings and emit the Workflow Handoff back to the authoring agent, who is re-executed to resolve blocking defects and apply simplifications.
14957
- - **Anti-Ping-Pong Guardrail (Max 2 Rounds)**: Bounded strictly to a maximum of **2 correction rounds** per phase/deliverable. If non-blocking advisories remain after round 2, proceed to the downstream phase; if blocking defects persist after round 2, escalate immediately to the Human Tech Lead.
14958
- - **Exclusion of Diagnostic/Review Roles**: Read-only baseline verifiers and diagnostic review roles (\`agent-compliance-checker\`, \`agent-security-auditor\`, \`agent-code-reviewer\`) assess pre-existing code and are excluded from being audited by this loop.
14959
-
14960
- ## End-to-End Execution Playbook
14961
-
14962
- ### Step 1: Non-Destructive Framework Scaffolding
14963
- 1. Run MCP tool \`new\` (or CLI \`npx @aisdlc/cli init\`) on the existing repository.
14964
- - AI-SDLC enforces strict **no-clobber protection**: existing \`package.json\`, \`CLAUDE.md\`, or CI pipelines are preserved while injecting missing schemas (\`schemas/\`), templates (\`templates/\`), policies (\`quality-policy.yaml\`, \`license-policy.yaml\`, \`privacy-policy.yaml\`), and MCP configs.
14965
- 2. Install the Git commit trailer hook via \`npx aisdlc git hook install\`.
14966
-
14967
- ### Step 2: Baseline Diagnostic Audit (Read-Only Assessment)
14968
- Before modifying any code or creating SDD changes, run diagnostic verifiers to quantify existing technical, legal, privacy, and security debt:
14969
- 1. **License & Dependency Audit (\`agent-compliance-checker\`)**: Run MCP tool \`verify_licenses\` (\`npx aisdlc verify licenses\`). Identify any viral (\`GPL\`/\`AGPL\`) or commercial (\`BSL\`/\`SSPL\`) dependencies already present in the lockfile and document exceptions or remediation plans.
14970
- 2. **Shift-Left Security Scan (\`agent-security-auditor\`)**: Run MCP tool \`verify_security\` (\`npx aisdlc verify security\`) to detect hardcoded secrets (Gate 11) or OWASP SAST vulnerabilities in legacy files.
14971
- 3. **Privacy & PII Scan (\`agent-privacy-officer\`)**: Run MCP tool \`verify_privacy\` (\`npx aisdlc verify privacy\`) to detect PII in logs/telemetry or hardcoded real PII in legacy tests/seeds.
14972
- 4. **AST Code Quality Baseline (\`agent-code-reviewer\`)**: Run MCP tool \`report_quality\` (\`npx aisdlc report quality\`) to generate \`reports/QUALITY_REPORT.md\` and identify legacy hotspots exceeding Cyclomatic Complexity ($\\le 10$), Cognitive Complexity ($\\le 15$), or Maintainability Index ($\\ge 50$).
14973
-
14974
- ### Step 3: Brownfield Retro-Inception (\`agent-system-architect\` & \`agent-product-analyst\`)
14975
- Instead of attempting to document 100% of a legacy monolith upfront, apply **bounded retro-inception** focused on the system boundary and the domain areas under active evolution:
14976
- 1. **System Vision & Context (\`ARCH-INTRO-001\`)**: Use [\`agent-product-analyst\`](../agent-product-analyst/SKILL.md) to document the current system's mission, primary actors (\`ACT-*\`), and top quality goals (\`QR-*\`) in \`specs/architecture/ARCH-INTRO-001.md\`.
14977
- - **Transversal Loop**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over \`ARCH-INTRO-001\`. Consolidate findings and return handoff to \`agent-product-analyst\` to re-execute and remediate (max 2 correction rounds).
14978
- 2. **As-Is Component Mapping (\`CMP-*\` & \`ADR-*\`)**: Use [\`agent-system-architect\`](../agent-system-architect/SKILL.md) to map existing core modules/services into \`specs/architecture/CMP-*.md\` and capture historical architectural constraints (\`CON-*\`, \`ADR-*\`).
14979
- - **Transversal Loop**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over component models. Consolidate findings and return handoff to \`agent-system-architect\` to re-execute and remediate (max 2 correction rounds).
14980
- 3. **Core Use Cases Extraction (\`UC-*\`, \`FR-*\`)**: Extract canonical \`UC-*\` and \`FR-*\` artifacts in \`specs/product/\` for the specific bounded context or module that will be modified or extended next, including Gherkin acceptance scenarios reflecting current expected behavior (characterization specs).
14981
- - **Transversal Loop**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over extracted \`UC-*\`/\`FR-*\`. Consolidate findings and return handoff to \`agent-product-analyst\` to re-execute and remediate (max 2 correction rounds).
14982
- 4. **Threat & Privacy Boundary Mapping (\`agent-threat-modeler\` \u2794 \`agent-privacy-officer\`)**: Map existing trust zones (\`SEC-ENC-*\`), active threat vectors (\`ACT-THREAT-*\`, \`ABUSE-*\`, \`SEC-REQ-*\`), and personal data inventories (\`DATA-ASSET-*\`, \`PRIV-ROPA-*\`, \`PRIV-REQ-*\`) on the target module.
14983
- - **Transversal Loop**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over threat and privacy models. Consolidate findings and return handoff to \`agent-threat-modeler\` and \`agent-privacy-officer\` to re-execute and remediate (max 2 correction rounds).
14984
-
14985
- ### Step 4: Characterization Testing & Synchronization
14986
- 1. Run MCP tool \`sdd_check_fix\` (\`npx aisdlc check --fix\`) to extract \`.feature\` files and compute canonical SHA-256 digests.
14987
- 2. Run \`verify_schemas\` and \`verify_pdac\` to confirm the reverse-engineered baseline graph is structurally valid and drift-free.
14988
-
14989
- ### Step 5: Transition to Governed SDD Increments (Boy Scout / Strangler Rule)
14990
- Once the target domain's baseline artifacts (\`ARCH-INTRO-*\`, \`UC-*\`, \`FR-*\`, \`CMP-*\`) are in place, execute all new features, refactorings, or bugfixes via [\`aisdlc-increment\`](../aisdlc-increment/SKILL.md).
14991
-
14992
- ## Non-Negotiable Guardrails
14993
- - **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles in the same conversation context window. In subagent-capable IDEs (Antigravity \`invoke_subagent\`, Claude Code \`Task\` / \`.claude/agents/\`, GitHub Copilot \`@agent-*\`), always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk (\`specs/\`, \`handoff.yaml\`, \`get_active_handoff\`). In chat-based IDEs (Cursor, Windsurf, Aider), persist all artifacts to disk, emit the Workflow Handoff block, and instruct the user to open a **New Chat** (or \`/clear\`) before running the next specialist.
14994
- - **Mandatory Transversal Quality & Adversarial Loop**: Every authoring agent deliverable must undergo concurrent inspection by \`agent-auditor\` and \`agent-adversary\` in isolated context windows, followed by a re-execution of the authoring agent to remediate findings. To prevent infinite cycles, enforce the **Anti-Ping-Pong Guardrail**: maximum 2 correction rounds per phase; if unresolved blocking defects persist after round 2, escalate to the Human Tech Lead.
14995
- - **Zero Drive-By Rewrites**: Never mass-refactor untouched legacy modules during onboarding. Apply the Strangler / Boy Scout rule: bring touched functions into compliance with \`quality-policy.yaml\` incrementally via governed SDD tasks (\`TSK-*\`).
14996
- - **Characterization First**: Never alter legacy business logic without first capturing its current behavior in an \`FR-*\` Gherkin specification and a verifiable test suite (\`agent-qa-engineer\`).
14997
- - **Immediate Secret Remediation**: If Step 2 (\`verify_security\`) uncovers leaked credentials (exit code 4), halt feature work and remediate/rotate secrets immediately.`
15015
+ body: "## Purpose & Trigger\nUse this skill when onboarding an **existing codebase (Brownfield / Legacy)** that was not built with AI-SDLC. It establishes non-disruptive governance, maps existing code into canonical specifications, inventories debt across all 12 Quality Gates, and creates baseline specifications (`specs/product/`, `specs/architecture/`) before new features or refactorings are introduced.\n\n## Retro-Inception Quality & Adversarial Checkpoint\nAcross Brownfield retro-inception, quality auditing and adversarial stress-testing are concentrated at the completion of retro-inception mapping:\n- **Concurrent Inspection**: Concurrently invoke [`agent-auditor`](../agent-auditor/SKILL.md) (evaluating YAGNI, over-modeling, and debt priorities) and [`agent-adversary`](../agent-adversary/SKILL.md) (uncovering undocumented invariants, hidden failure modes, and security gaps) in clean, isolated context windows.\n- **Non-Invasive Review**: Neither auditor nor adversary modifies deliverables directly; both deliver structured reports citing canonical IDs and SHA-256 digests.\n- **Consolidated Remediation**: Consolidate findings and emit the Workflow Handoff back to authoring agents to resolve blocking defects and apply simplifications (max 2 correction rounds).\n- **Anti-Ping-Pong Guardrail**: Bounded strictly to maximum **1 correction round**. If non-blocking advisories remain, proceed to characterization; if blocking defects persist, escalate to the Human Tech Lead.\n\n## End-to-End Execution Playbook\n\n### Step 1: Turnkey Repository Scaffolding (Non-Destructive)\n1. Initialize AI-SDLC configuration without overwriting existing application files using `npx @aisdlc/cli init` (or MCP tool `new`).\n2. Install the Git telemetry hook via `npx aisdlc git hook install` (`pnpm run git:hook:install`).\n3. Commit initial AI-SDLC schemas and policies (`.github/`, `schemas/`, `templates/`, `*-policy.yaml`).\n\n### Step 2: Automated Baseline Audit & Debt Inventory (Read-Only)\nBefore modifying any code or creating SDD changes, run diagnostic verifiers to quantify existing technical, legal, privacy, and security debt:\n1. **License & Dependency Audit (`agent-compliance-checker`)**: Run MCP tool `verify_licenses` (`npx aisdlc verify licenses`). Identify any viral (`GPL`/`AGPL`) or commercial (`BSL`/`SSPL`) dependencies already present in the lockfile and document exceptions or remediation plans.\n2. **Shift-Left Security Scan (`agent-security-auditor`)**: Run MCP tool `verify_security` (`npx aisdlc verify security`) to detect hardcoded secrets (Gate 11) or OWASP SAST vulnerabilities in legacy files.\n3. **Privacy & PII Scan (`agent-privacy-officer`)**: Run MCP tool `verify_privacy` (`npx aisdlc verify privacy`) to detect PII in logs/telemetry or hardcoded real PII in legacy tests/seeds.\n4. **AST Code Quality Baseline (`agent-code-reviewer`)**: Run MCP tool `report_quality` (`npx aisdlc report quality`) to generate `reports/QUALITY_REPORT.md` and identify legacy hotspots exceeding Cyclomatic Complexity ($\\le 10$), Cognitive Complexity ($\\le 15$), or Maintainability Index ($\\ge 50$).\n\n### Step 3: Brownfield Retro-Inception (`agent-system-architect` & `agent-product-analyst`)\nInstead of attempting to document 100% of a legacy monolith upfront, apply **bounded retro-inception** focused on the system boundary and the domain areas under active evolution:\n1. **System Vision & Context (`ARCH-INTRO-001`)**: Use [`agent-product-analyst`](../agent-product-analyst/SKILL.md) to document the current system's mission, primary actors (`ACT-*`), and top quality goals (`QR-*`) in `specs/architecture/ARCH-INTRO-001.md`.\n2. **As-Is Component Mapping (`CMP-*` & `ADR-*`)**: Use [`agent-system-architect`](../agent-system-architect/SKILL.md) to map existing core modules/services into `specs/architecture/CMP-*.md` and capture historical architectural constraints (`CON-*`, `ADR-*`).\n3. **Core Use Cases Extraction (`UC-*`, `FR-*`)**: Extract canonical `UC-*` and `FR-*` artifacts in `specs/product/` for the specific bounded context or module that will be modified or extended next, including Gherkin acceptance scenarios reflecting current expected behavior (characterization specs).\n4. **Threat & Privacy Boundary Mapping (`agent-threat-modeler` \u2794 `agent-privacy-officer`)**: Map existing trust zones (`SEC-ENC-*`), active threat vectors (`ACT-THREAT-*`, `ABUSE-*`, `SEC-REQ-*`), and personal data inventories (`DATA-ASSET-*`, `PRIV-ROPA-*`, `PRIV-REQ-*`) on the target module.\n5. **Retro-Inception Checkpoint (`agent-auditor` $\\parallel$ `agent-adversary`)**: Concurrently inspect reverse-engineered artifacts, evaluate fidelity vs. unnecessary modeling overhead, and consolidate fixes.\n\n### Step 4: Characterization Testing & Synchronization\n1. Run MCP tool `sdd_check_fix` (`npx aisdlc check --fix`) to extract `.feature` files and compute canonical SHA-256 digests.\n2. Run `verify_schemas` and `verify_pdac` to confirm the reverse-engineered baseline graph is structurally valid and drift-free.\n\n### Step 5: Transition to Governed SDD Increments (Boy Scout / Strangler Rule)\nOnce the target domain's baseline artifacts (`ARCH-INTRO-*`, `UC-*`, `FR-*`, `CMP-*`) are in place, execute all new features, refactorings, or bugfixes via [`aisdlc-increment`](../aisdlc-increment/SKILL.md).\n\n## Non-Negotiable Guardrails\n- **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles in the same conversation context window. Always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk.\n- **2-Checkpoint Quality & Adversarial Protocol**: Concentrated review at the retro-inception boundary and before PR delivery prevents process friction while maintaining rigorous defect interception.\n- **Zero Drive-By Rewrites**: Never mass-refactor untouched legacy modules during onboarding. Apply the Strangler / Boy Scout rule: bring touched functions into compliance with `quality-policy.yaml` incrementally via governed SDD tasks (`TSK-*`).\n- **Characterization First**: Never alter legacy business logic without first capturing its current behavior in an `FR-*` Gherkin specification and a verifiable test suite (`agent-qa-engineer`).\n- **Immediate Secret Remediation**: If Step 2 (`verify_security`) uncovers leaked credentials (exit code 4), halt feature work and remediate/rotate secrets immediately."
14998
15016
  },
14999
15017
  {
15000
15018
  id: "aisdlc-increment",
15001
15019
  title: "Bounded SDD Feature & Bugfix Delivery Playbook",
15002
- description: "Orchestrate the complete Spec-Driven Development (SDD) lifecycle for bounded feature increments, enhancements, and bugfixes (CHG-* / TSK-*), from upstream requirement derivation and 4-tier Git branching through Red-Green-Refactor TDD, transversal auditor/adversary verification loops, Pre-Merge Audit Triad, all 11 Quality Gates, and canonical baseline integration.",
15020
+ description: "Orchestrate the complete Spec-Driven Development (SDD) lifecycle for bounded feature increments, enhancements, and bugfixes (CHG-* / TSK-*), from upstream requirement derivation and streamlined Git branching through Red-Green-Refactor TDD, 2-checkpoint transversal auditor/adversary verification, all 12 Quality Gates, and canonical baseline integration.",
15003
15021
  references: "[`process/06_spec_driven_development.md`](../../process/06_spec_driven_development.md), [`process/08_citation_contract_and_drift.md`](../../process/08_citation_contract_and_drift.md), [`process/10_quality_management_and_release_gates.md`](../../process/10_quality_management_and_release_gates.md), [`process/11_git_branching_and_lifecycle.md`](../../process/11_git_branching_and_lifecycle.md), and [`process/09_agent_protocols.md`](../../process/09_agent_protocols.md).",
15004
15022
  globs: "specs/changes/**, src/**, packages/**, tests/**",
15005
- body: `## Purpose & Trigger
15006
- Use this skill for **every evolutionary increment (new feature, enhancement, refactoring, or bugfix)** on a project that already has an AI-SDLC baseline. It enforces strict 360\xB0 traceability from upstream ProductShape (\`UC-*\`, \`FR-*\`) through SDD (\`CHG-*\`, \`HOF-*\`, \`TSK-*\`), TDD implementation, the 12 Quality Gates, and baseline promotion.
15007
-
15008
- ## End-to-End Execution Playbook
15009
-
15010
- ### Step 1: Upstream Product, Security & Privacy Delta (\`agent-product-analyst\`, \`agent-threat-modeler\` & \`agent-privacy-officer\`)
15011
- 1. Inspect active changes via MCP tool \`get_active_handoff\` and verify whether the target Use Case (\`UC-*\`) or Requirement (\`FR-*\`) already exists in \`specs/product/\`.
15012
- 2. If the increment introduces new behavior or modifies business rules:
15013
- - Use [\`agent-product-analyst\`](../agent-product-analyst/SKILL.md) to create or update the \`UC-*\`, \`BR-*\`, and \`FR-*\` (with \`@nominal\`, \`@boundary\`, \`@invalid\` Gherkin scenarios).
15014
- - **Transversal Loop (\`agent-product-analyst\`)**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over updated specs. Consolidate findings and return handoff to \`agent-product-analyst\` to re-execute and remediate (max 2 correction rounds).
15015
- - Run MCP tool \`verify_duplicates\` (\`npx aisdlc verify duplicates\`) to block lexical or functional collisions early.
15016
- - Use [\`agent-threat-modeler\`](../agent-threat-modeler/SKILL.md) to model any new \`ABUSE-*\` and \`SEC-REQ-*\` mitigations.
15017
- - **Transversal Loop (\`agent-threat-modeler\`)**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over security models. Consolidate findings and return handoff to \`agent-threat-modeler\` to re-execute and remediate (max 2 correction rounds).
15018
- - Hand off to [\`agent-privacy-officer\`](../agent-privacy-officer/SKILL.md) to model any personal data assets (\`DATA-ASSET-*\`), GDPR Art. 30 processing activities (\`PRIV-ROPA-*\`), and privacy requirements (\`PRIV-REQ-*\`).
15019
- - **Transversal Loop (\`agent-privacy-officer\`)**: Concurrently invoke \`agent-auditor\` and \`agent-adversary\` over privacy models. Consolidate findings and return handoff to \`agent-privacy-officer\` to re-execute and remediate (max 2 correction rounds).
15020
- 3. Run \`sdd_check_fix\` (\`npx aisdlc check --fix\`) to sync Gherkin \`.feature\` files and validate schemas.
15021
-
15022
- ### Step 2: SDD Change Scaffolding & Architectural Design (\`agent-system-architect\`)
15023
- 1. Scaffold the bounded change package and its cryptographic \`handoff.yaml\` sidecar (\`HOF-*\`) targeting **a single Use Case (\`1 UC-* = 1 CHG-*\`)** using MCP tool \`sdd_change_new\` (or CLI \`npx aisdlc change new "<Title>" --from <UC-ID> --profile <patch|standard|critical>\`).
15024
- 2. Use [\`agent-system-architect\`](../agent-system-architect/SKILL.md) to complete \`specs/changes/active/<chg-id>/design.md\` and \`specs/architecture/CMP-*.md\`:
15025
- - Structure \`CMP-*\` and \`design.md\` around **Modular & Hexagonal Architecture (Ports & Adapters)** (Domain/Application Core + Inbound/Outbound Ports) and define **Contract-First** shared interfaces/DTOs/schemas when spanning Frontend and Backend.
15026
- - Map 100% of \`handoff.yaml\` requirements and components to atomic tasks (\`TSK-*\`) in \`tasks.md\` with explicit \`autonomy-mode\` (\`AUTONOMOUS\`, \`HUMAN_REVIEW_PLAN\`, \`HIGH_RISK_MANUAL\`, \`AMBIGUOUS\`).
15027
- 3. **Transversal Loop (\`agent-system-architect\`)**:
15028
- - Concurrently invoke \`agent-auditor\` (evaluating YAGNI, interface bloat, task completeness) and \`agent-adversary\` (probing race conditions, contract drift, SPOFs) in isolated context windows.
15029
- - Consolidate findings and return handoff to \`agent-system-architect\` to re-execute and remediate (max 2 correction rounds).
15030
- 4. Run \`verify_governance\` and \`verify_friction\` to validate task governance, 100% design/handoff scope coverage, and anti-monolith limits (\`maxUseCasesPerChange = 1\`).
15031
-
15032
- ### Step 3: 4-Tier Git Branch Navigation & Multi-Agent Parallelism
15033
- 1. Navigate to the task branch using \`npx aisdlc git checkout <TSK-ID>\` (\`pnpm run git:checkout <TSK-ID>\`), which cascade-creates:
15034
- \`main\` \u2794 \`release/vX.Y.Z\` \u2794 \`feat/CHG-XXX\` \u2794 \`task/CHG-XXX/TSK-YYY-<slug>\`.
15035
- 2. Validate branch naming compliance via \`npx aisdlc git validate <branch>\`.
15036
- 3. **Parallel Agent Execution Rules**:
15037
- - **Inter-Feature Parallelism (\`feat/CHG-001\` $\\parallel$ \`feat/CHG-002\`)**: Multiple agents may execute different \`CHG-*\` increments concurrently in isolated branches/worktrees (\`specs/changes/active/chg-XXX/\`) when their target \`CMP-*\` / \`UC-*\` have no blocking dependencies.
15038
- - **Intra-Feature Parallelism (\`task/CHG-X/TSK-002\` $\\parallel$ \`task/CHG-X/TSK-003\`)**: Once \`TSK-001\` (Contract-First shared interfaces/DTOs) is merged into \`feat/CHG-X\`, multiple \`agent-developer\` subagents may implement independent tasks (e.g., Backend adapter vs. Frontend UI) concurrently on their respective \`task/*\` branches.
15039
-
15040
- ### Step 4: Red Phase \u2014 Failing Test Suites (\`agent-qa-engineer\`)
15041
- 1. Delegate to or adopt [\`agent-qa-engineer\`](../agent-qa-engineer/SKILL.md).
15042
- 2. Author FAILING (red) BDD/Gherkin step definitions, integration/contract tests, and mandatory E2E/UI tests (evaluating Happy Path, Sad Path, and Boundary Values for every interactive UI element, plus \`UC-*\` alternative/exception flows) in \`tests/\`.
15043
- 3. **Transversal Loop (\`agent-qa-engineer\`)**:
15044
- - Concurrently invoke \`agent-auditor\` (checking test overengineering, brittle assertions) and \`agent-adversary\` (running conceptual mutation testing to prove whether trivial or empty implementations could falsely pass tests green) in isolated context windows.
15045
- - Consolidate findings and return handoff to \`agent-qa-engineer\` to re-execute and harden test suites (max 2 correction rounds).
15046
- 4. Run \`verify_testing\` (\`npx aisdlc verify testing\`) to confirm requirement test coverage before writing production code.
15047
-
15048
- ### Step 5: Green & Refactor Phase \u2014 Surgical Implementation (\`agent-developer\`)
15049
- 1. Delegate to or adopt [\`agent-developer\`](../agent-developer/SKILL.md).
15050
- 2. Execute the **Mandatory 4-Step Implementation Order**:
15051
- - (1) Modular & Hexagonal Architecture (Ports & Adapters) boundaries, (2) Inter-module interfaces/ports first, (3) Concrete component implementation (zero fake-wiring; all 4 UI states \`Loading\`, \`Empty\`, \`Error\`, \`Nominal\`), (4) Exhaustive per-function unit tests in \`tests/unit/\` (Happy Path, Sad Path, Boundary, Null/Empty).
15052
- 3. Verify any new dependency against \`license-policy.yaml\` via \`verify_licenses\` and PII handling against \`privacy-policy.yaml\` via \`verify_privacy\`.
15053
- 4. Run \`sdd_check_fix\` (\`npx aisdlc check --fix\`) and \`verify_quality\` (\`npx aisdlc verify quality\`) until Cyclomatic Complexity $\\le 10$, Cognitive $\\le 15$, Maintainability $\\ge 50$, and Function Length $\\le 40$ lines pass with zero violations.
15054
- 5. **Transversal Loop (\`agent-developer\`)**:
15055
- - Concurrently invoke \`agent-auditor\` (detecting overengineering, speculative parameters, AST complexity) and \`agent-adversary\` (attacking boundary inputs, concurrency races, type edge breaks with concrete PoCs) in isolated context windows.
15056
- - Consolidate findings and return handoff to \`agent-developer\` to re-execute and remediate (max 2 correction rounds).
15057
-
15058
- ### Mandatory Transversal Quality & Adversarial Protocol
15059
- - **Systematic Post-Agent Execution**: Immediately following the execution of any authoring agent (\`agent-product-analyst\`, \`agent-threat-modeler\`, \`agent-privacy-officer\`, \`agent-system-architect\`, \`agent-qa-engineer\`, \`agent-developer\`, \`agent-devops\`), invoke \`agent-auditor\` and \`agent-adversary\` concurrently in clean, isolated context windows over that agent's deliverables.
15060
- - **Concurrent Inspection**:
15061
- * [\`agent-auditor\`](../agent-auditor/SKILL.md) inspects deliverables for structural debt, premature generalizations, or unneeded complexity (YAGNI).
15062
- * [\`agent-adversary\`](../agent-adversary/SKILL.md) actively stress-tests deliverables: uncovers requirement contradictions, simulates architectural race conditions/SPOFs, conducts conceptual mutation testing on QA suites, or crafts breaking boundary payloads for code with mandatory proof-of-break.
15063
- - **Non-Invasive Guardrail**: Neither auditor nor adversary edits files directly. Both emit structured findings citing canonical IDs and SHA-256 hashes.
15064
- - **Consolidated Handoff & Remediation Re-Execution**: Consolidate findings and emit the Workflow Handoff back to the audited authoring agent, who is re-executed to resolve the findings.
15065
- - **Anti-Ping-Pong Guardrail (Max 2 Rounds)**: Enforce a strict boundary of maximum **2 correction rounds** per phase/deliverable. If non-blocking advisories remain after round 2, proceed downstream; if blocking defects persist after round 2, escalate to the Human Tech Lead.
15066
- - **Exclusion of Downstream Review & Validation Roles**: Pre-merge review agents (\`agent-code-reviewer\`, \`agent-security-auditor\`, \`agent-compliance-checker\`) and validation agents (\`agent-expert-user\`) evaluate finished deliverables and are excluded from being audited by this loop.
15067
-
15068
- ### Step 6: Post-Development Functional Validation & Pre-Merge Audit Triad
15069
- 1. **Functional Validation (\`agent-expert-user\`)**: Validate live runtime behavior against \`UC-*\` and \`FR-*\` criteria (including \`0\` browser \`console.error\`/\`pageerror\` on UI changes).
15070
- 2. **Pre-Merge Audit Triad**: Execute concurrent review across:
15071
- - [\`agent-code-reviewer\`](../agent-code-reviewer/SKILL.md) (SOLID, DRY, YAGNI, AST thresholds, zero fake-wiring)
15072
- - [\`agent-security-auditor\`](../agent-security-auditor/SKILL.md) (\`verify_security\`: Gitleaks secrets + OWASP SAST)
15073
- - [\`agent-privacy-officer\`](../agent-privacy-officer/SKILL.md) (\`verify_privacy\`: GDPR/LOPDGDD ROPA + PII-SAST)
15074
- - [\`agent-compliance-checker\`](../agent-compliance-checker/SKILL.md) (\`verify_licenses\`: SPDX & SBOM compliance)
15075
- 3. **Consolidated Release Gate**: Run MCP tool \`verify\` (\`npx aisdlc verify all\`) and confirm all **12 Quality Gates** pass green.
15076
-
15077
- ### Step 7: Human PR Sign-Off, Baseline Integration & Release Closure
15078
- 1. **Feature Merge (\`feat/CHG-*\` \u2794 \`release/vX.Y.Z\`)**: Present the PR, KPI summary (\`kpi_pr\`), and autogenerated reports (\`reports/QUALITY_REPORT.md\`, \`reports/TRACEABILITY_MATRIX.md\`, \`reports/ROPA_INVENTORY.md\`) to the human Tech Lead for review and approval (never auto-approve or auto-merge).
15079
- 2. **Canonical Baseline Promotion**: Once tasks in \`tasks.md\` are marked \`COMPLETED\` and approved, promote the change into the canonical baseline via MCP tool \`sdd_integrate\` (\`npx aisdlc sdd integrate --auto\`, or \`npx aisdlc sdd integrate --all\` to consolidate all completed changes), which synchronizes the normative text and BDD Gherkin scenarios into \`FR-*\` / \`UC-*\` / \`SEC-REQ-*\` / \`PRIV-REQ-*\`, bumps minor SemVer when updating active specs, resyncs PDaC SHA-256 digests, promotes \`FR-*\` to \`active\`, links \`CMP-*\`, and archives the change under \`specs/changes/completed/\`.
15080
- 3. **Release Milestone Closure (\`release/vX.Y.Z\` \u2794 \`main\`)**: When all \`CHG-*\` increments planned for \`release/vX.Y.Z\` are integrated:
15081
- - Run full verification (\`verify\`), generate CycloneDX SBOM & legal notices (\`npx aisdlc verify licenses --sbom reports/sbom.cdx.json --notices THIRD_PARTY_NOTICES.md\`), compute release telemetry (\`kpi_release\` / \`npx aisdlc kpi release --release release/vX.Y.Z\`), and refresh the interactive dashboard (\`report_dashboard\`).
15082
- - Open the Release PR from \`release/vX.Y.Z\` to \`main\` for final human Product Owner and Release Manager approval and semantic Git tagging (\`vX.Y.Z\`).
15083
-
15084
- ## Non-Negotiable Guardrails
15085
- - **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles (e.g., \`agent-qa-engineer\` and \`agent-developer\`, or \`agent-developer\` and \`agent-security-auditor\`) in the same conversation context window. In subagent-capable IDEs (Antigravity \`invoke_subagent\`, Claude Code \`Task\` / \`.claude/agents/\`, GitHub Copilot \`@agent-*\`), always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk (\`specs/\`, \`handoff.yaml\`, \`get_active_handoff\`). In chat-based IDEs (Cursor, Windsurf, Aider), persist all artifacts to disk, emit the Workflow Handoff block, and instruct the user to open a **New Chat** (or \`/clear\`) before running the next specialist.
15086
- - **Mandatory Transversal Quality & Adversarial Loop**: Every authoring agent deliverable must undergo concurrent inspection by \`agent-auditor\` and \`agent-adversary\` in isolated context windows, followed by a re-execution of the authoring agent to remediate findings. To prevent infinite cycles, enforce the **Anti-Ping-Pong Guardrail**: maximum 2 correction rounds per phase; if unresolved blocking defects persist after round 2, escalate to the Human Tech Lead.
15087
- - **Single-Use-Case Scope (\`1 UC-* = 1 CHG-*\`)**: Each SDD change (\`CHG-*\`) must deliver at most 1 Use Case (\`UC-*\`). Bundling multiple \`UC-*\` into one \`handoff.yaml\` is blocked by \`verify_governance\` (\`Greenfield monolith detected\`). Scale throughput via parallel \`CHG-*\` branches/worktrees, not monolithic changes.
15088
- - **100% Design & Handoff Coverage in \`tasks.md\`**: Every \`CMP-*\`, \`FR-*\`, \`SEC-REQ-*\`, and \`PRIV-REQ-*\` declared in \`design.md\` and \`handoff.yaml\` must be explicitly assigned to at least one \`TSK-*\` in \`tasks.md\`.`
15023
+ body: '## Purpose & Trigger\nUse this skill for **every evolutionary increment (new feature, enhancement, refactoring, or bugfix)** on a project that already has an AI-SDLC baseline. It enforces strict 360\xB0 traceability from upstream ProductShape (`UC-*`, `FR-*`) through SDD (`CHG-*`, `HOF-*`, `TSK-*`), TDD implementation, the 12 Quality Gates, and baseline promotion under the **streamlined 2-checkpoint architecture**.\n\n## End-to-End Execution Playbook\n\n### Step 1: Upstream Product, Security & Privacy Delta (`agent-product-analyst`, `agent-threat-modeler` & `agent-privacy-officer`)\n1. Inspect active changes via MCP tool `get_active_handoff` and verify whether the target Use Case (`UC-*`) or Requirement (`FR-*`) already exists in `specs/product/`.\n2. If the increment introduces new behavior or modifies business rules:\n - Use [`agent-product-analyst`](../agent-product-analyst/SKILL.md) to create or update the `UC-*`, `BR-*`, and `FR-*` (with `@nominal`, `@boundary`, `@invalid` Gherkin scenarios).\n - Run MCP tool `verify_duplicates` (`npx aisdlc verify duplicates`) to block lexical or functional collisions early.\n - Use [`agent-threat-modeler`](../agent-threat-modeler/SKILL.md) to model any new `ABUSE-*` and `SEC-REQ-*` mitigations.\n - Hand off to [`agent-privacy-officer`](../agent-privacy-officer/SKILL.md) to model any personal data assets (`DATA-ASSET-*`), GDPR Art. 30 processing activities (`PRIV-ROPA-*`), and privacy requirements (`PRIV-REQ-*`).\n3. Run `sdd_check_fix` (`npx aisdlc check --fix`) to sync Gherkin `.feature` files and validate schemas.\n\n### Step 2: SDD Change Scaffolding & Architectural Design (`agent-system-architect`)\n1. Scaffold the bounded change package and its cryptographic `handoff.yaml` sidecar (`HOF-*`) targeting **a single Use Case (`1 UC-* = 1 CHG-*`)** using MCP tool `sdd_change_new` (or CLI `npx aisdlc change new "<Title>" --from <UC-ID> --profile <patch|standard|critical>`).\n2. Use [`agent-system-architect`](../agent-system-architect/SKILL.md) to complete `specs/changes/active/<chg-id>/design.md` and `specs/architecture/CMP-*.md`:\n - Structure `CMP-*` and `design.md` around **Modular & Hexagonal Architecture (Ports & Adapters)** (Domain/Application Core + Inbound/Outbound Ports) and define **Contract-First** shared interfaces/DTOs/schemas when spanning Frontend and Backend.\n - Map 100% of `handoff.yaml` requirements and components to atomic tasks (`TSK-*`) in `tasks.md` with explicit `autonomy-mode` (`AUTONOMOUS`, `HUMAN_REVIEW_PLAN`, `HIGH_RISK_MANUAL`, `AMBIGUOUS`).\n3. Run `verify_governance` and `verify_friction` to validate task governance, 100% design/handoff scope coverage, and anti-monolith limits (`maxUseCasesPerChange = 1`).\n\n### Checkpoint 1: Specification & Design Checkpoint (`agent-auditor` $\\parallel$ `agent-adversary`)\n1. Concurrently invoke `agent-auditor` (evaluating YAGNI, interface bloat, and task completeness) and `agent-adversary` (probing contradictions, race conditions, and architecture SPOFs) in clean, isolated context windows over the combined upstream deliverables.\n2. Consolidate findings and remediate any blocking defects (max 2 correction rounds).\n3. **Human Approval Gate 1**: Present the specification and architectural design for Human Tech Lead / PO sign-off before proceeding to code.\n\n### Step 3: Streamlined Git Branch Navigation & Multi-Agent Parallelism\n1. Navigate to the working branch using `npx aisdlc git checkout <TSK-ID>` (`pnpm run git:checkout <TSK-ID>`).\n - **Default Streamlined Mode**: Switches to the working branch `feat/<CHG-ID>-<slug>` (created from `main`).\n - Granular task traceability is maintained via commit trailers (`Task-ID: TSK-*`, `Parent-Ref: CHG-*`) and commit scopes (`feat(TSK-001): ...`), enabling per-task rework KPIs without branch explosion.\n2. **Parallel Agent Execution Rules (`--parallel`)**:\n - When concurrent multi-agent implementation is configured (e.g. Backend adapter $\\parallel$ Frontend UI), `aisdlc git checkout <TSK-ID> --parallel` creates isolated worktrees (`task/<PARENT-ID>/<TSK-ID>-<slug>`).\n\n### Step 4: Red Phase \u2014 Failing Test Suites (`agent-qa-engineer`)\n1. Delegate to or adopt [`agent-qa-engineer`](../agent-qa-engineer/SKILL.md).\n2. Author FAILING (red) BDD/Gherkin step definitions, integration/contract tests, and mandatory E2E/UI tests (evaluating Happy Path, Sad Path, and Boundary Values for every interactive UI element, plus `UC-*` alternative/exception flows) in `tests/`.\n3. Commit failing test suites with trailer `Task-ID: TSK-YYY`.\n4. Run `verify_testing` (`npx aisdlc verify testing`) to confirm requirement test coverage before writing production code.\n\n### Step 5: Green & Refactor Phase \u2014 Surgical Implementation (`agent-developer`)\n1. Delegate to or adopt [`agent-developer`](../agent-developer/SKILL.md).\n2. Execute the **Mandatory 4-Step Implementation Order**:\n - (1) Modular & Hexagonal Architecture (Ports & Adapters) boundaries, (2) Inter-module interfaces/ports first, (3) Concrete component implementation (zero fake-wiring; all 4 UI states `Loading`, `Empty`, `Error`, `Nominal`), (4) Exhaustive per-function unit tests in `tests/unit/` (Happy Path, Sad Path, Boundary, Null/Empty).\n3. Commit implementations with trailer `Task-ID: TSK-YYY`.\n4. Verify any new dependency against `license-policy.yaml` via `verify_licenses` and PII handling against `privacy-policy.yaml` via `verify_privacy`.\n5. Run `sdd_check_fix` (`npx aisdlc check --fix`) and `verify_quality` (`npx aisdlc verify quality`) until Cyclomatic Complexity $\\le 10$, Cognitive $\\le 15$, Maintainability $\\ge 50$, and Function Length $\\le 40$ lines pass with zero violations.\n6. Run `verify` (`npx aisdlc verify all`) confirming all **12 Quality Gates** pass green.\n\n### Checkpoint 2: Implementation & Pre-PR Checkpoint (`agent-auditor` $\\parallel$ `agent-adversary`)\n1. **Functional Validation (`agent-expert-user`)**: Validate live runtime behavior against `UC-*` and `FR-*` criteria (including `0` browser `console.error`/`pageerror` on UI changes).\n2. Concurrently invoke `agent-auditor` (verifying Clean Code, SOLID, DRY, AST thresholds, and eliminating unnecessary abstractions) and `agent-adversary` (performing conceptual test mutation to verify QA tests catch defects, and attacking boundary inputs with concrete PoC breaks).\n3. Consolidate findings and remediate in `agent-developer` (max 2 correction rounds).\n4. Run `npx aisdlc verify all` to confirm final green status.\n\n### Step 6: Human PR Sign-Off, Baseline Integration & Release Closure\n1. **Feature Merge (`feat/CHG-*` \u2794 `main` or `release/vX.Y.Z`)**:\n - Present the PR, KPI summary (`kpi_pr` including per-task rework metrics), and autogenerated reports (`reports/QUALITY_REPORT.md`, `reports/TRACEABILITY_MATRIX.md`, `reports/ROPA_INVENTORY.md`) to the human Tech Lead for review and approval (never auto-approve or auto-merge).\n2. **Canonical Baseline Promotion**: Once tasks in `tasks.md` are marked `COMPLETED` and approved, promote the change into the canonical baseline via MCP tool `sdd_integrate` (`npx aisdlc sdd integrate --auto`), which synchronizes the normative text and BDD Gherkin scenarios into `FR-*` / `UC-*` / `SEC-REQ-*` / `PRIV-REQ-*`, bumps minor SemVer when updating active specs, resyncs PDaC SHA-256 digests, promotes `FR-*` to `active`, links `CMP-*`, and archives the change under `specs/changes/completed/` (or `npx aisdlc sdd integrate --all` to consolidate all completed changes).\n3. **Semantic Versioning Promotion**: Tag the merge with the computed SemVer bump (`patch`, `minor`, `major`) and refresh the interactive dashboard (`report_dashboard`).\n\n## Non-Negotiable Guardrails\n- **Clean Context Window Isolation per Specialist Agent (Cross-IDE)**: Never execute two distinct specialist roles (e.g., `agent-qa-engineer` and `agent-developer`, or `agent-developer` and `agent-security-auditor`) in the same conversation context window. In subagent-capable IDEs (Antigravity `invoke_subagent`, Claude Code `Task` / `.claude/agents/`, GitHub Copilot `@agent-*`), always spawn each specialist in a fresh isolated subagent context that reads state strictly from disk (`specs/`, `handoff.yaml`, `get_active_handoff`). In chat-based IDEs (Cursor, Windsurf, Aider), persist all artifacts to disk, emit the Workflow Handoff block, and instruct the user to open a **New Chat** (or `/clear`) before running the next specialist.\n- **2-Checkpoint Quality & Adversarial Protocol**: Enforce transversal quality and red-team checks exclusively at **Checkpoint 1 (Specification & Design)** and **Checkpoint 2 (Implementation & Pre-PR)**. Enforce the **Anti-Ping-Pong Guardrail**: maximum 2 correction rounds per checkpoint; if unresolved blocking defects persist, escalate to the Human Tech Lead.\n- **Single-Use-Case Scope (`1 UC-* = 1 CHG-*`)**: Each SDD change (`CHG-*`) must deliver at most 1 Use Case (`UC-*`). Bundling multiple `UC-*` into one `handoff.yaml` is blocked by `verify_governance` (`Greenfield monolith detected`). Scale throughput via parallel `CHG-*` branches/worktrees, not monolithic changes.\n- **100% Design & Handoff Coverage in `tasks.md`**: Every `CMP-*`, `FR-*`, `SEC-REQ-*`, and `PRIV-REQ-*` declared in `design.md` and `handoff.yaml` must be explicitly assigned to at least one `TSK-*` in `tasks.md`.'
15089
15024
  }
15090
15025
  ];
15091
15026
  function renderAntigravitySkillFile(skill) {
@@ -18852,6 +18787,7 @@ exports.CPP_CMAKE_STRICT = CPP_CMAKE_STRICT;
18852
18787
  exports.DEFAULT_DLP_RULES = DEFAULT_DLP_RULES;
18853
18788
  exports.DEFAULT_EXCLUDED_PATTERNS = DEFAULT_EXCLUDED_PATTERNS;
18854
18789
  exports.DEFAULT_EXCLUDES = DEFAULT_EXCLUDES;
18790
+ exports.DEFAULT_EXCLUDE_DIRS = DEFAULT_EXCLUDE_DIRS;
18855
18791
  exports.DEFAULT_EXTENSIONS = DEFAULT_EXTENSIONS;
18856
18792
  exports.DEFAULT_PRIVACY_POLICY = DEFAULT_PRIVACY_POLICY;
18857
18793
  exports.DEFAULT_SAST_EXCLUDES = DEFAULT_SAST_EXCLUDES;
@@ -19006,6 +18942,7 @@ exports.VALID_AUTONOMY_MODES = VALID_AUTONOMY_MODES;
19006
18942
  exports.VALID_CHANGE_PROFILES = VALID_CHANGE_PROFILES;
19007
18943
  exports.VALID_CI_PROVIDERS = VALID_CI_PROVIDERS;
19008
18944
  exports.VALID_CODING_RULE_STACKS = VALID_CODING_RULE_STACKS;
18945
+ exports.accumulateTaskSummaries = accumulateTaskSummaries;
19009
18946
  exports.aggregateCommitKpiRecords = aggregateCommitKpiRecords;
19010
18947
  exports.aggregatePrKpis = aggregatePrKpis;
19011
18948
  exports.aggregateReleaseKpis = aggregateReleaseKpis;
@@ -19070,6 +19007,7 @@ exports.formatCommitTrailers = formatCommitTrailers;
19070
19007
  exports.formatInspectResultMarkdown = formatInspectResultMarkdown;
19071
19008
  exports.formatPrKpiMarkdown = formatPrKpiMarkdown;
19072
19009
  exports.formatReleaseKpiMarkdown = formatReleaseKpiMarkdown;
19010
+ exports.formatTaskKpiRows = formatTaskKpiRows;
19073
19011
  exports.generateBranchHierarchyPlan = generateBranchHierarchyPlan;
19074
19012
  exports.generateCycloneDxSbom = generateCycloneDxSbom;
19075
19013
  exports.generateDashboardReport = generateDashboardReport;