@elvis1513/auto-coding-skill 5.0.5 → 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
@@ -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,8 +49,10 @@ 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
55
+ autocoding doctor --projects . --json
51
56
  ```
52
57
 
53
58
  These commands only install, preserve, and report documentation. They never run
@@ -61,6 +66,41 @@ when both checks pass and no leftovers need review; otherwise status exits with
61
66
  code 1. This is a local comparison, not an npm registry update check or an
62
67
  engineering gate. Project-owned document contents are not inspected for drift.
63
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
+
84
+ `init`/`sync` preflight every requested project before refreshing any of them.
85
+ Modified or unowned files in the managed skill tree, `AGENTS.md`, or
86
+ `docs/ENVIRONMENT.md` block replacement; their contents are not printed.
87
+ `--dry-run --json` previews affected paths and conflicts without writing files.
88
+ Review the differences and migrate useful project facts into `PROJECT.md` or
89
+ topic documents first. If replacement is then intended, explicitly request it:
90
+
91
+ ```bash
92
+ autocoding init --replace-managed --backup-dir /private/external/skill-backups
93
+ ```
94
+
95
+ The backup directory must be outside all target projects, including through
96
+ symlinks. Each replacement creates a new private backup directory (0700), copies
97
+ the conflicting files with mode 0600, verifies their hashes, and records their
98
+ source paths. It does not overwrite an earlier backup. A dry-run does not create
99
+ backups. Review backups as potentially credential-bearing data; never commit them.
100
+ The override does not merge project instructions automatically or authorize
101
+ discarding them. Whole-batch preflight prevents known conflicts from producing a
102
+ partial upgrade; it is not a filesystem transaction for failures such as disk loss.
103
+
64
104
  During upgrades, unchanged manifest-owned legacy files can be retired; the old
65
105
  `docs/ENGINEERING.md` policy is archived first. Modified legacy files outside the
66
106
  managed skill tree are preserved and reported across subsequent upgrades.
@@ -78,6 +118,11 @@ overwrite its own development instructions. Here, `status` reports source
78
118
  discovery, packaged asset alignment, and legacy leftovers instead of expecting a
79
119
  project install manifest.
80
120
 
121
+ Keep project constraints and validation entry points near the top of
122
+ `PROJECT.md`; read them before writing files or operating environments, including
123
+ when another skill suggests a default output path. Link to relevant existing
124
+ topic docs for historical detail. Shared managed files are not project overrides.
125
+
81
126
  ```bash
82
127
  npm run sync-assets
83
128
  npm run release:check
@@ -88,3 +133,10 @@ intended models: a read-only diagnosis, a focused fix, an already-authorized
88
133
  delivery, and a blocked external job. Compare scope adherence, verification,
89
134
  completion evidence, and unnecessary questions or repeated work. These are
90
135
  evaluation scenarios, not required steps for every consuming project task.
136
+
137
+ Include regressions for artifact paths, managed-file ownership, preservation
138
+ during upgrades, concurrent worktrees with conflicting changes, and a completed
139
+ application delivery followed by an unrelated documentation build. The last case
140
+ must not add an unrequested CI wait or background monitor. For parallel work,
141
+ exercise a rejected stale push, conflict reconciliation, verification of both
142
+ 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.2.0",
4
4
  "asset_files": [
5
5
  {
6
6
  "path": "SKILL.md",
7
- "sha256": "54c28a7a3a147460b96e11d3da92e7722690e2836db3e5c35fa28dfc46c2860c"
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": "f311a02d02bd6a924f94cbf341ff90dba839bf70a1f97d83500a7d2660dad6c1"
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": "6f3c5a2881d0b0252c7b7512f5783e9c06346656e2415be9bcec3f2070025755"
23
+ "sha256": "0c3aa3de1b09b19c5797aaa20b77b3f5fc1f8242223a724d878ab4c17f9e3c9b"
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": "e73e646aa0b300c9d5ef26c8044e26f11c1d4c3f97a07ef26a5a263a42fa540f"
40
44
  }
41
45
  ]
42
46
  }
@@ -1,28 +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`, then use the project documentation only when it helps the
9
- current request:
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.
10
11
 
11
- - `docs/ENVIRONMENT.md` for shared access endpoints, ports, and local credential references.
12
- - `docs/PROJECT.md` for project-specific runtime facts and configuration.
13
- - `docs/product/` for durable product context and decisions.
14
- - `docs/architecture/`, `docs/design/`, `docs/interfaces/`, and
15
- `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.
16
15
 
17
- Use the project's guidance to choose an approach and enough verification for the
18
- requested outcome. This Skill adds context, not a fixed task protocol or model
19
- profile; it does not narrow existing authorization or redefine completion.
20
-
21
- Write documentation only when the user asks for it or when a durable fact,
22
- contract, decision, test strategy, or operating procedure would otherwise be
23
- lost. Choose the relevant existing folder; do not create routine task records,
24
- review records, or duplicate summaries.
25
-
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.
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,32 +1,16 @@
1
- # Project Configuration
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 entry is project-owned. Init/sync create it only when missing.
5
4
 
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.
5
+ ## Current working context
10
6
 
11
- ## Project services and ports
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.
12
10
 
13
- - Application endpoints:
14
- - Internal services:
15
- - Runtime and dependency versions:
11
+ ## Topic and access index
16
12
 
17
- ## Shared-access overrides
18
-
19
- - Backend host or URL:
20
- - Credential records:
21
- - Access constraints:
22
-
23
- ## Runtime and operations
24
-
25
- - Local start and diagnostic entry points:
26
- - Relevant verification commands and acceptance criteria:
27
- - Deployment topology:
28
- - Logs and metrics:
29
-
30
- ## Constraints and durable decisions
31
-
32
- -
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,65 +1,27 @@
1
- <!-- auto-coding-skill:managed-agents:start version=5.0.5 -->
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. 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.
27
-
28
- Verify the changed behavior and relevant failure paths with evidence proportionate
29
- to the risk. Start with focused checks and broaden when impact or findings justify
30
- it. Honor required project checks; avoid repeating an unchanged check without a
31
- reason. State what was verified and any remaining uncertainty.
32
-
33
- Completion follows the requested outcome. Editing, committing, pushing, CI, and
34
- deployment are distinct results: complete the authorized parts the goal requires
35
- and report the evidence for each. A launched command or background job is not a
36
- successful result; follow required work to its terminal state. If that is not
37
- possible, report the specific blocker or pending state without claiming completion.
38
-
39
- ## Documentation
40
-
41
- Read relevant project documentation before relying on project context:
42
-
43
- - `docs/ENVIRONMENT.md`: shared GitLab, Nexus, Jenkins, and backend endpoint/port references. Managed and refreshed by the Skill.
44
- - `docs/PROJECT.md`: project-specific runtime facts, access overrides, and constraints. Project-owned and never overwritten by the Skill.
45
- - `docs/product/`: durable product context, boundaries, and decisions.
46
- - `docs/architecture/`: architecture and ADRs.
47
- - `docs/design/`: durable design notes that help future implementation.
48
- - `docs/interfaces/`: public API, event, protocol, or integration contracts.
49
- - `docs/deployment/`: runbooks and durable operating procedures.
50
-
51
- Documentation is optional. Do not create a record for a routine edit, a transient
52
- investigation, an ordinary review, or every commit. Record something only when the
53
- user asks or when the information will remain useful after the immediate task.
54
- Put it in the narrowest applicable folder and update an existing document instead
55
- of creating parallel summaries.
56
-
57
- ## Environment and credentials
58
-
59
- `docs/ENVIRONMENT.md` is shared managed context: it names endpoint ports and
60
- credential lookup guidance, but never contains plaintext credentials. Project
61
- specific configuration belongs in `docs/PROJECT.md`; it is preserved across
62
- Skill upgrades and may hold project-approved plaintext credential records. Never
63
- invent credentials, copy them into chat output, or expose them in logs.
64
-
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.
65
27
  <!-- auto-coding-skill:managed-agents:end -->
@@ -0,0 +1,39 @@
1
+ # Parallel repository development
2
+
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
+ }