@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 +16 -0
- package/cli/assets/managed-install.json +5 -5
- package/cli/assets/skill/SKILL.md +13 -38
- package/cli/assets/skill/data/templates/PROJECT.md +10 -29
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +26 -97
- package/cli/assets/skill/references/parallel-development.md +37 -59
- package/cli/src/check-package.js +3 -2
- package/cli/src/diagnostics.js +121 -0
- package/cli/src/index.js +29 -5
- package/package.json +4 -2
- package/src/git-workflow/guard.py +451 -0
- package/src/git-workflow/test_guard.py +341 -0
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.
|
|
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",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
},
|
|
41
41
|
{
|
|
42
42
|
"path": "references/parallel-development.md",
|
|
43
|
-
"sha256": "
|
|
43
|
+
"sha256": "e73e646aa0b300c9d5ef26c8044e26f11c1d4c3f97a07ef26a5a263a42fa540f"
|
|
44
44
|
}
|
|
45
45
|
]
|
|
46
46
|
}
|
|
@@ -1,46 +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
|
-
|
|
10
|
-
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
1
|
+
# Project configuration
|
|
2
2
|
|
|
3
|
-
This
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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.
|
|
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
|
-
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
task
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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.
|
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
|
+
}
|
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}
|
|
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}`);
|