@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 +53 -1
- package/cli/assets/managed-install.json +8 -4
- package/cli/assets/skill/SKILL.md +13 -20
- package/cli/assets/skill/data/templates/PROJECT.md +11 -27
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +26 -64
- package/cli/assets/skill/references/parallel-development.md +39 -0
- package/cli/src/check-package.js +3 -2
- package/cli/src/diagnostics.js +121 -0
- package/cli/src/index.js +139 -8
- package/package.json +5 -3
- package/src/git-workflow/guard.py +451 -0
- package/src/git-workflow/test_guard.py +341 -0
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
|
|
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
|
|
3
|
+
"skill_version": "5.2.0",
|
|
4
4
|
"asset_files": [
|
|
5
5
|
{
|
|
6
6
|
"path": "SKILL.md",
|
|
7
|
-
"sha256": "
|
|
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": "
|
|
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": "
|
|
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
|
|
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
|
-
|
|
9
|
-
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
|
1
|
+
# Project configuration
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
- Internal services:
|
|
15
|
-
- Runtime and dependency versions:
|
|
11
|
+
## Topic and access index
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
|
|
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
|
|
2
|
-
#
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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.
|
package/cli/src/check-package.js
CHANGED
|
@@ -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 (
|
|
34
|
-
|
|
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
|
+
}
|