ptc-integrity-si-cli/SKILL.md

PTC Integrity 10.7 CLI (si)

Purpose

Use this skill when working with source code managed by PTC Integrity 10.7, using the si command-line client.

Target version:

PTC Integrity 10.7.0.7930

PTC Integrity is not Git. Do not apply Git concepts or Git commands to an Integrity Sandbox unless the user explicitly states that Git is also being used.

The primary command-line tool is:

si

Core Concepts

Project

A Project is the server-side source configuration managed by Integrity.

Sandbox

A Sandbox is a local working representation of an Integrity Project. It normally contains a project.pj file and working files corresponding to project members.

Member

A Member is a version-controlled file belonging to an Integrity Project. A file existing on disk does not necessarily mean that it is a project member.

Working File

The local filesystem copy of a Member inside a Sandbox. Do not infer Integrity state merely from filesystem permissions or timestamps.

Member Revision

The revision currently selected by the Project. The working file may be based on a different revision.

Lock / Checkout

si co / si checkout checks out a member. Depending on server configuration, checkout normally obtains a lock. Do not assume that making a file writable is equivalent to checking it out.

Change Package

A Change Package (CP) records source changes associated with an Integrity item. Change package identifiers commonly look like 12345:1. Never invent a Change Package ID.

General Rules

1. Prefer si over manipulating Integrity metadata manually.
2. Never modify project.pj.
3. Never delete Integrity metadata manually.
4. Never assume Git semantics.
5. Determine Sandbox context before source-control operations.
6. Inspect state before changing state.
7. Operate on explicitly selected files whenever possible.
8. Avoid recursive operations unless required.
9. Never invent command options.
10. If uncertain about Integrity 10.7 syntax, use local CLI help.

Use:

si <command> --usage

or:

si <command> -?

The locally installed Integrity 10.7 client is authoritative.

Detecting an Integrity Sandbox

Prefer:

si sandboxinfo

When necessary:

si sandboxinfo --cwd=/path/to/directory

Do not use si sandboxinfo --xmlapi; --xmlapi is not available in Integrity 10.7.

A project.pj is an indicator of an Integrity-managed tree, but do not rely exclusively on filesystem inspection.

Read-Only Investigation

Prefer read-only commands while investigating:

si sandboxinfo
si viewsandbox
si projectinfo
si viewproject
si memberinfo
si history
si diff

Use local help when exact options are uncertain:

si viewsandbox --usage
si memberinfo --usage
si history --usage
si diff --usage

Inspecting Members

Before changing a file, determine its Integrity state:

si memberinfo path/to/file
si viewsandbox path/to/file

Determine where relevant:

• whether the file is a Member
• working revision
• member revision
• lock state
• whether the working file changed
• whether a newer member revision exists
• whether the member belongs to a variant/development path

Do not infer these from the filesystem alone.

Viewing Differences

Before overwriting, reverting, or checking in a modified file:

si diff path/to/file

If additional options are required:

si diff --usage

Do not replace this with git diff unless the directory is explicitly also managed by Git.

History

Use:

si history path/to/file

For advanced queries:

si history --usage

Checkout

The common command is:

si co path/to/file

Before checkout, determine:

• whether the file is already checked out or locked
• whether the working file has local modifications
• whether the member revision is current
• whether a Change Package is required

Never invent a Change Package ID.

If unsure:

si co --usage

Editing Files

When a file needs modification:

1. Determine Sandbox context.
2. Determine member state.
3. Check whether checkout/locking is required.
4. Check out the member if appropriate.
5. Modify only the requested files.
6. Review the resulting diff.

Do not automatically resynchronize a modified file merely because it is out of sync.

Check In

The common command is:

si ci path/to/file

Before checking in:

1. Inspect the member state.
2. Inspect the diff.
3. Determine the relevant Change Package.
4. Ensure only intended files are included.
5. Determine the check-in description.
6. Verify that unrelated modifications are not included.

Do not automatically check in changes merely because implementation work is complete. Unless the user explicitly requested a check-in, stop after making and reviewing the working-file changes.

For exact options:

si ci --usage

Change Packages

A CP identifier typically has the form:

ITEM:CP

For example:

4711:1

An option may have a form such as:

--changePackageId=4711:1

but always verify command-specific syntax using:

si <command> --usage

Never:

• invent a CP
• select an unrelated CP merely because it is open
• close a CP without explicit instruction
• create a CP without explicit instruction

Resynchronize

si resync updates Sandbox working files from member revisions:

si resync path/to/file

This command is potentially destructive and may overwrite local working-file changes.

Before resync:

1. Inspect Sandbox/member state.
2. Determine whether working files contain modifications.
3. Inspect important differences.
4. Determine exactly which members will be affected.
5. Avoid recursive resync unless necessary.

If the operation could destroy user changes, obtain explicit user approval.

Before advanced use:

si resync --usage

Resync by Change Package

Features may include:

si resync --byCP ...
si resynccp ...

Do not treat them as interchangeable.

Before use:

si resync --usage
si resynccp --usage

Adding Files

New files created inside a Sandbox are not automatically Integrity members.

Before adding:

1. Confirm the file is intended for source control.
2. Determine the target Project/Sandbox.
3. Determine whether a Change Package is required.
4. Check exact Integrity 10.7 syntax.

Use:

si add --usage

Do not add build output, temporary files, editor backup files, or generated files unless required.

Dropping Members

Dropping a member removes it from the Integrity Project configuration and is destructive.

Before dropping:

1. Verify the target member.
2. Inspect its state.
3. Determine whether local modifications exist.
4. Determine the required Change Package.
5. Obtain explicit user approval if removal was not already explicitly requested.

Check syntax:

si drop --usage

Revert / Discarding Changes

Discarding local changes can cause irreversible data loss. Do not assume Git semantics.

Before using a revert/discard operation:

si revert --usage

Inspect current member state and diff first. If local modifications would be destroyed, obtain explicit user approval unless the user already explicitly requested that those modifications be discarded.

Recursive Operations

Do not automatically use recursive options such as -R.

Before a recursive operation:

1. Determine the Sandbox root.
2. Determine the expected affected scope.
3. Prefer filters or explicit member lists where practical.
4. Inspect the command with --usage.
5. Avoid destructive recursive operations unless explicitly requested.

Selection Files

Integrity may support selection files for commands accepting multiple members, using forms such as:

-F file
--selectionFile=file

Verify support first:

si <command> --usage

--cwd

Integrity commands can operate relative to another working directory. Example:

si <command> --cwd=/path/to/sandbox ...

Prefer --cwd over arbitrary shell cd sequences when it makes command context clearer.

Error Handling

When an si command fails:

1. Preserve the complete error output.
2. Do not immediately retry with destructive flags.
3. Determine whether the failure concerns authentication, Sandbox context, member state, locks, Change Packages, permissions, project ambiguity, development paths, server connectivity, or unsupported options.
4. Query local command help if syntax is involved.

Never solve an Integrity error by deleting project.pj or other Integrity metadata.

Version Compatibility

This environment uses:

PTC Integrity 10.7.0.7930

Do not assume documentation for Integrity 11, Integrity 12, or Windchill RV&S exactly matches this installation.

Newer documentation may help explain concepts, but command-line options must be verified against the installed client.

When there is a discrepancy, the local Integrity 10.7 CLI is authoritative:

si <command> --usage

Safe Investigation Workflow

For an unfamiliar working tree:

pwd
find .. -name project.pj -print
si sandboxinfo
si viewsandbox --usage

For a file that needs modification:

si memberinfo path/to/file
si diff path/to/file

If checkout is required:

si co --usage
si co path/to/file

After modifying:

si diff path/to/file

Do not automatically check in.

Agent Safety Policy

Normally safe for autonomous investigation:

sandboxinfo
projectinfo
viewsandbox
viewproject
memberinfo
history
diff
help / --usage

Commands altering local or server-side Integrity state require additional care:

co / checkout
ci / checkin
add
drop
resync
resynccp
applycp
revert
lock
unlock
createsandbox
dropsandbox

The agent may perform a checkout when clearly necessary for an explicitly requested code modification and doing so does not discard existing work.

The agent must not autonomously:

• destroy local modifications
• drop members
• perform destructive resyncs
• close Change Packages
• create arbitrary Change Packages
• check in unrelated changes
• recursively modify a large project without understanding scope
• suppress safety confirmations merely to make a command succeed

Important Principle

Integrity source-control state is more important than filesystem appearance.

Never reason:

The file exists and is writable, therefore it is safe to edit.

Instead reason:

This is an Integrity Sandbox. Determine the member and working-file state before deciding which operation is appropriate.

When in doubt:

si sandboxinfo
si memberinfo <member>
si <command> --usage

before modifying source-control state.