create-project-arch 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-03-12
+
+### Added
+
+- Scaffolded projects now receive 8 bootstrap architecture tasks on `pa init` (previously 5)
+- New bootstrap tasks 006 `define-system-boundaries`, 007 `define-module-model`, and 008 `define-runtime-architecture` included in generated milestone
+- Bootstrap tasks 006–008 carry `discover` and `greenfield` tags for dual-mode authoring guidance
+- `pa milestone status` command available in all scaffolded projects for dependency-aware task blocking visibility
+
+### Changed
+
+- Updated templates to use `project-arch@1.5.0`
+- Bootstrap task 005 slug updated to `finalize-architecture-foundation` in all scaffolded projects
+- task 005 in generated projects now declares `dependsOn` on tasks 001–004 and 006–008, enforcing correct completion order
+
+---
+
 ## [1.4.0] - 2026-03-10
 
 ### Added

package/README.md

@@ -223,9 +223,11 @@ Scaffolded projects include closure report artifacts under `architecture/referen
 Recommended workflow:
 
 1. Complete milestone tasks and decision updates.
-2. Run `pa check` and `pa report`.
-3. Record closure outcomes in milestone closure report.
-4. Track remaining gaps as follow-on tasks/decisions.
+2. Run `pa lint frontmatter --fix`.
+3. Run `pnpm lint:md`.
+4. Run `pa check` and `pa report`.
+5. Record closure outcomes in milestone closure report.
+6. Track remaining gaps as follow-on tasks/decisions.
 
 ### Local Validation Hook Scaffold
 

package/dist/cli.js

@@ -8,6 +8,7 @@ const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const child_process_1 = require("child_process");
 const commander_1 = require("commander");
+const projectNameValidation_1 = require("./projectNameValidation");
 function getTemplatesRoot() {
     return path_1.default.resolve(__dirname, "../templates");
 }
@@ -104,6 +105,67 @@ async function wireProjectArchUsage(targetDir) {
     await fs_extra_1.default.writeJSON(rootPackageJsonPath, nextPkg, { spaces: 2 });
     await fs_extra_1.default.appendFile(rootPackageJsonPath, "\n");
 }
+async function normalizeTurboSchema(targetDir) {
+    const turboConfigPath = path_1.default.join(targetDir, "turbo.json");
+    if (!(await fs_extra_1.default.pathExists(turboConfigPath))) {
+        return;
+    }
+    const turboConfig = (await fs_extra_1.default.readJSON(turboConfigPath));
+    const existingGlobalEnv = Array.isArray(turboConfig.globalEnv)
+        ? turboConfig.globalEnv.filter((entry) => typeof entry === "string")
+        : [];
+    const globalEnv = existingGlobalEnv.includes("PROJECT_ROOT")
+        ? existingGlobalEnv
+        : [...existingGlobalEnv, "PROJECT_ROOT"];
+    await fs_extra_1.default.writeJSON(turboConfigPath, {
+        ...turboConfig,
+        $schema: "./node_modules/turbo/schema.json",
+        globalEnv,
+    }, { spaces: 2 });
+    await fs_extra_1.default.appendFile(turboConfigPath, "\n");
+}
+function getAppReadmeContent(title, appDir) {
+    return [
+        `# ${title}`,
+        "",
+        `This app lives in \`${appDir}\` and is part of the generated workspace.`,
+        "",
+        "## Getting Started",
+        "",
+        "Run from the repository root:",
+        "",
+        "```bash",
+        `pnpm --filter ${appDir.split("/").pop()} dev`,
+        "```",
+        "",
+        "Or run all apps in dev mode:",
+        "",
+        "```bash",
+        "pnpm dev",
+        "```",
+        "",
+    ].join("\n");
+}
+async function normalizeGeneratedAppReadmes(targetDir) {
+    const readmeTargets = [
+        {
+            readmePath: path_1.default.join(targetDir, "apps", "web", "README.md"),
+            title: "Web App",
+            appDir: "apps/web",
+        },
+        {
+            readmePath: path_1.default.join(targetDir, "apps", "docs", "README.md"),
+            title: "Docs App",
+            appDir: "apps/docs",
+        },
+    ];
+    for (const target of readmeTargets) {
+        if (!(await fs_extra_1.default.pathExists(target.readmePath))) {
+            continue;
+        }
+        await fs_extra_1.default.writeFile(target.readmePath, getAppReadmeContent(target.title, target.appDir), "utf8");
+    }
+}
 async function scaffoldArchitectureApps(targetDir) {
     const templatesRoot = getTemplatesRoot();
     const archUiTemplate = path_1.default.join(templatesRoot, "arch-ui");
@@ -339,9 +401,7 @@ async function main() {
         if (projectName === "." || projectName === "./") {
             throw new Error("Refusing to scaffold into current directory. Provide a new project directory name.");
         }
-        if (!/^[a-zA-Z0-9-_]+$/.test(projectName)) {
-            throw new Error("Invalid project name. Only alphanumeric characters, dashes, and underscores are allowed.");
-        }
+        (0, projectNameValidation_1.validateProjectName)(projectName);
         const targetDir = path_1.default.resolve(process.cwd(), projectName);
         await ensureTargetDir(targetDir, options.force);
         runCreateTurbo(projectName, options);
@@ -367,6 +427,8 @@ async function main() {
         await scaffoldArchitectureApps(targetDir);
         await upsertArchModulesInMap(targetDir);
         await wireProjectArchUsage(targetDir);
+        await normalizeTurboSchema(targetDir);
+        await normalizeGeneratedAppReadmes(targetDir);
         const relativeTarget = path_1.default.relative(process.cwd(), targetDir) || ".";
         console.log(`\nCreated project-arch repo at ${relativeTarget}`);
         console.log("\nNext steps:");

package/dist/projectNameValidation.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateProjectName = validateProjectName;
+const npmPackageNamePattern = /^[a-z0-9-~][a-z0-9-._~]*$/;
+const npmReservedNames = new Set(["node_modules", "favicon.ico"]);
+function toNpmNameSuggestion(projectName) {
+    return projectName
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, "-");
+}
+function validateProjectName(projectName) {
+    if (!/^[a-zA-Z0-9-_]+$/.test(projectName)) {
+        throw new Error("Invalid project name. Only alphanumeric characters, dashes, and underscores are allowed.");
+    }
+    if (projectName !== projectName.toLowerCase()) {
+        throw new Error(`Invalid project name '${projectName}'. Use lowercase to produce a valid npm package name (for example: '${toNpmNameSuggestion(projectName)}').`);
+    }
+    if (projectName.length > 214) {
+        throw new Error("Invalid project name. npm package names must be 214 characters or fewer.");
+    }
+    if (!npmPackageNamePattern.test(projectName) || npmReservedNames.has(projectName)) {
+        throw new Error(`Invalid project name '${projectName}'. It must be a valid npm package name.`);
+    }
+}

package/dist/projectNameValidation.test.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const projectNameValidation_1 = require("./projectNameValidation");
+(0, vitest_1.describe)("validateProjectName", () => {
+    (0, vitest_1.it)("accepts valid lowercase project names", () => {
+        (0, vitest_1.expect)(() => (0, projectNameValidation_1.validateProjectName)("project-arch")).not.toThrow();
+        (0, vitest_1.expect)(() => (0, projectNameValidation_1.validateProjectName)("project_arch_2")).not.toThrow();
+    });
+    (0, vitest_1.it)("rejects uppercase names with actionable guidance", () => {
+        (0, vitest_1.expect)(() => (0, projectNameValidation_1.validateProjectName)("testProject")).toThrow("Use lowercase to produce a valid npm package name");
+    });
+    (0, vitest_1.it)("rejects invalid characters", () => {
+        (0, vitest_1.expect)(() => (0, projectNameValidation_1.validateProjectName)("my project")).toThrow("Only alphanumeric characters, dashes, and underscores are allowed.");
+    });
+    (0, vitest_1.it)("rejects npm reserved names", () => {
+        (0, vitest_1.expect)(() => (0, projectNameValidation_1.validateProjectName)("node_modules")).toThrow("It must be a valid npm package name.");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-project-arch",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Scaffold new projects with Project Arch templates including Next.js apps and component libraries",
   "keywords": [
     "create",
@@ -37,7 +37,7 @@
   "dependencies": {
     "commander": "^12.1.0",
     "fs-extra": "^11.3.0",
-    "project-arch": "^1.3.0"
+    "project-arch": "^1.5.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/arch-ui/app/work/page.tsx

@@ -118,7 +118,7 @@ export default function WorkPage() {
       (Object.entries(filters.edgeTypes) as Array<[keyof typeof filters.edgeTypes, boolean]>)
         .filter(([, enabled]) => enabled)
         .map(([filter]) => filter as GraphEdgeFilter),
-    [filters.edgeTypes],
+    [filters],
   );
   const activeAuthorityFilters = useMemo(
     () =>
@@ -129,7 +129,7 @@ export default function WorkPage() {
       )
         .filter(([, enabled]) => enabled)
         .map(([filter]) => filter),
-    [filters.authorityTypes],
+    [filters],
   );
 
   return (

package/templates/arch-ui/components/graph-canvas.tsx

@@ -59,6 +59,12 @@ type GraphCanvasProps = {
 
 export { type GraphFilter, type InspectorNode } from "./graph/graph-types";
 
+const VIEW_CANONICAL_TYPES: Record<GraphCanvasViewMode, string[]> = {
+  "architecture-map": ["arch_folder", "domain_doc", "architecture_doc", "architecture_model"],
+  tasks: ["roadmap_folder", "roadmap_epic", "roadmap_story", "roadmap_task"],
+  project: ["project_folder", "app", "package", "module", "component"],
+};
+
 export function GraphCanvas({
   data,
   viewMode,
@@ -124,11 +130,6 @@ export function GraphCanvas({
   }, [nodes]);
 
   const behavior = GRAPH_VIEW_BEHAVIOR[viewMode];
-  const viewCanonicalTypes: Record<GraphCanvasViewMode, string[]> = {
-    "architecture-map": ["arch_folder", "domain_doc", "architecture_doc", "architecture_model"],
-    tasks: ["roadmap_folder", "roadmap_epic", "roadmap_story", "roadmap_task"],
-    project: ["project_folder", "app", "package", "module", "component"],
-  };
   const effectiveHopDepth = useMemo(() => {
     const min = Math.min(...behavior.allowedHopDepths);
     const max = Math.max(...behavior.allowedHopDepths);
@@ -507,7 +508,7 @@ export function GraphCanvas({
     if (!stored) return;
     if (selectedNodeId) return;
     const selected = nodes.find((node) => node.id === stored);
-    if (selected && viewCanonicalTypes[viewMode].includes(selected.data.canonicalType ?? "")) {
+    if (selected && VIEW_CANONICAL_TYPES[viewMode].includes(selected.data.canonicalType ?? "")) {
       setSelectedNodeId(stored);
       return;
     }
@@ -516,7 +517,7 @@ export function GraphCanvas({
     const candidateId = mapped.source === stored ? mapped.target : mapped.source;
     const candidateNode = nodes.find((node) => node.id === candidateId);
     if (!candidateNode) return;
-    if (!viewCanonicalTypes[viewMode].includes(candidateNode.data.canonicalType ?? "")) return;
+    if (!VIEW_CANONICAL_TYPES[viewMode].includes(candidateNode.data.canonicalType ?? "")) return;
     setSelectedNodeId(candidateId);
   }, [edges, nodes, selectedNodeId, viewMode]);
 

package/templates/arch-ui/components/workspace-context.tsx

@@ -18,15 +18,6 @@ type WorkspaceFilters = {
   hopDepth: number;
 };
 
-type WorkspacePersistedState = {
-  splitPane: boolean;
-  leftCollapsed: boolean;
-  rightCollapsed: boolean;
-  leftWidth: number;
-  rightWidth: number;
-  filtersByView: Record<GraphViewMode, WorkspaceFilters>;
-};
-
 type WorkspaceContextValue = {
   splitPane: boolean;
   leftCollapsed: boolean;
@@ -127,36 +118,38 @@ export function WorkspaceProvider({ children }: { children: ReactNode }) {
       if (typeof parsed.rightWidth === "number") setRightWidth(clamp(parsed.rightWidth, 320, 720));
       if (parsed.filtersByView) {
         const views: GraphViewMode[] = ["architecture-map", "tasks", "project"];
-        const nextByView = { ...filtersByView };
-        for (const view of views) {
-          const incoming = parsed.filtersByView[view];
-          if (!incoming) continue;
-          const base = defaultFilters();
-          nextByView[view] = {
-            nodeTypes: {
-              domains: incoming.nodeTypes?.domains ?? base.nodeTypes.domains,
-              modules: incoming.nodeTypes?.modules ?? base.nodeTypes.modules,
-              tasks: incoming.nodeTypes?.tasks ?? base.nodeTypes.tasks,
-              decisions: incoming.nodeTypes?.decisions ?? base.nodeTypes.decisions,
-            },
-            edgeTypes: {
-              dependency: incoming.edgeTypes?.dependency ?? base.edgeTypes.dependency,
-              "data-flow": incoming.edgeTypes?.["data-flow"] ?? base.edgeTypes["data-flow"],
-              blocking: incoming.edgeTypes?.blocking ?? base.edgeTypes.blocking,
-            },
-            authorityTypes: {
-              authoritative:
-                incoming.authorityTypes?.authoritative ?? base.authorityTypes.authoritative,
-              manual: incoming.authorityTypes?.manual ?? base.authorityTypes.manual,
-              inferred: incoming.authorityTypes?.inferred ?? base.authorityTypes.inferred,
-            },
-            hideCompletedTasks: incoming.hideCompletedTasks ?? base.hideCompletedTasks,
-            showExternalDependencies:
-              incoming.showExternalDependencies ?? base.showExternalDependencies,
-            hopDepth: clamp(incoming.hopDepth ?? base.hopDepth, 0, 3),
-          };
-        }
-        setFiltersByView(nextByView);
+        setFiltersByView((prev) => {
+          const nextByView = { ...prev };
+          for (const view of views) {
+            const incoming = parsed.filtersByView?.[view];
+            if (!incoming) continue;
+            const base = defaultFilters();
+            nextByView[view] = {
+              nodeTypes: {
+                domains: incoming.nodeTypes?.domains ?? base.nodeTypes.domains,
+                modules: incoming.nodeTypes?.modules ?? base.nodeTypes.modules,
+                tasks: incoming.nodeTypes?.tasks ?? base.nodeTypes.tasks,
+                decisions: incoming.nodeTypes?.decisions ?? base.nodeTypes.decisions,
+              },
+              edgeTypes: {
+                dependency: incoming.edgeTypes?.dependency ?? base.edgeTypes.dependency,
+                "data-flow": incoming.edgeTypes?.["data-flow"] ?? base.edgeTypes["data-flow"],
+                blocking: incoming.edgeTypes?.blocking ?? base.edgeTypes.blocking,
+              },
+              authorityTypes: {
+                authoritative:
+                  incoming.authorityTypes?.authoritative ?? base.authorityTypes.authoritative,
+                manual: incoming.authorityTypes?.manual ?? base.authorityTypes.manual,
+                inferred: incoming.authorityTypes?.inferred ?? base.authorityTypes.inferred,
+              },
+              hideCompletedTasks: incoming.hideCompletedTasks ?? base.hideCompletedTasks,
+              showExternalDependencies:
+                incoming.showExternalDependencies ?? base.showExternalDependencies,
+              hopDepth: clamp(incoming.hopDepth ?? base.hopDepth, 0, 3),
+            };
+          }
+          return nextByView;
+        });
       }
     } catch {
       // Ignore invalid persisted state.

package/templates/arch-ui/eslint.config.js

@@ -1,2 +1,4 @@
-import { nextJsConfig } from '@repo/eslint-config/next-js';
+import { nextJsConfig } from "@repo/eslint-config/next-js";
+
+/** @type {import("eslint").Linter.Config[]} */
 export default nextJsConfig;

package/templates/arch-ui/lib/graph-dataset.ts

@@ -67,8 +67,6 @@ async function walkDirectories(
   onDirectory: (relativePath: string, parentRelativePath: string | null) => Promise<void> | void,
   maxDepth = 6,
 ): Promise<void> {
-  const start = path.join(root, relativeDir);
-
   async function walk(currentRelative: string, parentRelative: string | null, depth: number) {
     if (depth > maxDepth) return;
     await onDirectory(currentRelative, parentRelative);
@@ -138,7 +136,7 @@ async function filterGitIgnoredPaths(root: string, paths: string[]): Promise<Set
       }
     }
     return ignored;
-  } catch (error) {
+  } catch {
     // If git is unavailable or command fails unexpectedly, do not block graph generation.
     return new Set();
   }

package/templates/arch-ui/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/arch-ui/package.json

@@ -35,3 +35,4 @@
     "typescript": "5.9.2"
   }
 }
+

package/templates/gap-closure/GAP_CLOSURE_TEMPLATE.md

@@ -23,6 +23,8 @@
 
 - [ ] Architecture docs updated
 - [ ] Roadmap tasks/decisions synchronized
+- [ ] Frontmatter preflight lint passes (`pa lint frontmatter --fix`)
+- [ ] Markdown lint passes (`pnpm lint:md`)
 - [ ] Graph/parity checks pass (`pa check`)
 - [ ] Report diagnostics reviewed (`pa report`)
 

package/templates/gap-closure/README.md

@@ -10,8 +10,10 @@ Create/update a closure report when a milestone reaches completion readiness.
 
 1. Copy `GAP_CLOSURE_TEMPLATE.md` into the milestone or reference location.
 2. Fill each section with concrete findings and evidence.
-3. Run validation commands (`pa check`, `pa report`) and record outcomes.
-4. Track unresolved items as follow-on tasks/decisions.
+3. Run `pa lint frontmatter --fix`.
+4. Run `pnpm lint:md`.
+5. Run `pa check` and `pa report`, then record outcomes.
+6. Track unresolved items as follow-on tasks/decisions.
 
 ## Suggested Locations
 

package/templates/gap-closure/example-gap-closure.md

@@ -19,6 +19,8 @@ Milestone scope is complete, critical architecture artifacts are synchronized, a
 
 - [x] Architecture docs updated
 - [x] Roadmap tasks/decisions synchronized
+- [x] Frontmatter preflight lint passes (`pa lint frontmatter --fix`)
+- [x] Markdown lint passes (`pnpm lint:md`)
 - [x] Graph/parity checks pass (`pa check`)
 - [x] Report diagnostics reviewed (`pa report`)