@elvis1513/auto-coding-skill 5.0.5 → 5.1.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/README.md CHANGED
@@ -6,7 +6,10 @@ small documentation layout. It is not a workflow engine.
6
6
  The guidance preserves task authorization, scales verification to risk, and
7
7
  defines completion by the user's requested outcome. It leaves model choice,
8
8
  reasoning effort, and execution strategy to the user and runtime; it ships no
9
- fixed agent profiles or mandatory task protocol.
9
+ fixed agent profiles or Gate runtime. Repository changes use task-owned
10
+ `codex/*` branches and independent worktrees, with verified integration into
11
+ `dev`; read-only questions do not need a branch. Development stays parallel,
12
+ while integration resolves conflicts against current `dev` without force pushes.
10
13
 
11
14
  ## Install
12
15
 
@@ -46,6 +49,7 @@ review, test, or commit.
46
49
 
47
50
  ```bash
48
51
  autocoding init
52
+ autocoding init --dry-run --json
49
53
  autocoding sync --projects /path/project-a,/path/project-b
50
54
  autocoding status --projects . --json
51
55
  ```
@@ -61,6 +65,26 @@ when both checks pass and no leftovers need review; otherwise status exits with
61
65
  code 1. This is a local comparison, not an npm registry update check or an
62
66
  engineering gate. Project-owned document contents are not inspected for drift.
63
67
 
68
+ `init`/`sync` preflight every requested project before refreshing any of them.
69
+ Modified or unowned files in the managed skill tree, `AGENTS.md`, or
70
+ `docs/ENVIRONMENT.md` block replacement; their contents are not printed.
71
+ `--dry-run --json` previews affected paths and conflicts without writing files.
72
+ Review the differences and migrate useful project facts into `PROJECT.md` or
73
+ topic documents first. If replacement is then intended, explicitly request it:
74
+
75
+ ```bash
76
+ autocoding init --replace-managed --backup-dir /private/external/skill-backups
77
+ ```
78
+
79
+ The backup directory must be outside all target projects, including through
80
+ symlinks. Each replacement creates a new private backup directory (0700), copies
81
+ the conflicting files with mode 0600, verifies their hashes, and records their
82
+ source paths. It does not overwrite an earlier backup. A dry-run does not create
83
+ backups. Review backups as potentially credential-bearing data; never commit them.
84
+ The override does not merge project instructions automatically or authorize
85
+ discarding them. Whole-batch preflight prevents known conflicts from producing a
86
+ partial upgrade; it is not a filesystem transaction for failures such as disk loss.
87
+
64
88
  During upgrades, unchanged manifest-owned legacy files can be retired; the old
65
89
  `docs/ENGINEERING.md` policy is archived first. Modified legacy files outside the
66
90
  managed skill tree are preserved and reported across subsequent upgrades.
@@ -78,6 +102,11 @@ overwrite its own development instructions. Here, `status` reports source
78
102
  discovery, packaged asset alignment, and legacy leftovers instead of expecting a
79
103
  project install manifest.
80
104
 
105
+ Keep project constraints and validation entry points near the top of
106
+ `PROJECT.md`; read them before writing files or operating environments, including
107
+ when another skill suggests a default output path. Link to relevant existing
108
+ topic docs for historical detail. Shared managed files are not project overrides.
109
+
81
110
  ```bash
82
111
  npm run sync-assets
83
112
  npm run release:check
@@ -88,3 +117,10 @@ intended models: a read-only diagnosis, a focused fix, an already-authorized
88
117
  delivery, and a blocked external job. Compare scope adherence, verification,
89
118
  completion evidence, and unnecessary questions or repeated work. These are
90
119
  evaluation scenarios, not required steps for every consuming project task.
120
+
121
+ Include regressions for artifact paths, managed-file ownership, preservation
122
+ during upgrades, concurrent worktrees with conflicting changes, and a completed
123
+ application delivery followed by an unrelated documentation build. The last case
124
+ must not add an unrequested CI wait or background monitor. For parallel work,
125
+ exercise a rejected stale push, conflict reconciliation, verification of both
126
+ changes, and non-force integration; do not merely test instruction wording.
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "schema_version": 2,
3
- "skill_version": "5.0.5",
3
+ "skill_version": "5.1.0",
4
4
  "asset_files": [
5
5
  {
6
6
  "path": "SKILL.md",
7
- "sha256": "54c28a7a3a147460b96e11d3da92e7722690e2836db3e5c35fa28dfc46c2860c"
7
+ "sha256": "5d4f094f3de1287a44e989af19195ced866c98af58d56db7c0a018a11acf7e42"
8
8
  },
9
9
  {
10
10
  "path": "data/templates/ENVIRONMENT.md",
@@ -12,7 +12,7 @@
12
12
  },
13
13
  {
14
14
  "path": "data/templates/PROJECT.md",
15
- "sha256": "f311a02d02bd6a924f94cbf341ff90dba839bf70a1f97d83500a7d2660dad6c1"
15
+ "sha256": "2a3de51f5bcb576a32d47d807ae17fd724e467da3edc03586dae332605ede2bd"
16
16
  },
17
17
  {
18
18
  "path": "data/templates/architecture/.gitkeep",
@@ -20,7 +20,7 @@
20
20
  },
21
21
  {
22
22
  "path": "data/templates/bridges/AGENTS.md",
23
- "sha256": "6f3c5a2881d0b0252c7b7512f5783e9c06346656e2415be9bcec3f2070025755"
23
+ "sha256": "15d264c0f89ae571534444f5333785913a11cf75f27b8fccbb717b0c483595f1"
24
24
  },
25
25
  {
26
26
  "path": "data/templates/deployment/.gitkeep",
@@ -37,6 +37,10 @@
37
37
  {
38
38
  "path": "data/templates/product/.gitkeep",
39
39
  "sha256": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
40
+ },
41
+ {
42
+ "path": "references/parallel-development.md",
43
+ "sha256": "907f70aee2d58df1018daa26c3926201aa26c74b37d498aa13f8e6ebf8cae828"
40
44
  }
41
45
  ]
42
46
  }
@@ -5,8 +5,10 @@ description: Use when a project opts into auto-coding-skill or the user asks to
5
5
 
6
6
  # Auto Coding Skill
7
7
 
8
- Read `AGENTS.md`, then use the project documentation only when it helps the
9
- current request:
8
+ Read `AGENTS.md`. Before repository edits, artifact-producing tools, or environment
9
+ operations, read the applicable constraints and entry points in `docs/PROJECT.md`.
10
+ Start with its short current-context section and follow only relevant links;
11
+ do not routinely load its history or credential records in full.
10
12
 
11
13
  - `docs/ENVIRONMENT.md` for shared access endpoints, ports, and local credential references.
12
14
  - `docs/PROJECT.md` for project-specific runtime facts and configuration.
@@ -18,11 +20,27 @@ Use the project's guidance to choose an approach and enough verification for the
18
20
  requested outcome. This Skill adds context, not a fixed task protocol or model
19
21
  profile; it does not narrow existing authorization or redefine completion.
20
22
 
23
+ For repository changes, use a task-owned `codex/*` branch in an independent
24
+ worktree, then integrate the verified result into `dev`. Read
25
+ [parallel development](references/parallel-development.md) before creating or
26
+ integrating a task worktree. Read-only questions do not require a branch.
27
+
28
+ Project constraints govern tool output paths, including defaults from other
29
+ skills. Put temporary output in the project's approved location, normally
30
+ `.local/<task>/`; do not create root-level output directories by default.
31
+
21
32
  Write documentation only when the user asks for it or when a durable fact,
22
33
  contract, decision, test strategy, or operating procedure would otherwise be
23
34
  lost. Choose the relevant existing folder; do not create routine task records,
24
35
  review records, or duplicate summaries.
25
36
 
26
- `autocoding init` refreshes `AGENTS.md` and `docs/ENVIRONMENT.md`. It creates
27
- `docs/PROJECT.md` and topic directories only when missing, and never overwrites
28
- project-owned documentation.
37
+ The installed skill, `AGENTS.md`, and `docs/ENVIRONMENT.md` are managed assets:
38
+ never append project-specific instructions or environment facts to them. Put
39
+ those in `docs/PROJECT.md` or its linked topic documents. Keep current constraints
40
+ and entry points prominent; maintain historical detail in the relevant existing
41
+ topic document rather than appending a diary to the project entry point.
42
+
43
+ `autocoding init` and `sync` preview changes with `--dry-run`. Modified or unowned
44
+ managed files block replacement until reviewed; migrate useful project content
45
+ first, then explicitly replace with a private external backup. Existing
46
+ `docs/PROJECT.md` and topic documents are never overwritten.
@@ -1,32 +1,35 @@
1
1
  # Project Configuration
2
2
 
3
- > This document belongs to the project. `autocoding init` and `autocoding sync`
4
- > create it only when missing and never overwrite it.
3
+ This file is project-owned. Skill installation creates it only when missing;
4
+ upgrades never overwrite it. Keep the current working context here and link to
5
+ maintained topic documents for detail, rather than accumulating task history.
5
6
 
6
- Record only durable, project-specific information that helps later development
7
- or diagnosis. This project-owned document may contain project-approved plaintext
8
- usernames and passwords for development and diagnosis. Keep each credential next
9
- to its system, address, and purpose; do not echo it in chat or logs.
7
+ ## Current working context
10
8
 
11
- ## Project services and ports
9
+ Record the facts needed before writing files or operating this project:
12
10
 
13
- - Application endpoints:
14
- - Internal services:
15
- - Runtime and dependency versions:
11
+ - Workspace constraints: approved directories, temporary output location, and
12
+ any concurrent work or external systems that must not be touched.
13
+ - Integration: `dev` is the integration target; each changing task uses its own
14
+ `codex/*` branch and independent worktree. Record any explicit project exception.
15
+ - Validation entry points: module working directories, focused checks, and the
16
+ acceptance boundaries relevant to delivery.
17
+ - Environment boundaries: deployment targets and actions requiring additional
18
+ authority. An endpoint or stored credential is not authorization to use it.
16
19
 
17
- ## Shared-access overrides
20
+ Replace this guidance with verified project facts; omit inapplicable fields and
21
+ identify genuinely unknown facts without inventing values.
18
22
 
19
- - Backend host or URL:
20
- - Credential records:
21
- - Access constraints:
23
+ ## Runtime and topic index
22
24
 
23
- ## Runtime and operations
25
+ Keep current service endpoints and operating entry points here. Link to the
26
+ existing product, architecture, interface, design, and deployment documents only
27
+ when they help locate durable knowledge. Historical release and acceptance
28
+ evidence belongs in the relevant topic document, not in the current-context block.
24
29
 
25
- - Local start and diagnostic entry points:
26
- - Relevant verification commands and acceptance criteria:
27
- - Deployment topology:
28
- - Logs and metrics:
30
+ ## Access records
29
31
 
30
- ## Constraints and durable decisions
31
-
32
- -
32
+ Project-approved credentials may be maintained here or at the project's approved
33
+ private location. Keep each record associated with its system and purpose.
34
+ Read only the required record; never print this whole file when it contains
35
+ credentials, and never echo secrets in chat, command arguments, or logs.
@@ -1,4 +1,4 @@
1
- <!-- auto-coding-skill:managed-agents:start version=5.0.5 -->
1
+ <!-- auto-coding-skill:managed-agents:start version=5.1.0 -->
2
2
  # General Engineering Guidance
3
3
 
4
4
  ## Authority and scope
@@ -20,10 +20,22 @@ An assessment or diagnosis alone does not authorize implementation or deployment
20
20
 
21
21
  ## Development approach
22
22
 
23
- Choose an approach suited to the request's complexity and risk. Work directly
24
- for ordinary changes; use isolation, design, review, or parallel work when useful
25
- and allowed by the task and runtime. Model choice and reasoning effort belong to
26
- the user and runtime, not to a fixed profile in this Skill.
23
+ Choose an approach suited to the request's complexity and risk. Model choice and
24
+ reasoning effort belong to the user and runtime, not to a fixed profile in this
25
+ Skill. Design, review, and delegation should serve the task, not a fixed ceremony.
26
+
27
+ For every repository-changing request, use a task-owned `codex/*` branch in an
28
+ independent worktree based on current `dev`; do not edit in the shared `dev`
29
+ checkout or switch its branch while other conversations may use it. Reuse your
30
+ own active task branch for follow-ups. Read-only questions need no new branch.
31
+ Read `.agents/skills/auto-coding-skill/references/parallel-development.md` for
32
+ worktree isolation, conflict resolution, integration, and cleanup boundaries.
33
+
34
+ Complete and verify work on that branch, integrate the latest `dev`, resolve
35
+ conflicts preserving both tasks' valid changes, and recheck the affected behavior
36
+ before merging into `dev`. If `dev` advances, reconcile again; never force-push
37
+ or overwrite others' work to finish. Ask only when conflicting product intent
38
+ cannot be determined. Keep development parallel and integration serialized.
27
39
 
28
40
  Verify the changed behavior and relevant failure paths with evidence proportionate
29
41
  to the risk. Start with focused checks and broaden when impact or findings justify
@@ -36,8 +48,19 @@ and report the evidence for each. A launched command or background job is not a
36
48
  successful result; follow required work to its terminal state. If that is not
37
49
  possible, report the specific blocker or pending state without claiming completion.
38
50
 
51
+ Do not expand completion to unrelated CI, documentation builds, or extra reports.
52
+ Wait for CI/deployment only when required by the requested outcome or a concrete
53
+ failure relevant to it. Respect existing push hooks; do not trigger duplicate
54
+ builds or invent background monitoring to finish an otherwise completed task.
55
+
39
56
  ## Documentation
40
57
 
58
+ Before repository edits, tools that produce files, or environment operations,
59
+ read the applicable constraints and entry points in `docs/PROJECT.md`, then only
60
+ the topic sections needed for the task. Follow those output-path rules even when
61
+ another tool or skill recommends a different default. Temporary output belongs
62
+ in the approved location, normally `.local/<task>/`, not new root directories.
63
+
41
64
  Read relevant project documentation before relying on project context:
42
65
 
43
66
  - `docs/ENVIRONMENT.md`: shared GitLab, Nexus, Jenkins, and backend endpoint/port references. Managed and refreshed by the Skill.
@@ -48,12 +71,22 @@ Read relevant project documentation before relying on project context:
48
71
  - `docs/interfaces/`: public API, event, protocol, or integration contracts.
49
72
  - `docs/deployment/`: runbooks and durable operating procedures.
50
73
 
74
+ The installed Skill, `AGENTS.md`, and `docs/ENVIRONMENT.md` are shared managed
75
+ files. Do not add project-specific guidance, deployment facts, or credentials to
76
+ them; put those in `docs/PROJECT.md` or its linked topic documents. Do not edit
77
+ the install manifest to hide drift. Skill upgrades must review changed managed
78
+ files and preserve useful project content before explicit replacement.
79
+
51
80
  Documentation is optional. Do not create a record for a routine edit, a transient
52
81
  investigation, an ordinary review, or every commit. Record something only when the
53
82
  user asks or when the information will remain useful after the immediate task.
54
83
  Put it in the narrowest applicable folder and update an existing document instead
55
84
  of creating parallel summaries.
56
85
 
86
+ Keep the project entry point focused on current constraints, runtime facts,
87
+ verification entry points, and links. Move useful historical evidence to existing
88
+ topic documents; do not turn `PROJECT.md` into a per-task or per-release diary.
89
+
57
90
  ## Environment and credentials
58
91
 
59
92
  `docs/ENVIRONMENT.md` is shared managed context: it names endpoint ports and
@@ -0,0 +1,61 @@
1
+ # Parallel repository development
2
+
3
+ Use this reference for repository-changing work, not read-only diagnosis. The
4
+ user may explicitly change the branch policy; do not infer an exception merely
5
+ because an edit is small. This is isolation for concurrent conversations, not a
6
+ task-ledger, fixed-review, or model-selection protocol.
7
+
8
+ ## Own a branch and a worktree
9
+
10
+ - Inspect the repository instructions, status, remotes, and existing worktrees.
11
+ Fetch the integration branch when available; start a unique `codex/<task>`
12
+ branch from current `dev`. Report an unavailable remote rather than pretending
13
+ an old base is current.
14
+ - Give the task an independent worktree. A different branch in the same directory
15
+ does not isolate files. Prefer the host's managed worktree tools when available;
16
+ otherwise use the project's approved worktree location. Keep temporary output
17
+ under that worktree's approved `.local/<task>/` location.
18
+ - Reuse the same task-owned branch/worktree for its follow-ups. Do not adopt,
19
+ reset, stash, switch, or remove another conversation's workspace. Existing
20
+ uncommitted work is not automatically part of the new request.
21
+ - Run edits, builds, formatters, and tests against the task worktree explicitly.
22
+ Do not apply a patch to the shared checkout accidentally. Shared output paths,
23
+ databases, devices, and deployments remain shared even with separate worktrees;
24
+ respect their own authorization and coordination boundaries.
25
+
26
+ ## Integrate into dev
27
+
28
+ - Commit only the task's verified changes. Fetch current `dev` again before
29
+ integration. Merge it into the task branch, or rebase only task-owned history
30
+ when doing so will not rewrite another participant's work.
31
+ - Resolve both textual and semantic conflicts in the task worktree. Read the
32
+ surrounding code, contracts, and tests; preserve both tasks' valid behavior.
33
+ Do not use blanket `ours`/`theirs`, reset, or force pushes as conflict resolution.
34
+ Re-run the checks affected by the combination, not merely the old task checks.
35
+ - Resolve implementation conflicts directly when evidence is sufficient. If
36
+ product requirements genuinely contradict and the intended result is unknown,
37
+ preserve both versions and ask for that decision.
38
+ - Serialize the final integration attempt. Where available, use the repository's
39
+ existing merge queue or integration lock. A non-force Git push is the final
40
+ concurrency guard, not proof that a stale candidate is safe to combine.
41
+ - If no PR/merge queue is required and pushing is authorized, a verified task
42
+ branch containing the latest remote `dev` may be fast-forwarded to remote
43
+ `dev` from its own worktree (`git push origin HEAD:refs/heads/dev`). This avoids
44
+ editing or switching the shared checkout. If rejected because `dev` moved,
45
+ fetch, reconcile, verify the changed combination, and retry without force.
46
+ - Update a local `dev` checkout only when it is clean and not in use by another
47
+ task; otherwise leave it untouched and report that remote integration succeeded
48
+ while the shared checkout still needs a safe fast-forward. Never discard local
49
+ changes to synchronize it.
50
+
51
+ ## Finish without losing work
52
+
53
+ Verify that the intended integration target contains the task commit. Distinguish
54
+ branch completion, dev integration, push, CI, deployment, and user/device
55
+ acceptance. Follow only the completion boundaries the user actually requested;
56
+ do not add unrelated CI waits or automatically start monitoring.
57
+
58
+ Remove/archive a task worktree or delete its branch only after its commits are
59
+ integrated, needed artifacts are preserved, it is clean, and no active task uses
60
+ it. Prefer recoverable worktree archival. Never bulk-delete `codex/*`: another
61
+ conversation may still be developing there.
package/cli/src/index.js CHANGED
@@ -46,12 +46,15 @@ function copyTree(source, target) {
46
46
 
47
47
  function parseArgs(argv) {
48
48
  const [,, rawCommand, ...rest] = argv;
49
- const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false };
49
+ const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false, dryRun: false, replaceManaged: false, backupDir: null };
50
50
  for (let index = 0; index < rest.length; index += 1) {
51
51
  const value = rest[index];
52
52
  if (value === "--dest") args.dest = rest[++index] || fail("--dest requires a path");
53
53
  else if (value === "--projects") args.projects.push(...(rest[++index] || fail("--projects requires paths")).split(",").filter(Boolean));
54
54
  else if (value === "--json") args.json = true;
55
+ else if (value === "--dry-run") args.dryRun = true;
56
+ else if (value === "--replace-managed") args.replaceManaged = true;
57
+ else if (value === "--backup-dir") args.backupDir = rest[++index] || fail("--backup-dir requires a private external directory");
55
58
  else if (value === "-h" || value === "--help") args.command = "help";
56
59
  else if (value.startsWith("--")) fail(`unknown argument: ${value}`);
57
60
  else args.projects.push(value);
@@ -59,6 +62,110 @@ function parseArgs(argv) {
59
62
  return args;
60
63
  }
61
64
 
65
+ function installSnapshot(root) {
66
+ const skill = managedTarget(root, ".agents/skills/auto-coding-skill");
67
+ const previous = readManifest(root);
68
+ const paths = new Set(["AGENTS.md", "docs/ENVIRONMENT.md", "docs/PROJECT.md", ".agents/managed-install.json"]);
69
+ if (skill && exists(skill)) {
70
+ if (!fs.statSync(skill).isDirectory()) fail("installed skill path is not a directory");
71
+ for (const file of listFiles(skill)) paths.add(`.agents/skills/auto-coding-skill/${file}`);
72
+ }
73
+ for (const entry of [...(Array.isArray(previous?.entries) ? previous.entries : []), ...(Array.isArray(previous?.legacy_entries) ? previous.legacy_entries : [])]) {
74
+ if (legacyManagedPath(entry?.path)) paths.add(entry.path);
75
+ }
76
+ return [...paths].sort().map(relative => {
77
+ const file = managedTarget(root, relative);
78
+ if (!file) fail(`unsafe install path: ${relative}`);
79
+ if (!exists(file)) return { path: relative, sha256: null };
80
+ if (!fs.statSync(file).isFile()) fail(`expected a regular file: ${relative}`);
81
+ return { path: relative, sha256: sha256(file) };
82
+ });
83
+ }
84
+
85
+ function installationPlan(project) {
86
+ const root = fs.realpathSync(path.resolve(project));
87
+ if (sourceRepository(root)) fail("this is the skill source repository; use npm run sync-assets and npm run release:check, not init/sync");
88
+ for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
89
+ if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
90
+ }
91
+ const snapshot = installSnapshot(root);
92
+ const expected = new Map(expectedEntries().map(entry => [entry.path, entry.sha256]));
93
+ const previous = readManifest(root);
94
+ const recorded = new Map();
95
+ for (const entry of Array.isArray(previous?.entries) ? previous.entries : []) {
96
+ if (!safeRelativePath(entry?.path) || !/^[a-f0-9]{64}$/.test(entry?.sha256)) continue;
97
+ recorded.set(entry.path, recorded.has(entry.path) ? null : entry.sha256);
98
+ }
99
+ const conflicts = [];
100
+ for (const entry of snapshot) {
101
+ if (!entry.sha256 || !(entry.path.startsWith(".agents/skills/auto-coding-skill/") || ["AGENTS.md", "docs/ENVIRONMENT.md"].includes(entry.path))) continue;
102
+ if (entry.sha256 === expected.get(entry.path) || entry.sha256 === recorded.get(entry.path)) continue;
103
+ // The existing legacy migration copies this complete document into a new PROJECT.md.
104
+ if (entry.path === "docs/ENVIRONMENT.md" && !isManaged(previous, entry.path) && !exists(path.join(root, "docs/PROJECT.md"))) continue;
105
+ conflicts.push({ path: entry.path, sha256: entry.sha256, reason: recorded.has(entry.path) ? "modified managed file" : "unowned file would be replaced" });
106
+ }
107
+ const current = new Map(snapshot.map(entry => [entry.path, entry.sha256]));
108
+ const changes = [...expected].filter(([relative, digest]) => current.get(relative) !== digest)
109
+ .map(([relative]) => ({ path: relative, action: current.get(relative) ? "refresh" : "install" }));
110
+ for (const entry of snapshot) if (entry.sha256 && entry.path.startsWith(".agents/skills/auto-coding-skill/") && !expected.has(entry.path)) changes.push({ path: entry.path, action: "retire" });
111
+ return { project: root, conflicts, changes, snapshot };
112
+ }
113
+
114
+ function assertUnchanged(plan) {
115
+ if (JSON.stringify(installSnapshot(plan.project)) !== JSON.stringify(plan.snapshot)) fail(`project changed during upgrade preparation; nothing further was refreshed: ${plan.project}`);
116
+ }
117
+
118
+ function backupConflicts(plans, directory) {
119
+ const requested = path.resolve(directory);
120
+ // Resolve even a not-yet-created suffix, so a symlinked parent cannot point into a project.
121
+ let ancestor = requested;
122
+ const suffix = [];
123
+ while (!exists(ancestor)) { suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
124
+ const resolved = path.join(fs.realpathSync(ancestor), ...suffix);
125
+ for (const plan of plans) {
126
+ const relative = path.relative(plan.project, resolved);
127
+ if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) fail("backup directory must be outside every target project");
128
+ }
129
+ fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
130
+ const backup = fs.mkdtempSync(path.join(resolved, "autocoding-managed-"));
131
+ fs.chmodSync(backup, 0o700);
132
+ const records = [];
133
+ for (const plan of plans) {
134
+ assertUnchanged(plan);
135
+ const key = `${path.basename(plan.project)}-${crypto.createHash("sha256").update(plan.project).digest("hex").slice(0, 12)}`;
136
+ for (const conflict of plan.conflicts) {
137
+ const target = path.join(backup, key, conflict.path);
138
+ fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
139
+ fs.writeFileSync(target, fs.readFileSync(path.join(plan.project, conflict.path)), { flag: "wx", mode: 0o600 });
140
+ if (sha256(target) !== conflict.sha256) fail("managed file changed while backing up; no replacement was started");
141
+ records.push({ project: plan.project, ...conflict, backup_path: path.relative(backup, target) });
142
+ }
143
+ }
144
+ fs.writeFileSync(path.join(backup, "backup.json"), `${JSON.stringify({ version: pkg.version, files: records }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
145
+ return backup;
146
+ }
147
+
148
+ function installProjects(projects, args) {
149
+ if (args.replaceManaged && !args.backupDir) fail("--replace-managed requires --backup-dir outside the target projects; review and migrate project facts first");
150
+ if (args.backupDir && !args.replaceManaged) fail("--backup-dir requires --replace-managed");
151
+ const plans = [...new Set(projects.map(project => fs.realpathSync(path.resolve(project))))].map(installationPlan);
152
+ const conflicts = plans.some(plan => plan.conflicts.length > 0);
153
+ const preview = { version: pkg.version, dry_run: args.dryRun, can_apply: !conflicts || args.replaceManaged, results: plans.map(({ snapshot, ...plan }) => plan) };
154
+ if (args.dryRun || (conflicts && !args.replaceManaged)) {
155
+ toJson(preview, args.json);
156
+ if (conflicts && !args.replaceManaged) {
157
+ console.error("[autocoding] No files changed. Review the listed files, migrate useful facts to PROJECT.md/topic docs, then use --replace-managed --backup-dir <private-external-directory> if replacement is intended. No file contents or credentials are printed.");
158
+ process.exitCode = 1;
159
+ }
160
+ return;
161
+ }
162
+ const backup = conflicts ? backupConflicts(plans, args.backupDir) : null;
163
+ // Preflight the whole batch before the first installation, not one project at a time.
164
+ for (const plan of plans) assertUnchanged(plan);
165
+ const results = plans.map(plan => { assertUnchanged(plan); return { ...init(plan.project), backup }; });
166
+ toJson(args.command === "init" ? results[0] : { version: pkg.version, results }, args.json);
167
+ }
168
+
62
169
  function readManifest(project) {
63
170
  const file = managedTarget(project, ".agents/managed-install.json");
64
171
  if (!file || !exists(file)) return null;
@@ -301,15 +408,15 @@ function status(project) {
301
408
  }
302
409
 
303
410
  function help() {
304
- console.log(`auto-coding-skill ${pkg.version}\n\nCommands:\n autocoding init [--dest PATH]\n autocoding sync [--projects PATH[,PATH...]]\n autocoding status [--projects PATH[,PATH...]] [--json]\n\nThese commands only install, preserve, and report documentation. They do not run or require Gates, reviews, tests, tasks, worktrees, or deployment checks.`);
411
+ console.log(`auto-coding-skill ${pkg.version}\n\nCommands:\n autocoding init [--dest PATH] [--dry-run] [--json]\n autocoding sync [--projects PATH[,PATH...]] [--dry-run] [--json]\n autocoding status [--projects PATH[,PATH...]] [--json]\n\nChanged or unowned managed files block replacement. After reviewing and migrating project facts, use --replace-managed --backup-dir <private-external-directory> for a verified backup before explicit replacement. Dry-run never writes files.\n\nThese commands only install, preserve, and report documentation. They do not run project tests, Gates, worktrees, builds, or deployments. The installed guidance describes task-owned codex branches and worktrees; the installer does not create them.`);
305
412
  }
306
413
 
307
414
  const args = parseArgs(process.argv);
308
415
  if (args.command === "help") help();
309
- else if (args.command === "init") toJson(init(args.dest || process.cwd(), args), args.json);
416
+ else if (args.command === "init") installProjects([args.dest || process.cwd()], args);
310
417
  else if (args.command === "sync") {
311
418
  const projects = args.projects.length ? args.projects : [process.cwd()];
312
- toJson({ version: pkg.version, results: projects.map(project => init(project, args)) }, args.json);
419
+ installProjects(projects, args);
313
420
  } else if (args.command === "status") {
314
421
  const projects = args.projects.length ? args.projects : [process.cwd()];
315
422
  const results = projects.map(status);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "5.0.5",
3
+ "version": "5.1.0",
4
4
  "description": "Lightweight engineering guidance and a managed installer that preserves project-owned documentation.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -17,7 +17,7 @@
17
17
  "clean:cache": "find cli src -type d -name '__pycache__' -prune -exec rm -rf {} +",
18
18
  "prepack": "npm run clean:cache",
19
19
  "check:package": "npm run clean:cache && node cli/src/check-package.js",
20
- "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js",
20
+ "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js && node cli/tests/parallel.test.js",
21
21
  "test:src": "node -e \"const fs=require('fs'); for (const file of ['src/auto-coding-skill/SKILL.md','src/auto-coding-skill/data/templates/ENVIRONMENT.md','src/auto-coding-skill/data/templates/PROJECT.md','src/auto-coding-skill/data/templates/architecture/.gitkeep','src/auto-coding-skill/data/templates/product/.gitkeep','src/auto-coding-skill/data/templates/bridges/AGENTS.md']) if (!fs.existsSync(file)) throw new Error('missing '+file); console.log('source-doc-assets-ok')\"",
22
22
  "check:assets": "node cli/src/sync-assets.js --check",
23
23
  "sync-assets": "node cli/src/sync-assets.js",