@phuc1403/musketeer 0.3.0 → 0.5.0

package/template/.claude/skills/architecture-characteristic-writer/assets/worksheet-template.md

@@ -1,40 +1,29 @@
 # Architecture Characteristics Worksheet
 
-| Field | Value |
-|---|---|
-| **System/Project** | {system_name} |
-| **Domain/Quantum** | {domain_quantum} |
-| **Architect/Team** | {architect_team} |
-| **Date** | {date} |
-| **Next Review** | {next_review} |
-
----
+Derived from the top 7 of `architecture-characteristics-ranking.md`.
 
-## Driving Characteristics (up to 7)
+## Driving Characteristics
 
-<!-- Rationale = WHY the system needs this (business driver / risk), never HOW it's delivered.
-     No libraries, patterns, components, or tactics (e.g. ports/adapters, load-balancer, caching). -->
+<!-- From the top 7 of the ranking, in ranked order.
+     A composite replaces its components only when EVERY component is in the top 7:
+       agility     = maintainability + testability + deployability
+       reliability = availability + testability + data integrity + data consistency + fault tolerance
+     Never list a composite and its components together.
+     No backfill: fewer than 7 rows is expected once a composite forms.
+     Rationale = WHY the system needs this, meaning the business driver or risk.
+     Never name the mechanism: no patterns, libraries, components, or tactics. -->
 
-| # | Characteristic | Top 3 | Rationale |
-|---|---|---|---|
-| 1 | {char1} | {yes/no} | {rationale1} |
-| 2 | {char2} | {yes/no} | {rationale2} |
+| # | Characteristic | Rationale |
+|---|---|---|
+| 1 | {char1} | {rationale1} |
+| 2 | {char2} | {rationale2} |
 
 ## Implicit Characteristics
 
-Only list implicit characteristics (feasibility, security, maintainability, observability) NOT already in Driving Characteristics. Composites (agility, reliability) can appear in either section.
-
-<!-- Notes = WHY this is only implicit (e.g. "low stakes — no sensitive data") + residual risk, never what to build. -->
+<!-- The four implicit characteristics are feasibility, security, maintainability, observability.
+     List only those NOT in the top 7. A characteristic absorbed into a composite counts as present.
+     Notes = why it is only implicit, plus the risk that leaves. Never what to build. -->
 
 | Characteristic | Notes |
 |---|---|
-| {implicit1} | {notes} |
-
-## Others Considered
-
-| Characteristic | Reason Not Selected |
-|---|---|
-| {other1} | {reason1} |
-| {other2} | {reason2} |
-
----
+| {implicit1} | {notes1} |

package/template/.claude/skills/architecture-characteristic-writer/references/characteristics-catalog.md

@@ -1,33 +1,29 @@
 # Architecture Characteristics Catalog
 
-Based on Mark Richards' Architecture Characteristics Worksheet (DeveloperToArchitect.com, March 2024) and "Software Architecture" reference material.
-
 ## Common Architecture Characteristics
 
-| Characteristic | Definition | Related |
-|---|---|---|
-| **performance** | Time it takes for system to process a business request | a |
-| **responsiveness** | Time it takes to get a response to the user | a |
-| **availability** | Uptime of a system; usually measured in 9's (e.g., 99.9%) | b |
-| **fault tolerance** | When fatal errors occur, other parts of system continue to function | b |
-| **scalability** | System capacity and growth over time; as users/requests increase, responsiveness, performance, and error rates remain constant | c |
-| **elasticity** | System can expand and respond quickly to unexpected or anticipated extreme loads (e.g., 20 to 250,000 users instantly) | c |
-| **data integrity** | Data across the system is correct and there is no data loss | d |
-| **data consistency** | Data across the system is in sync and consistent across databases and tables | d |
-| **adaptability** | Ease in which system can adapt to changes in environment and functionality | e |
-| **extensibility** | Ease in which system can be extended with additional features and functionality | e |
-| **concurrency** | Ability to process simultaneous requests, usually in the same order received; implied when scalability and elasticity are supported | |
-| **interoperability** | Ability to interface and interact with other systems to complete a business request | |
-| **deployability** | Amount of ceremony involved with releasing software, frequency of releases, and overall risk of deployment | |
-| **testability** | Ease of and completeness of testing | |
-| **abstraction** | Level at which parts of system are isolated from other parts (internal and external interactions) | |
-| **workflow** | Ability to manage complex workflows requiring multiple parts (services) to complete a business request | |
-| **configurability** | Ability to support multiple configurations, custom on-demand configurations and configuration updates | |
-| **recoverability** | Ability to start where it left off in the event of a system crash | |
-
-**Related pairs (a/b):** Some systems only need one, others may need both.
-
-## Implicit Characteristics (Always Considered)
+| Characteristic | Definition |
+|---|---|
+| **performance** | Time it takes for system to process a business request |
+| **responsiveness** | Time it takes to get a response to the user |
+| **availability** | Uptime of a system; usually measured in 9's (e.g., 99.9%) |
+| **fault tolerance** | When fatal errors occur, other parts of system continue to function |
+| **scalability** | System capacity and growth over time; as users/requests increase, responsiveness, performance, and error rates remain constant |
+| **elasticity** | System can expand and respond quickly to unexpected or anticipated extreme loads (e.g., 20 to 250,000 users instantly) |
+| **data integrity** | Data across the system is correct and there is no data loss |
+| **data consistency** | Data across the system is in sync and consistent across databases and tables |
+| **adaptability** | Ease in which system can adapt to changes in environment and functionality |
+| **extensibility** | Ease in which system can be extended with additional features and functionality |
+| **concurrency** | Ability to process simultaneous requests, usually in the same order received; implied when scalability and elasticity are supported |
+| **interoperability** | Ability to interface and interact with other systems to complete a business request |
+| **deployability** | Amount of ceremony involved with releasing software, frequency of releases, and overall risk of deployment |
+| **testability** | Ease of and completeness of testing |
+| **abstraction** | Level at which parts of system are isolated from other parts (internal and external interactions) |
+| **workflow** | Ability to manage complex workflows requiring multiple parts (services) to complete a business request |
+| **configurability** | Ability to support multiple configurations, custom on-demand configurations and configuration updates |
+| **recoverability** | Ability to start where it left off in the event of a system crash |
+
+## Implicit Characteristics
 
 | Characteristic | Definition |
 |---|---|
@@ -36,71 +32,9 @@ Based on Mark Richards' Architecture Characteristics Worksheet (DeveloperToArchi
 | **maintainability** | Level of effort required to locate and apply changes to the system |
 | **observability** | Ability to make available and stream metrics such as overall health, uptime, response times, performance, etc. |
 
-Implicit characteristics become **driving** characteristics if they are critical concerns.
-
 ## Composite Architecture Characteristics
 
 | Composite | Components |
 |---|---|
 | **agility** | maintainability + testability + deployability |
 | **reliability** | availability + testability + data integrity + data consistency + fault tolerance |
-
-## Category Groupings (from reference material)
-
-### Process Characteristics
-modularity, testability, agility, deployability, decouple-ability, extensibility
-
-### Structural Characteristics
-security, maintainability, extensibility, portability, localization
-
-### Operational Characteristics
-scalability, recoverability, robustness, performance, reliability/safety, availability
-
-### Cross-cutting Characteristics
-security, legal, authentication/authorization, privacy, accessibility, usability
-
-## Guiding Questions by Category
-
-### Operational
-- How many concurrent users are expected? Peak vs average?
-- What uptime SLA is required? (99.9%? 99.99%?)
-- Is traffic steady or bursty? (e.g., seasonal spikes, flash sales)
-- How fast must the system respond? (ms? seconds?)
-- What happens if the system goes down? Business impact?
-
-### Structural
-- How frequently will new features be added?
-- How many external systems need integration?
-- How large is the development team? Multiple teams?
-- How often will the system be deployed?
-- Is the codebase expected to grow significantly?
-
-### Cross-cutting
-- Does the system handle sensitive/personal data?
-- Are there compliance requirements? (GDPR, HIPAA, PCI-DSS, SOC2)
-- Does it need to work across regions/languages?
-- Who are the end users? Technical sophistication?
-- Are there legal/regulatory constraints?
-
-### Environment & Feasibility
-- Startup (agility-first) or enterprise (stability-first)?
-- Budget and timeline constraints?
-- Team expertise — what technologies are they comfortable with?
-- Existing infrastructure that must be leveraged?
-
-## Custom Characteristics
-
-If no existing characteristic fits, create a custom one:
-- Name MUST end in `-ility` (e.g., `auditability`, `portability`, `learnability`)
-- Provide a clear, one-sentence definition following the pattern: "The ability/ease/level of [what the system can do]"
-- Assign to the most appropriate category
-- Document why existing characteristics don't cover this concern
-
-### Examples of Custom Characteristics
-| Characteristic | Definition | Category |
-|---|---|---|
-| **auditability** | The ability to trace and record all system actions for compliance review | Cross-cutting |
-| **portability** | The ease in which the system can be moved to a different environment or platform | Structural |
-| **learnability** | The ease in which new developers can understand and contribute to the system | Process |
-| **debuggability** | The ease in which issues can be identified and diagnosed in production | Operational |
-| **reproducibility** | The ability to consistently reproduce system behavior across environments | Process |

package/template/.claude/skills/architecture-characteristic-writer/scripts/ranking-table.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Scaffolds and repairs the architecture-characteristics ranking table.
+//
+//   scaffold  write a blank ranking holding every catalog characteristic
+//   fix       renumber the Order column and rebuild every "Above X:" prefix
+//             from the row order as it now stands, keeping the justifications
+//
+// Ranking ORDER and justification prose are the architect's work. Everything
+// this script touches — which characteristics appear, the numbering, which row
+// each reason compares against — is mechanical, so no one has to transcribe it.
+//
+// Run `fix` after moving rows. A prefix left naming the wrong row is the usual
+// defect after a reorder, and regenerating them makes it impossible.
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadCatalog,
+  normalise,
+  locateTable,
+  splitCells,
+  isSeparator,
+  RANKING_HEADER,
+} = require('../../../hooks/lib/characteristics/checker.cjs');
+
+const DEFAULT_FILE = 'docs/architecture-characteristics-ranking.md';
+
+// The validation hook resolves the ranking against CLAUDE_PROJECT_DIR. Resolve
+// against the same root, or running this from a subdirectory would quietly
+// write a second ranking somewhere the hook never looks at.
+const projectRoot = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const PLACEHOLDER = '{why}';
+const HEADING = '# Architecture Characteristics Ranking';
+
+const PREAMBLE = [
+  HEADING,
+  '',
+  'All characteristics in priority order. The top 7 feed the worksheet in',
+  '`architecture-characteristics.md`.',
+  '',
+  '<!-- Reason = why this row outranks the row directly BELOW it. Comparative, never a description.',
+  '     Keep the "Above {next characteristic}:" prefix and replace {why} with the justification.',
+  '     Both sides must appear: what this row protects, and what the row below gives up.',
+  '     State WHY the system needs it, meaning the business driver or risk.',
+  '     Never name the mechanism: no patterns, libraries, components, or tactics.',
+  '',
+  '     Move rows freely, then run scripts/ranking-table.cjs fix to renumber and',
+  '     rebuild every prefix. Do not hand-maintain the numbering or the prefixes. -->',
+  '',
+];
+
+const die = (msg) => {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+};
+
+// Builds the three table lines plus data rows for the given ordered names,
+// pairing each row with the justification supplied for it.
+function render(order, justifications) {
+  const rows = order.map((name, i) => {
+    const last = i === order.length - 1;
+    const reason = last ? '—' : `Above ${order[i + 1]}: ${justifications[i] || PLACEHOLDER}`;
+    return `| ${i + 1} | ${name} | ${reason} |`;
+  });
+  return ['| Order | Characteristic | Reason |', '|---|---|---|', ...rows];
+}
+
+// Drops an "Above X:" prefix and a lone em dash, leaving the justification the
+// author actually wrote.
+function justificationOf(reason) {
+  const text = String(reason).trim();
+  if (/^[—-]$/.test(text)) return '';
+  const m = text.match(/^above\s+[^:]+:\s*(.*)$/i);
+  return (m ? m[1] : text).trim();
+}
+
+function scaffold(argv) {
+  const out = argv.out || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), out);
+
+  if (fs.existsSync(target) && !argv.force) {
+    die(`${out} already exists. Run fix to repair it, or pass --force to start over.`);
+  }
+
+  const { catalog } = loadCatalog(argv.catalog);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, [...PREAMBLE, ...render(catalog, []), ''].join('\n'), 'utf8');
+
+  process.stdout.write(
+    `Wrote ${out} with ${catalog.length} characteristics in catalog order.\n` +
+      'Reorder the rows, replace every {why}, then run fix.\n'
+  );
+}
+
+function fix(argv) {
+  const file = argv.file || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), file);
+
+  if (!fs.existsSync(target)) die(`${file} does not exist. Run scaffold first.`);
+
+  const original = fs.readFileSync(target, 'utf8');
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  const lines = original.split(/\r?\n/);
+
+  const bounds = locateTable(lines, RANKING_HEADER);
+  if (!bounds) die(`${file} holds no table with a "| Order | Characteristic | Reason |" header row.`);
+
+  const table = lines.slice(bounds.start, bounds.end);
+  const data = table.filter((l) => {
+    const c = splitCells(l);
+    return c.length >= 3 && !isSeparator(c) && !/^order$/i.test(c[0]);
+  });
+
+  if (!data.length) die(`${file} holds no ranking rows to fix.`);
+
+  const order = data.map((l) => normalise(splitCells(l)[1]));
+  const justifications = data.map((l) => justificationOf(splitCells(l)[2]));
+
+  const { catalog } = loadCatalog(argv.catalog);
+  const unknown = order.filter((n) => !catalog.includes(n));
+  if (unknown.length) die(`${file} names characteristics absent from the catalog: ${unknown.join(', ')}`);
+
+  const rebuilt = render(order, justifications);
+  const next = [...lines.slice(0, bounds.start), ...rebuilt, ...lines.slice(bounds.end)];
+  const updated = next.join(eol);
+
+  // Reported whether or not anything moved: a scaffold is already correct and
+  // still has every justification left to write.
+  const blank = justifications.filter((j, i) => i < justifications.length - 1 && (!j || j === PLACEHOLDER)).length;
+  const outstanding = blank ? `${blank} row(s) still need a justification in place of ${PLACEHOLDER}.\n` : '';
+
+  if (updated === original) {
+    process.stdout.write(`${file} is already correct.\n${outstanding}`);
+    return;
+  }
+
+  fs.writeFileSync(target, updated, 'utf8');
+
+  const repaired = data.filter((l, i) => splitCells(l)[2] !== splitCells(rebuilt[i + 2])[2]).length;
+  const renumbered = data.filter((l, i) => splitCells(l)[0] !== String(i + 1)).length;
+
+  process.stdout.write(
+    `Fixed ${file}: renumbered ${renumbered} row(s), rebuilt ${repaired} reason(s).\n${outstanding}`
+  );
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const argv = { force: false };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i];
+    if (flag === '--force') argv.force = true;
+    else if (flag === '--out') argv.out = rest[(i += 1)];
+    else if (flag === '--file') argv.file = rest[(i += 1)];
+    else if (flag === '--catalog') argv.catalog = rest[(i += 1)];
+    else die(`unknown argument: ${flag}`);
+  }
+
+  try {
+    if (command === 'scaffold') return scaffold(argv);
+    if (command === 'fix') return fix(argv);
+  } catch (err) {
+    die(err.message);
+  }
+
+  die('usage: ranking-table.cjs scaffold [--out <path>] [--force] | fix [--file <path>]');
+}
+
+main();

package/template/dotnet-scaffold/src/__SolutionName__.Api/obj/Debug/net10.0/.NETCoreApp,Version=v10.0.AssemblyAttributes.cs

@@ -0,0 +1,4 @@
+// <autogenerated />
+using System;
+using System.Reflection;
+[assembly: global::System.Runtime.Versioning.TargetFrameworkAttribute(".NETCoreApp,Version=v10.0", FrameworkDisplayName = ".NET 10.0")]

package/template/dotnet-scaffold/src/__SolutionName__.Api/obj/Debug/net10.0/__SolutionName__.Api.AssemblyInfo.cs

@@ -0,0 +1,22 @@
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This code was generated by a tool.
+//
+//     Changes to this file may cause incorrect behavior and will be lost if
+//     the code is regenerated.
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+using System;
+using System.Reflection;
+
+[assembly: System.Reflection.AssemblyCompanyAttribute("__SolutionName__.Api")]
+[assembly: System.Reflection.AssemblyConfigurationAttribute("Debug")]
+[assembly: System.Reflection.AssemblyFileVersionAttribute("1.0.0.0")]
+[assembly: System.Reflection.AssemblyInformationalVersionAttribute("1.0.0+b8b9e4e3c73f140ae7b06d954c63afb26d78c687")]
+[assembly: System.Reflection.AssemblyProductAttribute("__SolutionName__.Api")]
+[assembly: System.Reflection.AssemblyTitleAttribute("__SolutionName__.Api")]
+[assembly: System.Reflection.AssemblyVersionAttribute("1.0.0.0")]
+
+// Generated by the MSBuild WriteCodeFragment class.
+

package/template/dotnet-scaffold/src/__SolutionName__.Api/obj/Debug/net10.0/__SolutionName__.Api.AssemblyInfoInputs.cache

@@ -0,0 +1 @@
+922649250c3cbe1ea76366976311f3d76bad60fe3f765d7bf9d3d9b685476c9f

package/template/dotnet-scaffold/src/__SolutionName__.Api/obj/Debug/net10.0/__SolutionName__.Api.GeneratedMSBuildEditorConfig.editorconfig

@@ -0,0 +1,23 @@
+is_global = true
+build_property.TargetFramework = net10.0
+build_property.TargetFrameworkIdentifier = .NETCoreApp
+build_property.TargetFrameworkVersion = v10.0
+build_property.TargetPlatformMinVersion = 
+build_property.UsingMicrosoftNETSdkWeb = true
+build_property.ProjectTypeGuids = 
+build_property.InvariantGlobalization = 
+build_property.PlatformNeutralAssembly = 
+build_property.EnforceExtendedAnalyzerRules = 
+build_property._SupportedPlatformList = Linux,macOS,Windows
+build_property.RootNamespace = __SolutionName__.Api
+build_property.RootNamespace = __SolutionName__.Api
+build_property.ProjectDir = C:\Projects2\Personal\musketeer\template\dotnet-scaffold\src\__SolutionName__.Api\
+build_property.EnableComHosting = 
+build_property.EnableGeneratedComInterfaceComImportInterop = 
+build_property.RazorLangVersion = 9.0
+build_property.SupportLocalizedComponentNames = 
+build_property.GenerateRazorMetadataSourceChecksumAttributes = 
+build_property.MSBuildProjectDirectory = C:\Projects2\Personal\musketeer\template\dotnet-scaffold\src\__SolutionName__.Api
+build_property._RazorSourceGeneratorDebug = 
+build_property.EffectiveAnalysisLevelStyle = 10.0
+build_property.EnableCodeStyleSeverity = 

package/template/dotnet-scaffold/src/__SolutionName__.Api/obj/Debug/net10.0/__SolutionName__.Api.GlobalUsings.g.cs

@@ -0,0 +1,17 @@
+// <auto-generated/>
+global using Microsoft.AspNetCore.Builder;
+global using Microsoft.AspNetCore.Hosting;
+global using Microsoft.AspNetCore.Http;
+global using Microsoft.AspNetCore.Routing;
+global using Microsoft.Extensions.Configuration;
+global using Microsoft.Extensions.DependencyInjection;
+global using Microsoft.Extensions.Hosting;
+global using Microsoft.Extensions.Logging;
+global using System;
+global using System.Collections.Generic;
+global using System.IO;
+global using System.Linq;
+global using System.Net.Http;
+global using System.Net.Http.Json;
+global using System.Threading;
+global using System.Threading.Tasks;