@jenga-ai/agent 2.0.0 → 3.1.0

package/templates/copilot-instructions.md.tpl

@@ -9,8 +9,15 @@ This project uses **Jenga** — a skill-based AI agent framework. Jenga organise
 
 ### How Jenga Works
 
-- Each **skill** is a self-contained instruction set stored under `.agents/skills/<skill-name>/` (the non-Claude discovery path; Claude Code reads the same content from `.claude/skills/`).
-- Skills are invoked by typing `j:skill-name` in the chat prompt (e.g. `j:status`, `j:commit`). The
+- Each **skill** is a self-contained instruction set: a `SKILL.md` file inside a per-skill directory.
+  Copilot discovers project skills from **all three** of `.github/skills/`, `.agents/skills/`, and
+  `.claude/skills/`. Jenga installs its skills under `.agents/skills/<skill-name>/` and mirrors
+  byte-identical content into `.claude/skills/<skill-name>/`; when the same skill name is found in
+  more than one of those directories, `.agents/skills/` takes precedence. Cite and open
+  `.agents/skills/` as the canonical path.
+- A skill's **identity is its frontmatter `name:` field, not its directory name**. Jenga names every
+  skill `j.<skill-name>` — the skill in `.agents/skills/status/` declares `name: j.status`.
+- Skills are invoked by typing `j.skill-name` in the chat prompt (e.g. `j.status`, `j.commit`). The
   older bare `/skill-name` form (e.g. `/status`, `/commit`) is a **permanent alias** — it keeps
   resolving indefinitely, with no deprecation warning and no removal planned — so treat a message in
   either form as the exact same invocation.
@@ -18,22 +25,43 @@ This project uses **Jenga** — a skill-based AI agent framework. Jenga organise
 
 ### Skill Routing
 
-Unlike Claude Code, GitHub Copilot has **no native slash-command interception** — typing `j:skill-name`
-(or the older bare `/skill-name` alias) does not automatically load or run anything on its own. Copilot
-depends entirely on the instructions below to know what "invoking a skill" concretely means. Do not
-improvise a plausible-sounding response instead of following these steps — that is the exact failure
-this section exists to prevent.
+**Copilot loads these skills natively.** Copilot has a real, validating skill loader. It reads every
+`SKILL.md` under the discovery paths above and validates each one's frontmatter `name:` against:
 
-**Old bare-form alias.** `j:skill-name` is the canonical invocation form. A message using the older
+```
+Skill name must start with an ASCII letter or number and contain only
+ASCII letters (a-z, A-Z), numbers, hyphens, underscores, dots, and spaces
+```
+
+A skill whose name fails that rule **does not load at all** — it is reported under "failed to load"
+by `copilot skill list` and is simply absent from the session. Every skill that does load is
+registered as a **native slash command named after its frontmatter `name`**, matched
+case-insensitively: `j.status` is invocable as `/j.status` and appears in the slash-command picker.
+That native path loads and applies the skill on its own — you do not need to locate or open the file
+yourself when the user types it.
+
+**What still depends on these instructions.** Native registration covers only the exact
+`/j.skill-name` form. These forms have **no** native handler and are routed entirely by the steps
+below:
+
+- the no-slash `j.skill-name` form, which is Jenga's documented invocation style;
+- the older bare `/skill-name` alias (`/status`, `/commit`);
+- a message that matches a skill by keyword or intent rather than by a literal command.
+
+For those, do not improvise a plausible-sounding response instead of following these steps — that is
+the exact failure this section exists to prevent.
+
+**Old bare-form alias.** `j.skill-name` is the canonical invocation form. A message using the older
 bare `/skill-name` form is not deprecated and must not be treated as an error, a warning case, or a
-migration prompt — route it to the identical skill as its `j:skill-name` equivalent. Both forms remain
+migration prompt — route it to the identical skill as its `j.skill-name` equivalent. Both forms remain
 equally valid indefinitely.
 
-When the user's message is or matches `j:skill-name`, or matches the older bare `/skill-name` alias (or
+When the user's message is or matches `j.skill-name`, or matches the older bare `/skill-name` alias (or
 otherwise clearly matches a known skill's keyword or intent):
 
 1. Locate the target file at `.agents/skills/<skill-name>/SKILL.md` (the discovery path from "How
-   Jenga Works" above).
+   Jenga Works" above; `.claude/skills/<skill-name>/SKILL.md` holds identical content if the first
+   is absent). Note the directory is the **unprefixed** name — `j.status` lives in `status/`.
 2. Open and read that file **in full** before doing anything else.
 3. Execute its instructions exactly as written, for the rest of this turn — including running any
    shell scripts or commands it references (e.g. via a terminal/shell tool).
@@ -46,20 +74,61 @@ answer directly using your full capabilities.
 
 #### Routing decision table
 
-Before acting on any row below that opens a `SKILL.md` file, first check the identifier against
-the trusted allow-list: {{ALLOWED_SKILL_IDS}}. Since Copilot/Codex has no native interception for
-`j:skill-name`, this prose-level check is the entire enforcement mechanism — there is no runtime
-guard behind it.
+Before acting on any row below that opens a `SKILL.md` file yourself, check the identifier against
+the trusted allow-list: {{ALLOWED_SKILL_IDS}}.
+
+There are two enforcement layers, and they cover different inputs:
+
+1. **Copilot's own loader** handles the native `/j.skill-name` form. It only ever registers a skill
+   that is actually present under a discovery path and passed name validation.
+2. **This prose allow-list check** is the second layer — and the *only* layer for the forms Copilot
+   does not natively intercept: the no-slash `j.skill-name` form, the bare `/skill-name` alias, and
+   keyword or intent matches. Apply it whenever you are about to open a `SKILL.md` yourself.
+
+Neither layer inspects a skill's *contents*; both defend the invocation-matching layer only.
 
 | Situation | Action |
 |-----------|--------|
-| Message matches `j:skill-name` and `skill-name` is in the allow-list | Open `.agents/skills/<skill-name>/SKILL.md`, read it fully, execute it as written |
-| Message matches the older bare `/skill-name` alias and `skill-name` is in the allow-list | Treat identically to `j:skill-name` — same skill, same file, no warning, no migration prompt |
+| User types the native `/j.skill-name` slash command | Copilot's loader applies the skill; follow the loaded instructions as written |
+| Message matches `j.skill-name` (no slash) and `skill-name` is in the allow-list | Open `.agents/skills/<skill-name>/SKILL.md`, read it fully, execute it as written |
+| Message matches the older bare `/skill-name` alias and `skill-name` is in the allow-list | Treat identically to `j.skill-name` — same skill, same file, no warning, no migration prompt |
 | Message matches a skill keyword or intent and the matched skill is in the allow-list | Open `.agents/skills/<skill-name>/SKILL.md`, read it fully, execute it as written |
-| Message matches `j:skill-name` or `/skill-name`, but `skill-name` is **not** in the allow-list | Do not open or execute anything — tell the user the identifier is unrecognized and is not a known Jenga skill |
+| Message matches `j.skill-name` or `/skill-name`, but `skill-name` is **not** in the allow-list | Do not open or execute anything — tell the user the identifier is unrecognized and is not a known Jenga skill |
 | Message is a general coding or project question | Answer directly |
 | Ambiguous — could be skill or free-form | Prefer the skill; open and execute its `SKILL.md` rather than describing it |
 
+### Sub-Agent Delegation (`prefered_agent`)
+
+Some skills declare a `metadata.prefered_agent: <agent_name>` field in their `SKILL.md`
+frontmatter. This names a sub-agent persona — a file under `agents/` (`scrum-master`,
+`developer`, `tester`) — that should execute the skill, the same delegation Claude Code performs
+natively for the same skill via root `CLAUDE.md`'s "Skill Frontmatter" section.
+
+**Copilot CLI has its own native custom-agent-loading mechanism for this.** The `--agent <name>`
+CLI flag and the interactive `/agent [name]` command both load a custom agent-definition file
+discovered from `.github/agents/*.md` or `.claude/agents/*.md`, keyed by that file's frontmatter
+`name:` field — not its filename. Jenga's `agents/*.md` personas are mirrored into both of those
+paths by `/self-sync` (`skills/self-sync/scripts/run.js`); cite `.github/agents/` as the
+canonical path for this purpose, parallel to how "How Jenga Works" above cites `.agents/skills/`
+as canonical for skills. `.agents/agents/` is also mirrored (for reasons unrelated to Copilot)
+but is a **confirmed Copilot-discovery dead-end** — the native agent loader does not read it;
+never rely on it when resolving a `prefered_agent`.
+
+When a matched skill's frontmatter has `metadata.prefered_agent: <agent_name>`:
+
+1. Before executing the skill's instructions, load that persona by invoking `--agent
+   <agent_name>` (if starting a new `copilot` invocation) or the interactive `/agent
+   <agent_name>` command (if already in an interactive session).
+2. Then proceed with the skill's instructions exactly as written, per the "Skill Routing"
+   section above — the loaded agent persona governs *how* the skill executes, not *whether* it
+   does, and does not change which `SKILL.md` file gets opened or the allow-list check that
+   precedes it.
+3. If a skill's frontmatter has no `prefered_agent` field, execute it directly with no agent
+   switch.
+
+Valid `<agent_name>` values match the agent definitions under `agents/` (frontmatter `name:`
+field, not the filename): `scrum-master`, `developer`, `tester`.
+
 ### Available Skills
 
 {{SKILL_LIST}}
@@ -77,6 +146,7 @@ The `hooks/`, `lib/`, `scripts/`, `templates/`, and `mcp/` directories all live
 ### Notes
 
 - Always resolve file paths relative to `JENGA_PROJECT_DIR`.
-- When a skill asks you to read a file such as `SKILL.md` or a task file, look for it inside `JENGA_PROJECT_DIR/.agents/skills/` or `JENGA_PROJECT_DIR/project/board/` respectively.
+- When a skill asks you to read a file such as `SKILL.md` or a task file, look for it inside `JENGA_PROJECT_DIR/.agents/skills/` (or `JENGA_PROJECT_DIR/.claude/skills/`, which mirrors it) or `JENGA_PROJECT_DIR/project/board/` respectively.
+- If a Jenga skill seems to be missing entirely, run `copilot skill list` and check the "failed to load" section before assuming it does not exist — a name that fails validation is absent rather than broken.
 - Commit messages and branch names follow the EST naming convention (`E<n>_S<n>_T<n>`).
 <!-- JENGA:END -->

package/skills/continue/SKILL.md

@@ -1,29 +0,0 @@
----
-name: j:continue
-description: Check project status across PROJECT_SUMMARY.md, epics, and stories to determine what should be done next. Reports "All done!" if everything is complete.
-keywords:
-  - continue
-  - next
-  - proceed
-  - what's next
-  - status
-examples:
-  - "what should I do next?"
-  - "continue with the project"
----
-
-# Continue — Pick Up the Next Work Item
-
-## Instructions
-
-1. **Check `project/PROJECT_SUMMARY.md`** — Determine if there is outstanding work at the project level.
-
-2. **Check `project/epics/`** — If the project summary is done, check if any epics have remaining work.
-
-3. **Check `project/stories/`** — If epics are done, check if any stories have remaining work.
-
-   **Important:** Always check story status within an epic even if the epic itself is marked as done.
-
-4. **If everything is complete** — Respond with: "All done! 🎉"
-
-5. **Otherwise** — Begin work on the next incomplete item.

package/skills/error/SKILL.md

@@ -1,29 +0,0 @@
----
-name: j:error
-description: Guided troubleshooting flow that gathers context about an error — where it occurs, what was attempted, what went wrong, and what was expected.
-keywords:
-  - error
-  - bug
-  - fix
-  - troubleshoot
-  - debug
-  - broken
-examples:
-  - "I'm getting an error"
-  - "help me fix this bug"
-metadata: 
-  prefered_agent: tester
----
-
-# Error — Guided Troubleshooting
-
-## Instructions
-
-Ask the following questions to understand the background of the error:
-
-1. Where does the error occur?
-2. What are you trying to do?
-3. What went wrong?
-4. What was the expected outcome?
-
-Then use the answers to investigate and resolve the issue by creating a issue using the /todo skill.

package/skills/examplify/SKILL.md

@@ -1,42 +0,0 @@
----
-name: j:examplify
-description: Explains concepts, features, use cases, and patterns based on provided context — a description, scenario, code snippet, or file. Use when the user wants to understand what something is, how it works, when to use it, or wants a concrete example.
-keywords:
-  - examplify
-  - explain
-  - example
-  - how does
-  - understand
-examples:
-  - "explain how this works"
-  - "give me an example of X"
----
-
-# Concept Explainer
-
-## Instructions
-
-If the context is unclear or too broad, ask one focused clarifying question before proceeding. Otherwise, infer and proceed.
-
-Explain the concept by covering:
-
-1. **What it is** — a plain-language definition
-2. **Why it exists** — the problem it solves
-3. **How it works** — core mechanics
-4. **When to use it** — and when not to
-5. **Example(s)** — grounded in the user's context; show a before/after when relevant
-
-After delivering the explanation, save a copy to:
-`project/documentation/examples/<concept_and_context>.md`
-
-Derive the filename from the concept + context (lowercased, hyphenated). Tell the user where the file was saved.
-
-## Follow-up
-
-If further discussion reveals new information about the topic — a new use case, correction, or better example — ask the user:
-
-> "That adds something new to what we covered — want me to update the saved file?"
-1. Yes
-2. No
-
-If yes, append the new content under an `## Additional Notes` section. Do not overwrite the original.

package/skills/init/SKILL.md

@@ -1,155 +0,0 @@
----
-name: j:init
-description: Initialize a new project with the standard directory structure, PROJECT_SUMMARY.md, workflow.json, git repo, and gitignore. Follows a defined ordered onboarding sequence. Use when setting up a new or empty project.
-keywords:
-  - init
-  - initialize
-  - setup
-  - new project
-  - scaffold
-examples:
-  - "initialize a new project"
-  - "set up a new workspace"
----
-
-# Init — Project Setup
-
-## Instructions
-
-Follow these steps in order. Do not skip steps — the sequence matters.
-
-### 1. Detect existing project state
-
-Before asking anything or scaffolding anything, classify the target directory
-(the current directory) by running the detection script:
-
-```bash
-skills/init/scripts/detect-existing-codebase.sh .
-```
-
-It prints exactly one verdict on stdout:
-
-| Verdict | Meaning | What to do |
-|---|---|---|
-| `empty` | The directory is empty, or contains only `.git`, `.gitignore`, and top-level `README*`/`LICENSE*` boilerplate. | Proceed to step 2 — behaviour here is unchanged from before this detection step existed. |
-| `already-scaffolded` | `project/board/`, `project/PROJECT_SUMMARY.md`, or `project/configs/workflow.json` already exists. | Tell the user this directory already has a Jenga scaffold and **stop** — do not run the scaffold script. Re-running it would silently overwrite `PROJECT_SUMMARY.md` and `workflow.json` with fresh stubs. Point them at `/continue` or `/status` instead. |
-| `existing-codebase` | The directory has real content (source, configs, docs beyond the boilerplate list) and is not already scaffolded. | **Pause. Do not scaffold.** Present the choice below and wait for an answer. |
-
-On `existing-codebase`, present this choice verbatim, per the Interaction Pattern in
-`CLAUDE.md` (numbered, free-text last):
-
-    This directory already contains code that wasn't built through Jenga. How would
-    you like to proceed?
-    1. Run /uncharted onboard first, to analyze the existing code and backfill the
-       board before scaffolding
-    2. Scaffold fresh anyway, leaving the board empty (the existing code is never
-       modified either way — onboard mode and fresh scaffolding are both board-only)
-    3. Abort — don't scaffold, don't run /uncharted
-    4. Other (describe below)
-
-- **Option 1** — invoke `/uncharted onboard`. It analyzes the existing code and backfills
-  the board; it never modifies, moves, or restructures application code. Once it
-  finishes, the directory now has `project/PROJECT_SUMMARY.md` etc., so re-running this
-  detection step returns `already-scaffolded` — there is nothing left to scaffold.
-- **Option 2** — continue to step 2 and scaffold fresh. Note in your response that the
-  board will start empty despite the directory containing pre-existing code, since the
-  user explicitly chose that.
-- **Option 3** — stop here. Do not run the scaffold script and do not invoke `/uncharted`.
-- **Option 4** — handle the free-text response on its own merits.
-
-If the run is non-interactive (no user available to answer), default to **option 3
-(abort)**. Unlike the visibility question in step 2, none of these three choices is a
-no-op: running `/uncharted onboard` unattended commits an analysis pass the user never
-asked for, and scaffolding fresh unattended silently discards pre-existing code from the
-board exactly as `/init` did before this step existed. Aborting is the only choice that
-changes nothing on disk, so it is the only safe default.
-
-Never treat `existing-codebase` as if it were `empty`, and never skip straight to step 2
-on that verdict without the user (or the non-interactive default) choosing to.
-
-### 2. Ask how Jenga AI's working files should appear
-
-Ask the user this question, verbatim, before running any script:
-
-    How should Jenga AI's own working files (project/ — the scrum board, todo.md,
-    queue/, rapports/, and logs/) appear in this project?
-    1. Visible — keep them at `project/`, tracked and visible in directory listings
-    2. Ignored — keep them at `project/` but add them to `.gitignore` so they are never committed
-    3. Not sure — explain the trade-offs and ask me again
-
-If the user picks option 3, explain the trade-offs and re-ask. Do not proceed until
-the answer is one of `visible` or `ignored`.
-
-If the run is non-interactive (no user available to answer), use the default:
-**`visible`**. It is the only choice that changes nothing on disk, so an unattended
-run can never silently relocate directories or edit `.gitignore`.
-
-> A third mode, `hidden` (dot-prefixing `project/` to `.project/`, matching the
-> `.agents/`/`.claude/` convention), was built and then withdrawn before release —
-> testing found it left board resolution and session-end hooks writing to two
-> different trees. It is not offered here. See
-> `skills/distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
-> follow-up to reintroduce it once fixed.
-
-Carry the chosen value into step 3. Do not apply it yourself — the script owns all
-of the mechanical work.
-
-### 3. Run the scaffold script
-
-`init.sh` is not guaranteed to live at a single fixed path: in a project that
-installed Jenga via npm, it was mirrored to `.claude/skills/init/scripts/`
-(Claude Code) and `.agents/skills/init/scripts/` (Copilot/other agents) by
-`postinstall.js`, and neither of those exists yet in this framework's own
-source checkout, where it lives at the bare `skills/init/scripts/` path
-instead. This step runs before `CLAUDE.md`/`AGENTS.md` exist, so it cannot
-rely on either file's routing instructions to resolve the path — it must
-locate its own script directly. Execute the init script from the project
-root, passing the choice from step 2:
-
-```bash
-INIT_SCRIPT=""
-for candidate in .claude/skills/init/scripts/init.sh .agents/skills/init/scripts/init.sh skills/init/scripts/init.sh; do
-  [[ -f "$candidate" ]] && { INIT_SCRIPT="$candidate"; break; }
-done
-if [[ -z "$INIT_SCRIPT" ]]; then
-  echo "Error: could not locate init.sh under .claude/skills/, .agents/skills/, or skills/" >&2
-  exit 1
-fi
-chmod +x "$INIT_SCRIPT" && "$INIT_SCRIPT" --visibility <visible|ignored>
-```
-
-Omitting `--visibility` falls back to the `JENGA_PROJECT_FILES_VISIBILITY`
-environment variable, then to `visible`.
-
-This script handles all scaffolding in one step:
-1. Initializes the git repository
-2. Creates `.gitignore`
-3. Creates the full directory structure under `project/`
-4. Creates `project/PROJECT_SUMMARY.md` with placeholder content
-5. Creates `project/configs/workflow.json` with shared constants
-6. Creates `project/configs/test-config.json` stub
-7. Creates `project/configs/scope-thresholds.json` with default execution-scope thresholds (consumed by `/jenga` and `/do`, which halt if it's missing)
-8. Creates `project/data/baselines.json`
-9. Creates `project/logs/events.json`
-10. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
-11. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
-12. Applies the chosen visibility mode via `scripts/apply-project-visibility.sh`, which records it as `project_files_visibility` in `jenga.config.json` and performs any `.gitignore` change
-13. Stages and commits all files with the message `init: scaffold project structure and workflow config`
-
-The visibility mode is validated before any scaffolding happens, so an invalid
-value fails fast and leaves nothing behind. It is applied before the commit, so
-the `.gitignore` entry is captured in the initial commit.
-
-If the script fails, check that you are in the project root and that git and `jq`
-are available.
-
-See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility`
-field reference.
-
-### 4. Prompt next step
-
-Inform the user that setup is complete, and state which visibility mode was applied
-and where the working files now live. Mention that `docs/STRATEGY.md` was created as
-a strategic brief stub for investors, partners, and the product team — they can fill
-it in now or return to it later. Suggest running `/pi-plan` to define project goals
-and epics.

package/skills/init/assets/scope-thresholds_template.json

@@ -1,7 +0,0 @@
-{
-  "threshold_version": 2,
-  "inline_max_files": 3,
-  "inline_max_lines": 75,
-  "story_max_files": 5,
-  "bundle_lock_ttl_minutes": 30
-}

package/skills/init/assets/strategy_stub_template.md

@@ -1,38 +0,0 @@
-# Strategy
-
-<!-- This document is intended for investors, strategic partners, and senior stakeholders.
-     Write in clear, confident language that conveys conviction and focus.
-     Avoid jargon. Prioritise substance over length. -->
-
-## Vision
-
-<!-- Describe the long-term direction of this project over a 3–5 year horizon.
-     What change do you want to see in the world, and what role does this project play in bringing it about?
-     A strong vision statement is specific, ambitious, and grounded — it should be possible to hold yourself accountable to it. -->
-
-## Value Proposition
-
-<!-- Articulate what makes this project uniquely valuable and to whom.
-     Answer: Why does this exist? Why now? Why this team?
-     Focus on the distinct advantage or insight that underpins the project — not features, but the underlying value delivered. -->
-
-## Scope
-
-### In Scope
-
-<!-- List the capabilities, domains, or problem spaces this project actively addresses.
-     Be specific enough that a new stakeholder can quickly understand the boundaries of the work.
-     Use bullet points for readability. -->
-
-### Out of Scope
-
-<!-- List what this project explicitly does not cover.
-     Revenue model, pricing strategy, and competitive analysis are intentionally excluded from this document —
-     they belong in separate artefacts and are out of scope here.
-     Use this section to prevent scope creep and set clear expectations with stakeholders. -->
-
-## Target Audience
-
-<!-- Describe who this project is built for.
-     Include both the end users (who experiences the product) and the stakeholders (who evaluates or funds it).
-     Be specific: a well-defined audience sharpens every other section of this document. -->

package/skills/init/assets/workflow_template.json

@@ -1,30 +0,0 @@
-{
-  "statuses": ["Pending", "In Progress", "Passed", "Passed with remarks", "Failed", "Rejected", "Blocked"],
-  "rapport_types": ["conflict", "implementation_blocker", "security_concern", "test_failure", "analysis"],
-  "paths": {
-    "board": "project/board",
-    "epics": "project/board/epics",
-    "stories": "project/board/stories",
-    "tasks": "project/board/tasks",
-    "rapports_problems": "project/rapports/problems",
-    "rapports_analysis": "project/rapports/analysis",
-    "queue": "project/queue",
-    "scrum_triggers": "project/queue/scrum_triggers.jsonl",
-    "developer_triggers": "project/queue/developer_triggers.jsonl",
-    "tester_triggers": "project/queue/tester_triggers.jsonl",
-    "session_handoff": "project/queue/handoffs/",
-    "logs": "project/logs",
-    "data": "project/data",
-    "configs": "project/configs",
-    "documentation": "project/documentation",
-    "documentation_plans": "project/documentation/plans",
-    "documentation_summaries": "project/documentation/summaries"
-  },
-  "agents": ["developer", "tester", "scrum-master"],
-  "pipeline": [
-    {"step": 1, "agent": "scrum-master", "phase": "planning",        "on_complete": "write planning_complete handoff → developer_triggers.jsonl"},
-    {"step": 2, "agent": "developer",    "phase": "implementation",  "on_complete": "write implementation_complete handoff → tester_triggers.jsonl"},
-    {"step": 3, "agent": "tester",       "phase": "verification",    "on_complete": "write test status handoff → scrum_triggers.jsonl (+ developer_triggers.jsonl if failed)"},
-    {"step": 4, "agent": "scrum-master", "phase": "rollup_review",   "on_complete": "update board statuses, close epic/story if all done"}
-  ]
-}

package/skills/init/scripts/apply-project-visibility.sh

@@ -1,176 +0,0 @@
-#!/usr/bin/env bash
-#
-# apply-project-visibility.sh — apply the `project_files_visibility` mode to a project.
-#
-# Usage:
-#   apply-project-visibility.sh <mode> [project_root]
-#   apply-project-visibility.sh --check-only <mode>
-#
-# Modes:
-#   visible   Working files stay where they are. No-op on disk beyond the config write.
-#   ignored   Working files are added to the project's .gitignore — present on disk,
-#             never committed.
-#
-# NOTE: A third mode, `hidden` (dot-prefixing project/ -> .project/), was
-# implemented and then withdrawn before release. Testing found it functionally
-# broken: scripts/board_resolver.sh hardcodes project/configs/workflow.json
-# and never locates the rewritten path, and hooks/on_session_end.sh
-# unconditionally recreates a shadow project/ tree on every session end,
-# splitting runtime state across two trees. See
-# project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md
-# for the full findings. Re-introducing `hidden` requires fixing both of
-# those hardcoded paths first — tracked as a follow-up /todo item.
-#
-# Exit codes:
-#   0  Success
-#   1  Bad usage or missing prerequisite
-#   2  Invalid mode (outside the two-value enum)
-#   3  Filesystem apply failure
-#   4  jenga.config.json write failure
-
-# Do NOT use set -e globally — each step handles its own errors.
-set -uo pipefail
-
-info() { echo "[visibility] $*"; }
-warn() { echo "[visibility] WARNING: $*"; }
-err()  { echo "[visibility] ERROR: $*" >&2; }
-
-usage() {
-  echo "Usage: $(basename "$0") <visible|ignored> [project_root]" >&2
-  echo "       $(basename "$0") --check-only <visible|ignored>" >&2
-  exit 1
-}
-
-# Every Jenga AI working file named in E31_S05 — the scrum board, todo.md,
-# queue/, rapports/ and logs/ — nests under this single root, so one entry
-# covers them all. `ignored` consumes this list.
-JENGA_WORKING_PATHS=("project")
-
-VALID_MODES="visible ignored"
-
-validate_mode() {
-  local mode="$1"
-  for valid in $VALID_MODES; do
-    [ "$mode" = "$valid" ] && return 0
-  done
-  err "Invalid project_files_visibility value: '${mode}'"
-  err "Allowed values are: ${VALID_MODES// /, }"
-  exit 2
-}
-
-# ---------------------------------------------------------------------------
-# Argument parsing
-# ---------------------------------------------------------------------------
-
-CHECK_ONLY=0
-if [ "${1:-}" = "--check-only" ]; then
-  CHECK_ONLY=1
-  shift
-fi
-
-MODE="${1:-}"
-[ -n "$MODE" ] || usage
-
-validate_mode "$MODE"
-
-if [ "$CHECK_ONLY" -eq 1 ]; then
-  info "Mode '$MODE' is valid."
-  exit 0
-fi
-
-PROJECT_ROOT="${2:-$PWD}"
-if [ ! -d "$PROJECT_ROOT" ]; then
-  err "Project root does not exist: $PROJECT_ROOT"
-  exit 1
-fi
-cd "$PROJECT_ROOT" || { err "Cannot enter project root: $PROJECT_ROOT"; exit 1; }
-
-if ! command -v jq >/dev/null 2>&1; then
-  err "jq is required to write jenga.config.json but was not found on PATH."
-  exit 1
-fi
-
-# ---------------------------------------------------------------------------
-# ignored — append to .gitignore, without ever duplicating an entry
-# ---------------------------------------------------------------------------
-
-gitignore_append() {
-  local entry="$1"
-  local gitignore=".gitignore"
-
-  if [ -f "$gitignore" ] && grep -qxF -- "$entry" "$gitignore"; then
-    info "'$entry' already present in .gitignore — skipping."
-    return 0
-  fi
-
-  # Don't glue our entry onto a final line that lacks a newline.
-  if [ -s "$gitignore" ] && [ -n "$(tail -c 1 "$gitignore")" ]; then
-    printf '\n' >> "$gitignore"
-  fi
-
-  if ! printf '%s\n' "$entry" >> "$gitignore"; then
-    err "Failed to append '$entry' to .gitignore"
-    exit 3
-  fi
-  info "Added '$entry' to .gitignore"
-}
-
-# ---------------------------------------------------------------------------
-# jenga.config.json — merge the field in, written atomically (temp + mv)
-# ---------------------------------------------------------------------------
-
-write_visibility_config() {
-  local mode="$1"
-  local config="jenga.config.json"
-  local tmp="${config}.tmp"
-  local existing='{}'
-
-  # /init normally runs before any /distribute, so the file usually does not
-  # exist yet. Merge rather than overwrite so other fields survive.
-  if [ -f "$config" ]; then
-    if ! jq empty "$config" 2>/dev/null; then
-      err "$config exists but contains malformed JSON — refusing to overwrite it."
-      exit 4
-    fi
-    existing="$(cat "$config")"
-  fi
-
-  local content
-  content="$(jq --arg v "$mode" '.project_files_visibility = $v' <<< "$existing")"
-  if [ -z "$content" ]; then
-    err "Failed to construct $config content."
-    exit 4
-  fi
-
-  if ! printf '%s\n' "$content" > "$tmp"; then
-    err "Failed to write temporary config file: $tmp"
-    exit 4
-  fi
-
-  if ! mv "$tmp" "$config"; then
-    err "Failed to atomically move $tmp to $config"
-    rm -f "$tmp"
-    exit 4
-  fi
-
-  info "Wrote project_files_visibility = \"$mode\" to $config"
-}
-
-# ---------------------------------------------------------------------------
-# Apply
-# ---------------------------------------------------------------------------
-
-case "$MODE" in
-  visible)
-    info "Mode 'visible' — working files stay in place; nothing to change on disk."
-    ;;
-  ignored)
-    for path in "${JENGA_WORKING_PATHS[@]}"; do
-      gitignore_append "${path}/"
-    done
-    ;;
-esac
-
-write_visibility_config "$MODE"
-
-info "Applied project_files_visibility '$MODE' to $PROJECT_ROOT"