@elvis1513/auto-coding-skill 5.1.0 → 5.2.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
@@ -52,6 +52,7 @@ autocoding init
52
52
  autocoding init --dry-run --json
53
53
  autocoding sync --projects /path/project-a,/path/project-b
54
54
  autocoding status --projects . --json
55
+ autocoding doctor --projects . --json
55
56
  ```
56
57
 
57
58
  These commands only install, preserve, and report documentation. They never run
@@ -65,6 +66,21 @@ when both checks pass and no leftovers need review; otherwise status exits with
65
66
  code 1. This is a local comparison, not an npm registry update check or an
66
67
  engineering gate. Project-owned document contents are not inspected for drift.
67
68
 
69
+ `doctor` separates managed integrity, project-owned context/legacy profiles,
70
+ the selected worktree, and clone-local Git guard health. A primary checkout is
71
+ normal for inspection, not a failed check. Profiles are reported by path and pin
72
+ presence, not loaded, removed or printed. No project script is executed.
73
+
74
+ For clones **already opted into** the optional Git guard, its single source and
75
+ hermetic tests are in `src/git-workflow/` in this package. In a task-owned
76
+ linked worktree use `autocoding guard-sync --dry-run` and then
77
+ `autocoding guard-sync` to refresh a recognized source/test pair under
78
+ `config/git-workflow/`. Unknown downstream changes are never overwritten.
79
+ After verification, `python3 config/git-workflow/guard.py install` explicitly
80
+ updates that clone's hooks and preserves its baseline, receipts and prior hook
81
+ chain. New clones do not inherit local activation. Neither init/sync nor doctor
82
+ installs a hook; no Jenkins, repository protection or publishing settings change.
83
+
68
84
  `init`/`sync` preflight every requested project before refreshing any of them.
69
85
  Modified or unowned files in the managed skill tree, `AGENTS.md`, or
70
86
  `docs/ENVIRONMENT.md` block replacement; their contents are not printed.
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "schema_version": 2,
3
- "skill_version": "5.1.0",
3
+ "skill_version": "5.2.0",
4
4
  "asset_files": [
5
5
  {
6
6
  "path": "SKILL.md",
7
- "sha256": "5d4f094f3de1287a44e989af19195ced866c98af58d56db7c0a018a11acf7e42"
7
+ "sha256": "64888606212f2d3f833d857197d617ab9cac7ea7fe86352842e49bbb9bf4291f"
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": "2a3de51f5bcb576a32d47d807ae17fd724e467da3edc03586dae332605ede2bd"
15
+ "sha256": "221ca1288d8e753900719182a37769f68a1e1ab2e42f6e3180373434aa7fd08b"
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": "15d264c0f89ae571534444f5333785913a11cf75f27b8fccbb717b0c483595f1"
23
+ "sha256": "0c3aa3de1b09b19c5797aaa20b77b3f5fc1f8242223a724d878ab4c17f9e3c9b"
24
24
  },
25
25
  {
26
26
  "path": "data/templates/deployment/.gitkeep",
@@ -40,7 +40,7 @@
40
40
  },
41
41
  {
42
42
  "path": "references/parallel-development.md",
43
- "sha256": "907f70aee2d58df1018daa26c3926201aa26c74b37d498aa13f8e6ebf8cae828"
43
+ "sha256": "e73e646aa0b300c9d5ef26c8044e26f11c1d4c3f97a07ef26a5a263a42fa540f"
44
44
  }
45
45
  ]
46
46
  }
@@ -1,46 +1,21 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Use when a project opts into auto-coding-skill or the user asks to initialize, refresh, or inspect its project guidance and documentation. Provides context without imposing a fixed engineering workflow.
3
+ description: Use in opted-in projects to locate project-owned context, or to inspect and safely refresh their managed guidance.
4
4
  ---
5
5
 
6
6
  # Auto Coding Skill
7
7
 
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.
8
+ The repository's `AGENTS.md` is the shared entry point. If its instructions and
9
+ the applicable project context are already in this chat, use them; revisit when
10
+ the checkout, constraints, or task scope changes.
12
11
 
13
- - `docs/ENVIRONMENT.md` for shared access endpoints, ports, and local credential references.
14
- - `docs/PROJECT.md` for project-specific runtime facts and configuration.
15
- - `docs/product/` for durable product context and decisions.
16
- - `docs/architecture/`, `docs/design/`, `docs/interfaces/`, and
17
- `docs/deployment/` for existing topic-specific knowledge.
12
+ For a project fact, start at the relevant section of `docs/PROJECT.md` and
13
+ follow its links. Shared endpoint and credential **lookup** guidance lives in
14
+ `docs/ENVIRONMENT.md`; do not dump access records into tool or chat output.
18
15
 
19
- Use the project's guidance to choose an approach and enough verification for the
20
- requested outcome. This Skill adds context, not a fixed task protocol or model
21
- profile; it does not narrow existing authorization or redefine completion.
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
-
32
- Write documentation only when the user asks for it or when a durable fact,
33
- contract, decision, test strategy, or operating procedure would otherwise be
34
- lost. Choose the relevant existing folder; do not create routine task records,
35
- review records, or duplicate summaries.
36
-
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.
16
+ For worktree setup, conflicts or integration, see
17
+ [parallel development](references/parallel-development.md). For a Skill upgrade,
18
+ preview with `autocoding init --dry-run`. If managed content has diverged,
19
+ review and migrate project facts before explicitly replacing it with a private
20
+ external backup. Existing project documents are never overwritten by init/sync.
21
+ `autocoding doctor` is an optional read-only diagnostic, not a development step.
@@ -1,35 +1,16 @@
1
- # Project Configuration
1
+ # Project configuration
2
2
 
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.
3
+ This entry is project-owned. Init/sync create it only when missing.
6
4
 
7
5
  ## Current working context
8
6
 
9
- Record the facts needed before writing files or operating this project:
7
+ Put the project's actual workspace/output boundaries, focused validation commands,
8
+ delivery restrictions and active environment roles here. Include only facts that
9
+ change how work is done; omit inapplicable fields and unknown values.
10
10
 
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.
11
+ ## Topic and access index
19
12
 
20
- Replace this guidance with verified project facts; omit inapplicable fields and
21
- identify genuinely unknown facts without inventing values.
22
-
23
- ## Runtime and topic index
24
-
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.
29
-
30
- ## Access records
31
-
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.
13
+ Link to maintained module, interface or deployment documents by topic. Keep
14
+ history in its existing home, outside the default reading path. Record only the
15
+ project-approved location for sensitive access information or its restricted
16
+ section; never echo credentials in chat or logs.
@@ -1,98 +1,27 @@
1
- <!-- auto-coding-skill:managed-agents:start version=5.1.0 -->
2
- # General Engineering Guidance
3
-
4
- ## Authority and scope
5
-
6
- Follow the user's current goal and applicable instructions. Treat the current source,
7
- tests, schemas, runtime configuration, and deployment configuration as the truth
8
- for existing behavior. Documentation describes durable intent and operating
9
- context; it must not override working code without an explicit decision.
10
-
11
- Work only within the requested scope. Do not silently change deployment systems,
12
- Jenkins, production data, credentials, infrastructure, or another developer's
13
- work. When a shared checkout contains unrelated changes, preserve them and avoid
14
- reset, clean, overwrite, or bulk formatting operations.
15
-
16
- Carry forward earlier authorization that still applies to this task, unless the
17
- user changes or revokes it. Act on clear, reversible steps within that scope;
18
- ask when missing information or new authority would materially change the result.
19
- An assessment or diagnosis alone does not authorize implementation or deployment.
20
-
21
- ## Development approach
22
-
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.
39
-
40
- Verify the changed behavior and relevant failure paths with evidence proportionate
41
- to the risk. Start with focused checks and broaden when impact or findings justify
42
- it. Honor required project checks; avoid repeating an unchanged check without a
43
- reason. State what was verified and any remaining uncertainty.
44
-
45
- Completion follows the requested outcome. Editing, committing, pushing, CI, and
46
- deployment are distinct results: complete the authorized parts the goal requires
47
- and report the evidence for each. A launched command or background job is not a
48
- successful result; follow required work to its terminal state. If that is not
49
- possible, report the specific blocker or pending state without claiming completion.
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
-
56
- ## Documentation
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
-
64
- Read relevant project documentation before relying on project context:
65
-
66
- - `docs/ENVIRONMENT.md`: shared GitLab, Nexus, Jenkins, and backend endpoint/port references. Managed and refreshed by the Skill.
67
- - `docs/PROJECT.md`: project-specific runtime facts, access overrides, and constraints. Project-owned and never overwritten by the Skill.
68
- - `docs/product/`: durable product context, boundaries, and decisions.
69
- - `docs/architecture/`: architecture and ADRs.
70
- - `docs/design/`: durable design notes that help future implementation.
71
- - `docs/interfaces/`: public API, event, protocol, or integration contracts.
72
- - `docs/deployment/`: runbooks and durable operating procedures.
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
-
80
- Documentation is optional. Do not create a record for a routine edit, a transient
81
- investigation, an ordinary review, or every commit. Record something only when the
82
- user asks or when the information will remain useful after the immediate task.
83
- Put it in the narrowest applicable folder and update an existing document instead
84
- of creating parallel summaries.
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
-
90
- ## Environment and credentials
91
-
92
- `docs/ENVIRONMENT.md` is shared managed context: it names endpoint ports and
93
- credential lookup guidance, but never contains plaintext credentials. Project
94
- specific configuration belongs in `docs/PROJECT.md`; it is preserved across
95
- Skill upgrades and may hold project-approved plaintext credential records. Never
96
- invent credentials, copy them into chat output, or expose them in logs.
97
-
1
+ <!-- auto-coding-skill:managed-agents:start version=5.2.0 -->
2
+ # Working in this project
3
+
4
+ Before writing files or operating an environment, use the applicable constraints
5
+ and entry points in `docs/PROJECT.md`. Read the relevant section, not the whole
6
+ file; reuse current context. Put temporary output in the project-approved
7
+ location (normally `.local/<task>/`), including output from other tools.
8
+
9
+ Develop changes on a task-owned `codex/*` branch in an independent linked
10
+ worktree based on current `dev`. Reuse the same worktree for follow-ups; do not
11
+ edit on shared `dev` or switch, stash, or clean another chat's workspace.
12
+ Resolve conflicts in the task worktree, verify the combined change and integrate
13
+ without force. For setup, integration and cleanup details see
14
+ [parallel development](.agents/skills/auto-coding-skill/references/parallel-development.md).
15
+ Read-only work needs no branch.
16
+
17
+ Choose tools, reasoning and delegation to fit the task. Verify changed behavior
18
+ in proportion to risk and honor project-required checks. Diagnosis does not
19
+ authorize changes. Report what actually finished: local integration, push, CI,
20
+ deployment and user acceptance are distinct. Do not trigger duplicate pipelines
21
+ or wait for unrelated jobs.
22
+
23
+ This file, the installed Skill and `docs/ENVIRONMENT.md` are managed. Keep
24
+ project-specific facts in `docs/PROJECT.md` or a linked topic, never in these
25
+ managed files. Write documentation when requested or when durable knowledge
26
+ would otherwise be lost; do not create routine task records. Never print secrets.
98
27
  <!-- auto-coding-skill:managed-agents:end -->
@@ -1,61 +1,39 @@
1
1
  # Parallel repository development
2
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.
3
+ ## Choose the task workspace
4
+
5
+ Check the current branch and `git worktree list`. Reuse the worktree that
6
+ belongs to this task if it is linked and on its own `codex/<task>` branch. If
7
+ the host supplied a new **task-owned, clean, detached** linked worktree, confirm
8
+ its base and attach a unique task branch there; no second worktree is needed.
9
+ If starting in the primary checkout, create a separate linked worktree from
10
+ current `dev` (normally fetched `origin/dev`). If the base cannot be refreshed,
11
+ say which revision was used. Never repurpose a dirty or unowned workspace.
12
+ Run edits and tests in the selected worktree. Devices, databases, ports and
13
+ deployments are still shared; worktree isolation does not grant access to them.
14
+
15
+ ## Integrate and finish
16
+
17
+ Reconcile current `dev` in the task branch. Resolve textual and behavioral
18
+ conflicts there, preserve both changes and recheck the affected behavior.
19
+ Ask only if product intent cannot be reconciled from the evidence. Serialize
20
+ final integration using the project's existing queue or a non-forced fast-forward.
21
+ If `dev` moves, reconcile and verify again; do not overwrite it.
22
+
23
+ For **local-only** delivery, fast-forward the local `dev` checkout only if
24
+ clean and unused. For authorized remote delivery without a required MR/queue,
25
+ `git push origin HEAD:refs/heads/dev` from the task worktree avoids switching
26
+ the shared checkout. Respect existing hooks and pipeline triggers. If a shared
27
+ checkout is busy, leave it intact and report which ref contains the result.
28
+
29
+ Retire only this task's clean worktree/branch, after its commits are integrated,
30
+ needed artifacts preserved, and no chat still needs it. Never bulk-delete task branches.
31
+
32
+ ## Clones with the optional Git guard
33
+
34
+ `python3 config/git-workflow/guard.py status` checks the local hook chain.
35
+ Explicit `install` on an opted-in clone preserves existing hooks and task
36
+ receipts across linked worktrees; it does not install on CI or prevent editor
37
+ writes. Authorized `uninstall` restores the previous hook setting and retains
38
+ recovery data. To test the guard itself, run `python3 -B config/git-workflow/test_guard.py`
39
+ in an isolated development workspace, not as an application delivery check.
@@ -30,8 +30,9 @@ const files = payload?.[0]?.files?.map(item => String(item.path || "")) || [];
30
30
  const forbidden = files.filter(file =>
31
31
  /(^|\/)__pycache__(\/|$)/.test(file) || /\.py[cod]$/i.test(file),
32
32
  );
33
- if (!files.includes("cli/assets/managed-install.json")) {
34
- process.stderr.write("Managed install manifest is missing from the package\n");
33
+ if (["cli/assets/managed-install.json", "cli/src/diagnostics.js", "src/git-workflow/guard.py",
34
+ "src/git-workflow/test_guard.py"].some(file => !files.includes(file))) {
35
+ process.stderr.write("A required manifest, diagnostic or optional Git guard asset is missing\n");
35
36
  process.exit(1);
36
37
  }
37
38
  if (forbidden.length > 0) {
@@ -0,0 +1,121 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { spawnSync } from "node:child_process";
4
+
5
+ // Previously shipped source/test pairs. Unknown or mixed pairs are project-owned
6
+ // until reviewed. Do not silently replace a downstream fix on the next release.
7
+ const originalGuard = "7e47fce43263ae1cfa440565b1d56af0a865db36da3566e6cbac7a2de9cb4804";
8
+ const knownPairs = new Set([
9
+ originalGuard + ":d593fa6aae02a31b0d148b90325b514565ed1661fc647f46f529a3bf980d8c3b",
10
+ originalGuard + ":absent", // original single-file adoption, before fixtures were distributed
11
+ "f654b2875e33670212bfdd365779ef9a87c6636daec57c4035eb7c1587798a2e:231b711228791209d9a1655f368f50d5032c8cfc0964c9c5013d765ddd91f4a3",
12
+ "fb9b841b0edfaa778e4a58436d8b4f55b09bef08def333bf741276d33cd2019e:54064d4752da3a9a244dee8b1258286a01d56322ceadffda3dd0c7db44f37e67",
13
+ ]);
14
+ const names = ["guard.py", "test_guard.py"];
15
+ const regular = file => file && fs.statSync(file, { throwIfNoEntry: false })?.isFile();
16
+ function cmd(cwd, binary, args) {
17
+ const env = { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
18
+ // Diagnose the requested checkout, even when invoked from another Git hook.
19
+ for (const key of ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE"]) delete env[key];
20
+ return spawnSync(binary, args, { cwd, env, encoding: "utf8", timeout: 10000 });
21
+ }
22
+ function git(cwd, ...args) {
23
+ const r = cmd(cwd, "git", args);
24
+ return r.status === 0 ? r.stdout.trim() : "";
25
+ }
26
+ function workspace(root) {
27
+ const top = git(root, "rev-parse", "--show-toplevel");
28
+ if (!top || fs.realpathSync(top) !== fs.realpathSync(root)) return { kind: "not-checkout-root" };
29
+ const common = git(root, "rev-parse", "--path-format=absolute", "--git-common-dir");
30
+ const dir = git(root, "rev-parse", "--absolute-git-dir");
31
+ if (!common || !dir) return { kind: "unknown" };
32
+ const linked = fs.realpathSync(common) !== fs.realpathSync(dir);
33
+ const branch = git(root, "symbolic-ref", "-q", "--short", "HEAD") || null;
34
+ return { kind: linked ? "linked" : "primary", branch, common,
35
+ task_branch: linked && Boolean(branch?.startsWith("codex/")) };
36
+ }
37
+
38
+ export function diagnostics({ packageRoot, managedTarget, sha256 }) {
39
+ const canonical = names.map(n => path.join(packageRoot, "src/git-workflow", n));
40
+ function sources(root) {
41
+ const targets = names.map(n => managedTarget(root, "config/git-workflow/" + n));
42
+ if (targets.some(p => !p)) return { state: "unknown", targets };
43
+ if (targets.every(p => !fs.existsSync(p))) return { state: "absent", targets };
44
+ const pair = targets.map(p => regular(p) ? sha256(p) : fs.existsSync(p) ? "unknown" : "absent").join(":");
45
+ const state = pair === canonical.map(sha256).join(":") ? "current" : knownPairs.has(pair) ? "known-older" : "unknown";
46
+ return { state, targets };
47
+ }
48
+
49
+ function guardSync(root, dryRun) {
50
+ const { state, targets } = sources(root);
51
+ const result = { project: root, source: state, dry_run: dryRun, changed: false };
52
+ if (state === "current") return { ...result, ok: true };
53
+ if (state !== "known-older") return { ...result, ok: false,
54
+ next: "No files changed. No recognized guard pair; review project ownership or downstream changes." };
55
+ if (dryRun) return { ...result, ok: true, would_refresh: names };
56
+ if (!workspace(root).task_branch) return { ...result, ok: false, next: "Use this task's linked codex/* worktree." };
57
+ for (const [i, target] of targets.entries()) fs.copyFileSync(canonical[i], target);
58
+ return { ...result, source: "current", changed: true, ok: true,
59
+ next: "After verification, explicitly refresh the opted-in clone with python3 config/git-workflow/guard.py install." };
60
+ }
61
+
62
+ function guard(root, w) {
63
+ const { state } = sources(root);
64
+ const opted = Boolean(w.common && fs.existsSync(path.join(w.common, "codex-workflow-guard/state.json")));
65
+ if (!opted && state === "absent") return { status: "not-configured", source: state, ok: true };
66
+ if (!opted) return { status: "not-installed", source: state, ok: false,
67
+ next: "Confirm clone opt-in before installing; no hook was changed." };
68
+ // Execute the trusted, packaged checker, never a script from the project.
69
+ const r = cmd(root, "python3", ["-I", "-B", canonical[0], "status"]);
70
+ let detail;
71
+ try { detail = JSON.parse(r.stdout); } catch { /* missing interpreter, invalid state, etc. */ }
72
+ const ok = state === "current" && r.status === 0 && detail?.ok === true;
73
+ const next = state === "unknown" || state === "absent" ? "Review the project's guard files; do not replace unknown changes."
74
+ : state === "known-older" ? "Preview autocoding guard-sync --dry-run in this project."
75
+ : !detail ? "Check Python 3.9+ and the clone's guard metadata; do not disable hooks."
76
+ : "Inspect core.hooksPath and the chained hooks; refresh the verified guard with its install command.";
77
+ return { status: ok ? "active" : "needs-review", source: state, ok, version: detail?.version ?? null,
78
+ expected_version: detail?.expected_version ?? null, interpreter: detail?.interpreter ?? null,
79
+ runtime_matches: detail?.runtime_matches ?? null, hooks_match: detail?.hooks_match ?? null,
80
+ ...(!ok ? { next } : {}) };
81
+ }
82
+
83
+ function doctor(status) {
84
+ if (status.mode === "source") return status;
85
+ const root = status.project;
86
+ const project = managedTarget(root, "docs/PROJECT.md");
87
+ const bridge = managedTarget(root, "AGENTS.md");
88
+ const bridgeText = regular(bridge) ? fs.readFileSync(bridge, "utf8") : "";
89
+ const marker = /<!-- auto-coding-skill:managed-agents:start[^>]*-->[\s\S]*?<!-- auto-coding-skill:managed-agents:end -->/;
90
+ const outside = marker.test(bridgeText) ? Boolean(bridgeText.replace(marker, "").trim()) : null;
91
+ const agentDir = managedTarget(root, ".agents/agents");
92
+ const overlays = [];
93
+ if (agentDir && fs.statSync(agentDir, { throwIfNoEntry: false })?.isDirectory()) {
94
+ for (const name of fs.readdirSync(agentDir).filter(n => n.endsWith(".toml")).sort()) {
95
+ const relative = ".agents/agents/" + name;
96
+ const file = managedTarget(root, relative);
97
+ if (!regular(file)) continue;
98
+ const content = fs.readFileSync(file, "utf8");
99
+ overlays.push({ path: relative, pins_model: /^\s*model\s*=/m.test(content),
100
+ pins_effort: /^\s*model_reasoning_effort\s*=/m.test(content) });
101
+ }
102
+ }
103
+ const w = workspace(root);
104
+ const g = guard(root, w);
105
+ const contextPresent = Boolean(regular(project));
106
+ const next = [];
107
+ if (!status.integrity) next.push("Review modified managed files; migrate project facts before replacement.");
108
+ if (!status.assets_current) next.push("Preview autocoding init --dry-run; project documents are preserved.");
109
+ if (!contextPresent) next.push("Restore the project-owned docs/PROJECT.md; do not invent project facts.");
110
+ if (outside) next.push("Review text outside the managed AGENTS.md block and move project-only constraints to docs/PROJECT.md.");
111
+ if (overlays.length || status.legacy_files.length) next.push("Check consumers of local overlays before archiving; no profile was loaded or removed.");
112
+ if (!g.ok) next.push(g.next);
113
+ return { project: root, ok: status.ok && contextPresent && g.ok,
114
+ managed: { integrity: status.integrity, current: status.assets_current, installed: status.version, cli: status.expected_version },
115
+ context: { project_entry: contextPresent ? "present" : "missing-or-unsafe", ownership: "project",
116
+ entry_bytes: contextPresent ? fs.statSync(project).size : null, outside_managed_bridge: outside, legacy_profiles: overlays,
117
+ legacy_workflow: status.legacy_files }, worktree: { kind: w.kind, branch: w.branch ?? null, task_branch: w.task_branch ?? false },
118
+ guard: g, next };
119
+ }
120
+ return { doctor, guardSync };
121
+ }
package/cli/src/index.js CHANGED
@@ -3,6 +3,7 @@ import crypto from "node:crypto";
3
3
  import fs from "node:fs";
4
4
  import path from "node:path";
5
5
  import { fileURLToPath } from "node:url";
6
+ import { diagnostics } from "./diagnostics.js";
6
7
 
7
8
  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
8
9
  const assetsRoot = path.join(packageRoot, "cli", "assets");
@@ -276,6 +277,10 @@ function init(project) {
276
277
  for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
277
278
  if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
278
279
  }
280
+ // Topic scaffolding is bootstrap-only. A project may deliberately remove a
281
+ // placeholder or an entire empty topic; upgrades must honor that choice.
282
+ const established = Array.isArray(readManifest(root)?.project_documents)
283
+ && exists(path.join(root, "docs/PROJECT.md"));
279
284
  const { retired, retained } = retireExactLegacyFiles(root);
280
285
  const installedSkill = path.join(root, ".agents", "skills", "auto-coding-skill");
281
286
  fs.rmSync(installedSkill, { recursive: true, force: true });
@@ -288,6 +293,7 @@ function init(project) {
288
293
  copyFile(source, path.join(root, targetRelative));
289
294
  }
290
295
  for (const [assetRelative, targetRelative] of projectDocs) {
296
+ if (established && targetRelative.endsWith("/.gitkeep")) continue;
291
297
  const source = path.join(assetSkill, "data", "templates", assetRelative);
292
298
  const target = path.join(root, targetRelative);
293
299
  if (!exists(target)) {
@@ -399,27 +405,45 @@ function status(project) {
399
405
  ? listFiles(skill).map(file => `.agents/skills/auto-coding-skill/${file}`).filter(file => !expectedPaths.has(file)) : [];
400
406
  currentErrors.push(...extra.map(file => `unexpected installed skill file: ${file}`));
401
407
  const legacy = legacyFiles(root, manifest);
408
+ const assetsCurrent = currentErrors.length === 0;
402
409
  currentErrors.push(...legacy.map(file => `legacy workflow file requires review: ${file}`));
403
410
  const errors = [...integrityErrors, ...currentErrors];
404
411
  const documents = Object.fromEntries(bootstrapDocs.map(([, target]) => [target, exists(path.join(root, target))]));
405
412
  return { project: root, version: manifest?.skill_version || "", expected_version: pkg.version,
406
- integrity: integrityErrors.length === 0, current: currentErrors.length === 0, ok: errors.length === 0,
413
+ integrity: integrityErrors.length === 0, assets_current: assetsCurrent, current: currentErrors.length === 0, ok: errors.length === 0,
407
414
  errors, legacy_files: legacy, unexpected_files: extra, documents };
408
415
  }
409
416
 
410
417
  function help() {
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.`);
418
+ console.log(`auto-coding-skill ${pkg.version}
419
+
420
+ autocoding init [--dest PATH] [--dry-run] [--json]
421
+ autocoding sync [--projects PATH[,PATH...]] [--dry-run] [--json]
422
+ autocoding status [--projects PATH[,PATH...]] [--json]
423
+ autocoding doctor [--projects PATH[,PATH...]] [--json]
424
+ autocoding guard-sync [--dest PATH] [--dry-run] [--json]
425
+
426
+ Changed or unowned managed files block replacement. Migrate project facts first,
427
+ then use --replace-managed --backup-dir <private-external-directory> if intended.
428
+ Doctor is read-only. Guard-sync only refreshes recognized Git guard source pairs;
429
+ it never opts a clone in, changes hooks, starts CI or deploys.`);
412
430
  }
413
431
 
414
432
  const args = parseArgs(process.argv);
433
+ const local = diagnostics({ packageRoot, managedTarget, sha256 });
415
434
  if (args.command === "help") help();
416
435
  else if (args.command === "init") installProjects([args.dest || process.cwd()], args);
417
436
  else if (args.command === "sync") {
418
437
  const projects = args.projects.length ? args.projects : [process.cwd()];
419
438
  installProjects(projects, args);
420
- } else if (args.command === "status") {
421
- const projects = args.projects.length ? args.projects : [process.cwd()];
422
- const results = projects.map(status);
439
+ } else if (args.command === "status" || args.command === "doctor") {
440
+ const projects = args.projects.length ? args.projects : [args.dest || process.cwd()];
441
+ const results = projects.map(p => args.command === "doctor" ? local.doctor(status(p)) : status(p));
423
442
  toJson({ version: pkg.version, results }, args.json);
424
443
  if (results.some(result => !result.ok)) process.exitCode = 1;
444
+ } else if (args.command === "guard-sync") {
445
+ if (args.projects.length || args.replaceManaged || args.backupDir) fail("guard-sync accepts --dest PATH, --dry-run and --json only");
446
+ const result = local.guardSync(fs.realpathSync(args.dest || process.cwd()), args.dryRun);
447
+ toJson(result, args.json);
448
+ if (!result.ok) process.exitCode = 1;
425
449
  } else fail(`unknown command: ${args.command}`);